agent-conductor

Hook-based traffic control for humans conducting multiple AI coding agents — plus a library of reusable Claude Code skills.

Quick start

npx github:Analyst-creeator/agent-conductor

That launches the interactive setup wizard — a big gradient banner, then three questions: which skills to install (all preselected), where they should live (~/.claude/skills globally, or this repo's .claude/skills), and optionally which hook tools to wire into the current repo. Arrow keys to move, space to toggle, a for all, enter to confirm.

 ▄████  ▄███▄  █▄  █ ███▄  █   █  ▄████ █████  ▄███▄  ████▄
 █      █   █  ██▄ █ █  ▀█ █   █  █       █    █   █  █   █
 █      █   █  █ █▄█ █   █ █   █  █       █    █   █  ████▀
 █      █   █  █  ██ █  ▄█ █   █  █       █    █   █  █  █
 ▀████  ▀███▀  █   █ ███▀  ▀███▀  ▀████   █    ▀███▀  █   █
  agent-conductor — skills + traffic control for AI coding agents

◆  Which skills do you want to install?
│  ❯ ◼ caveman                        Ultra-compressed communication mode
│    ◼ diagnose                       Disciplined diagnosis loop for hard bugs…
│    ◼ tdd                            Test-driven development with red-green-refactor…
└  ↑↓ move · space toggle · a all · enter install · esc cancel

Non-interactive (CI, dotfiles, scripts):

npx github:Analyst-creeator/agent-conductor skills              # list the library
npx github:Analyst-creeator/agent-conductor add all --global    # → ~/.claude/skills
npx github:Analyst-creeator/agent-conductor add tdd handoff --project   # → <repo>/.claude/skills
npx github:Analyst-creeator/agent-conductor remove caveman --global

The skills library

Thirteen battle-tested skills, extracted from daily multi-agent work on a production codebase:

Skill	What it does
caveman	Ultra-compressed communication mode (~75% fewer tokens)
diagnose	Disciplined diagnosis loop: reproduce → minimise → hypothesise → instrument → fix
grill-me	Relentless plan interview until every branch of the decision tree is resolved
grill-with-docs	Grilling that also sharpens terminology and updates CONTEXT.md / ADRs inline
handoff	Write / resume / archive AI session handoff documents
improve-codebase-architecture	Find module-deepening opportunities informed by domain language + ADRs
prototype	Throwaway prototypes to flush out a design — terminal app or N UI variants
tdd	Red-green-refactor with interface-design and mocking guidance
to-issues	Break a plan/PRD into independently-grabbable tracer-bullet issues
to-prd	Turn the current conversation into a PRD on the issue tracker
triage	Issue triage as a state machine driven by triage roles
write-a-skill	Create new skills with proper structure and progressive disclosure
zoom-out	Force the agent to zoom out and give the higher-level picture

Skills are plain directories (SKILL.md + optional support files) — read them before installing, edit them after. add is idempotent; re-running replaces cleanly.

---

The hook tools

Hook-based traffic control for humans conducting multiple AI coding agents.

When you run several Claude Code sessions at once — same repo, sibling clones, background agents — the failure mode is never the code. It's the traffic: two agents editing the same file, one agent git stash-ing over another's half-finished work, clones silently drifting until a merge explodes, a new session starting blind to what the last five did.

agent-conductor is a small catalog of hook tools that give your agents peripheral vision. Each tool is a single short script wired into Claude Code's lifecycle hooks (UserPromptSubmit, PostToolUse, Stop, SessionStart, PreToolUse). No daemon, no service, no dependencies — just git, node ≥ 18, and files you can read in two minutes.

Every one of these exists because the incident it prevents actually happened.

Install hook tools

Run inside the repo you want to protect (or pick them in the wizard above):

npx github:Analyst-creeator/agent-conductor list             # see the catalog
npx github:Analyst-creeator/agent-conductor install all      # or name tools
npx github:Analyst-creeator/agent-conductor status
npx github:Analyst-creeator/agent-conductor doctor           # self-test installed hooks
npx github:Analyst-creeator/agent-conductor snapshots        # browse turn snapshots
npx github:Analyst-creeator/agent-conductor uninstall git-rails

install copies the tool scripts into .claude/hooks/agent-conductor/ and merges their hook entries into .claude/settings.json (idempotent — re-installing replaces cleanly). Commit both so every clone and teammate gets them. Hooks go live at the next session start (or reload via /hooks).

---

The catalog

1. claims-radar — cross-session collision warnings

What. Every time any session edits a file, a claim is logged. Every time any session receives a prompt, it's told which files other sessions touched in the last 30 minutes:

⚠ claims-radar: another agent edited src/pages/ReviewPage.tsx 4m ago — coordinate before touching it.

How. PostToolUse on Edit|Write records {time, session, path}; UserPromptSubmit reports foreign claims. Claims are keyed by the repo's origin URL and stored outside the repo (~/.claude/agent-conductor/), so multiple local clones of the same remote share one radar — exactly the setup where collisions hurt most.

Why it's great. Merge conflicts are collisions detected hours late. The radar moves detection to the moment before the second agent starts typing — when coordination is still free. It's the difference between "two agents rewrote the same component and a human untangled it" and "agent B said: that file is claimed, I'll work around it."

Config: git config conductor.claimsWindow 45 (minutes, default 30).

2. git-rails — destructive git commands need a human

What. When an agent tries git reset --hard, git clean -f, git stash/pop, git push --force, or a branch switch, the command stops and asks you first, with the reason spelled out:

git-rails: stash/pop in a tree other sessions edit causes conflicts in files
you don't own — prefer a temporary git worktree for baselines.

How. A PreToolUse hook on Bash inspects the command and returns permissionDecision: "ask" (or "deny" if you set git config conductor.rails deny). Everything else passes through untouched, with zero latency for non-git commands.

Why it's great. These five commands share a property: they rewrite a working tree that, in a multi-agent shop, is shared mutable state. An agent's judgment about them is only as good as its awareness of the other agents — which is exactly what it lacks. Rails convert "agent judgment" into "human judgment, one click". The incident this encodes: an agent stashed/popped around a test run while a second agent was editing, and the pop left conflict markers in files neither of them owned.

Config: git config conductor.rails ask|deny|off.

3. sync-guard — anti-drift heartbeat and self-healing main

What. Three jobs on every interaction:

1. Heartbeat — stamps busy (prompt) / idle (turn done) into .git/conductor-session-state. Your release/sync automation reads it and refuses to commit or move files under a live session.
2. Convergence — kicks a background fetch (at most every 5 min, never blocks your prompt) and, when the clone's main is clean and strictly behind, fast-forwards it immediately and tells the agent to re-read changed files.
3. Early warning — dirty-and-behind or diverged mains get a visible warning injected into the session, and a configurable lock file lets your orchestration tell every session to stand down while it runs.

Why it's great. Conflicts need a divergence window. Most tools shrink it at integration time; sync-guard shrinks it at prompt time, which for an AI agent is dozens of times per hour. Clean clones simply stop drifting. And the heartbeat inverts the usual race: instead of automation hoping no session is mid-turn, sessions continuously publish whether they are.

Heartbeat contract for your scripts: content busy|idle, freshness = file mtime; treat busy fresher than ~45 min as "do not touch this tree".

Config: conductor.main, conductor.autoff false, conductor.lockfile /path/to/lock.

4. turn-snapshots — a rewind point after every agent turn

What. After each completed turn, the entire working tree — including untracked files — is snapshotted as a commit object under refs/conductor/turns/<timestamp>. No branch moves, no index change, no working-tree mutation, no stash-list noise. Newest 40 kept.

git for-each-ref refs/conductor/turns               # list rewind points
git diff refs/conductor/turns/20260702-2140         # what changed since
git checkout refs/conductor/turns/20260702-2140 -- src/foo.ts   # restore one file

How. A Stop hook builds a tree with a throwaway index (GIT_INDEX_FILE + git add -A + git write-tree), wraps it in a commit parented on HEAD, and stores a ref. Deduplicates: an unchanged tree costs nothing.

Why it's great. Agents are confidently wrong at machine speed, and "what did the tree look like two turns ago?" is unanswerable exactly when you need it. This gives every turn an undo point for ~zero cost, in plain git — no proprietary format, works with every git tool you already know.

5. session-journal — agents brief each other automatically

What. Every completed turn appends one line — time, clone, branch, diffstat, hottest paths — to a journal shared across all clones of the same remote. Every new session opens with the tail injected:

recent agent activity (session-journal):
  2026-07-02 21:40  backend  main  6 files changed, 312 insertions(+)  app/core/storage.py …
  2026-07-02 22:05  UI       main  2 files changed, 58 insertions(+)   src/pages/ReviewPage.tsx …

How. Stop records (deduplicating idle turns, capped at 200 lines); SessionStart briefs. Same outside-the-repo, keyed-by-origin storage as claims-radar.

Why it's great. The most expensive thing a fresh agent session does is rediscover context. A human-written handoff is great but costs discipline; the journal is the ambient version — written by machines, for machines, with zero human effort. Fresh sessions stop stepping on yesterday's work because they've read about it before their first tool call.

---

Beyond Claude Code: Codex, Copilot, Gemini CLI, Qwen Code, Grok …

The tools are runtime-agnostic; only the wiring differs. There are two integration tiers, and it's worth being honest about the difference:

Tier	Runtimes	Guarantee
Harness-enforced hooks	Claude Code	The runtime itself fires the tools — agents cannot forget or skip them
Protocol + CLI verbs	Codex, Copilot, Gemini CLI, Qwen Code, Grok, anything that reads AGENTS.md	The agent is instructed to run the tools — compliance is very good with modern models, but it's cooperation, not physics

For the second tier, every tool is exposed as a plain CLI verb any agent can shell out to:

npx github:Analyst-creeator/agent-conductor radar            # foreign-claim warnings
npx github:Analyst-creeator/agent-conductor claim src/x.ts   # announce an edit
npx github:Analyst-creeator/agent-conductor snapshot         # tree rewind point
npx github:Analyst-creeator/agent-conductor journal brief    # read recent agent activity
npx github:Analyst-creeator/agent-conductor guard            # drift check + heartbeat

And install --runtime <name> writes a coordination-protocol block into the instructions file that runtime reads on every session — telling the agent when to run which verb, and which git commands need a human:

npx github:Analyst-creeator/agent-conductor install --runtime codex     # → AGENTS.md
npx github:Analyst-creeator/agent-conductor install --runtime copilot   # → .github/copilot-instructions.md
npx github:Analyst-creeator/agent-conductor install --runtime gemini    # → GEMINI.md
npx github:Analyst-creeator/agent-conductor install --runtime qwen      # → QWEN.md
npx github:Analyst-creeator/agent-conductor install --runtime grok      # → GROK.md
npx github:Analyst-creeator/agent-conductor install all --runtime claude,codex,gemini   # mix freely

The block is delimited by markers and refreshed in place on re-install. Claims, journal, and snapshots share the same storage in both tiers — so a Claude Code session and a Codex session in the same repo (or sibling clones) see each other: Claude's hook-recorded edits show up on Codex's radar and vice versa. That cross-runtime visibility is the point.

Attribution tip for tier-two agents: set a stable CONDUCTOR_SESSION env var per agent (e.g. CONDUCTOR_SESSION=codex-1) so claims are attributed to the right session; the fallback is per-terminal granularity.

How the pieces compose

• claims-radar prevents collisions within the divergence window.
• sync-guard shrinks the window itself and publishes busy/idle so your own sync/release scripts can respect live sessions.
• git-rails guards the commands that turn a small mess into a big one.
• turn-snapshots make any surviving mess reversible.
• session-journal makes the next session smarter than the last.

A practical baseline for a multi-agent repo: install all, then set git config conductor.rails ask semantics free of charge and wire your sync automation to the heartbeat contract.

Safety and scope

• Hooks are shell commands your own session runs — read the scripts (each is < 120 lines) before installing, like anything else you pipe into your toolchain.
• Everything degrades to a no-op outside a git repo, on read errors, or on missing config. All hook commands are wrapped in || true — a broken guard never blocks your work.
• State lives in .git/ (never committed) and ~/.claude/agent-conductor/ (never inside a repo). uninstall removes exactly what install added.

License

MIT © Analyst-creeator