🎮 MC‑CC

Play Minecraft while your Claude Code agents work.

A client‑side Minecraft 26.2 Fabric mod that bridges herdr into the game, so you can watch your Claude Code agents, get pinged when one is blocked or done, read the conversation, and reply — all without alt‑tabbing out of Minecraft.

---

⚠️ This mod does nothing on its own — it requires herdr + Claude Code

MC‑CC is a bridge, not a standalone tool. It reads and controls agents that are already running inside herdr, and it renders conversation history straight from Claude Code's on‑disk transcripts. Without both of these set up and running, the mod loads but shows an empty list.

You need all of the following on the machine running your Minecraft client:

Requirement	Why	Notes
herdr, running, with agents	The mod talks to herdr's local socket (~/.config/herdr/herdr.sock) to list agents, read output, subscribe to status, and send input.	This is the hard dependency. No herdr → nothing to show.
Claude Code agents inside herdr	Rich features (conversation history, the last‑message preview, the Claude:/You: rendering) read Claude Code's ~/.claude/projects/**/*.jsonl transcripts.	Other agent types appear in the list and can be replied to, but history falls back to raw terminal scraping.
Minecraft 26.2 + Fabric Loader ≥ 0.19.3 + Fabric API	It's a Fabric mod for 26.2 (unobfuscated era).	Client‑side only — no server install needed.
Java 25	Minecraft 26.2 runs on Java 25.	Your launcher profile for 26.2 should already use it.

💡 herdr rolls every agent up to 🔴 blocked / 🟡 working / 🔵 done / 🟢 idle with zero config — MC‑CC just surfaces that inside Minecraft and lets you act on it.

---

✨ Features

• In‑game notifications — a colored chat ping + toast + sound when an agent becomes 🔴 blocked (loud, "needs you"), 🔵 done (soft chime), or 💥 errors. Pre‑existing state at startup is seeded silently, so you don't get spammed on launch.
• Last‑message context — each notification is preceded by up to 3 short gray lines of the agent's most recent message, so you know what it wants before you tab in.
• /cc chat UI — a clickable, colored agent list right in chat. Each agent shows its workspace · tab name (herdr's own labels) with [reply] and [history] you can click.
• Conversation history — /cc history <agent> renders the real Claude Code conversation (markdown: bold, code, headings, bullets; tool calls hidden) with You: / Claude: labels.
• Reply from Minecraft — focus an agent and type in chat; your message is sent straight to it (and submitted). Normal chat stays normal when you're not in reply mode.
• Ambient HUD peek — a dim one‑line preview of what a working agent is currently saying, top‑left, refreshed every couple seconds.
• The [K] screen — a classic list/detail screen is still there if you prefer it to chat.

Keys & commands

Input	Does
/cc or /cc status	Clickable, colored agent list
/cc history <agent>	Dump that agent's recent conversation to chat
/cc focus <agent> / /cc unfocus	Enter / leave reply mode
/cc reply <text…>	One‑off message to the focused agent
N	Open chat pre‑filled with /cc
B	Toggle reply mode for the top blocked agent
K	Open the list/detail screen

All keybinds are rebindable in Options → Controls → MC‑CC.

---

📦 Install

1. Install Fabric Loader for Minecraft 26.2 and the Fabric API mod (0.153.0+26.2 or newer).
2. Download mccc-<version>.jar from the Releases page.
3. Drop it into your mods/ folder (e.g. ~/.minecraft/mods/).
4. Make sure herdr is running with at least one agent.
5. Launch Minecraft (Java 25). Type /cc in a world.

Because it's client‑side only, it works in singleplayer and on any multiplayer server — the server never needs the mod, and /cc is a client command that's never sent to the server.

---

🔌 How it works

 Claude Code agents          herdr (multiplexer)              MC-CC (this mod, in your MC client)
 ─────────────────           ───────────────────              ──────────────────────────────────
  claude / codex / …  ─────▶  ~/.config/herdr/herdr.sock  ◀──▶  HerdrClient  (JSON-RPC over the
        │                     pane.list / pane.read /            Unix socket, background threads)
        │                     send_text / send_keys /                 │
        ▼                     events.subscribe                        ▼  events → tick thread
  ~/.claude/projects/**/*.jsonl  ───────────────────────▶  AgentRegistry → notifications + HUD
        (conversation transcripts, read for history & previews)        │
                                                                       ▼
                                                        chat UI · [K] screen · reply (send_text)

The transport layer (mccc.herdr) is deliberately isolated from Minecraft — all socket I/O runs on background threads and hands events to the client tick thread through a concurrent queue, so the game never blocks on herdr.

---

🛠️ Build from source

Requires a JDK 25 on your PATH (the Gradle daemon must run on 25).

git clone https://github.com/pisanvs/mc-cc.git
cd mc-cc
./gradlew build          # jar lands in build/libs/mccc-<version>.jar
./gradlew runClient      # launch a dev client with the mod

Stack: Java 25 · Fabric Loom 1.17 · Gradle 9.5.1 · Mojang official mappings (26.x is unobfuscated — no Yarn) · Fabric API 0.154.0+26.2.

---

🧭 Known limitations

• No error/crash status from herdr. herdr's agent_status is only idle/working/blocked/done/unknown, so the 💥 error tier is wired up but not yet driven — it needs a pane‑exit signal. PRs welcome.
• Reply‑mode footgun on servers. While reply mode is on, your chat goes to the agent, not to other players. The green echo + → <agent> HUD tag are there to remind you; B / /cc unfocus / Esc get you out.
• Local herdr only. The mod talks to the herdr socket on the same machine as your MC client. Remote herdr (herdr --remote) isn't wired up yet — but the isolated transport layer makes it a small addition.

---

🤝 Contributing

PRs welcome! This started as a "play Minecraft while vibecoding" experiment and there's lots of low‑hanging fruit:

• drive the 💥 error tier from a pane‑exit / process signal
• richer markdown rendering, images, or diffs in /cc history
• support for remote herdr and multiple herdr sessions
• per‑agent notification filters, quiet hours, sounds
• non‑Claude agent transcript adapters

Open an issue to discuss, or just send a PR. Keep the isolation rule intact: mccc.herdr, mccc.core, mccc.config, and mccc.claude must not import any Minecraft/Fabric class (there's a test that enforces it).

---

📄 License

MIT — do whatever you like.

_{Not affiliated with Mojang, Anthropic, or herdr. Built for fun. 🧱🤖}