Agent Bus

agent-bus

Turn your Claude / Codex / Cursor / Gemini sessions on the same machine into a local agent team. Each session registers a name, then you can send messages, ask blocking questions, delegate tasks, broadcast to channels, message scoped teams, route work by capability/role, track agent status, record decisions and memories, record task progress, generate session briefs, and produce merge-readiness reports — all through one SQLite file at ~/.agent-bus/bus.db.

This skill is the coordinator playbook: when the user speaks naturally, you translate their intent into agent-bus tool calls.

Setup check (do this first)

Before using any bus tools, run scripts/check-setup.sh. If it exits non-zero, halt and show the user the install hint it printed. Do not try to use the bus until the check passes. If the user asks you to fix the setup, run scripts/check-setup.sh --install-cli; it installs or upgrades @agent-bus-connect/cli@latest through npm, then rechecks.

If mcp__agent-bus__register is not in your available tools, the MCP server is not wired into this session. Tell the user to add it — the exact command varies by client; the README at has each.

Identity

This session is the coordinator. At the start of any bus interaction:

1. Call register with a stable name and a concrete team. Ask the

user once for any missing name or team, then reuse both for the rest of the session. Default the name to the user's first name or a short tag they choose, but do not invent a team. Pass replace=true, team=, and capabilities ["human-driven", "coordinator"] plus up to ten relevant native powers such as tool:websearch, tool:shell, mcp:posthog, skill:flowdeck, or subagent:Explore. Capabilities are exact-match tags: mcp:posthog does not match posthog. Do not register without a team. If register returns scope_summary / suggested_next_actions, follow the teaser. In particular, call session_brief before taking work when it mentions pinned handoffs, pinned risks, open tasks, or recent decisions.

1. Call directory if available, otherwise whois, and show the user

who else is on the bus, with their capabilities, in one compact line: on the bus: helper-a [review, verify; idle], helper-b [docs; working]. If nobody else is registered, say so.

1. Do NOT enter a listener loop. You are the active driver — only

check inbox when the user asks or when you've just done an ask that needs the result surfaced. When checking inbox in a team workflow, pass your concrete team.

Translating natural language into bus calls

The user speaks normally. You pick the tool. Common patterns:

| When the user says… | You call… | |---|---| | "Ask the reviewer / a reviewer to check X" | ask_best(capability="review", question=…) if they describe a role; ask(to=, …) if they named a specific agent | | "Get a second opinion on X" | ask_best(capability="review" or "verify", …) | | "Have someone research / find / look up X" | ask_best(capability="research", …) | | "Have someone summarize the docs for X" | ask_best(capability="docs" or "summarize", …) | | "Ask the UI team / backend team / team X" | ask_team(team=, question=…); add capability or role if the user wants a specialist inside that team | | "Tell the team X" / "message everyone on " | send_team(team=, message=…) | | "Show team chat" / "watch the conversation" | If using CLI, run agent-bus team-chat --team or agent-bus team-chat --team --watch; with MCP, use recent(team=) and render only that team scope | | "Listen only to my team" / "keep checking this team" | inbox(agent=, team=, wait_s=110, claim_s=300); use inbox_status(agent=, team=) for non-consuming checks | | "Wait for this thread" / "only watch this conversation" | inbox(agent=, team=, thread_id=, wait_s=110); with CLI use agent-bus team-chat --team --thread or agent-bus wait --agent --team --thread | | "Wake me when a message arrives" | Explain that MCP cannot wake an idle model session by itself; use agent-bus wait --agent --team --notify, a Claude listener hook, or a host automation | | "Inbox is too large" / "message got truncated" | Use inbox_previews(agent=, team=), then get_message(message_id=…, team=, include_content=false) or fetch one full message only when needed | | "Delegate this to a helper" or "tell someone to…" | send(to=, message=…). Don't block; tell the user you dispatched it. | | "Ask to do X" | ask(from=, to="", question=…) only if they are online/listening and the user needs the answer now; otherwise ask_async(from=, to="", question=…) | | "Send a message: X" | send(from=, to="", message=…) | | "What did say?" / "Did anyone reply?" | inbox_status(agent=) first when you need state without consuming; inbox(agent=) when you are ready to process messages | | "Why did nobody answer?" | message_status(message_id=…) or why_no_reply(message_id=…); summarize delivery, claim, recipient presence, related task, and next actions | | "Who's around?" / "Who's listening?" | whois() rendered cleanly | | "Remove this member" / "delete this agent" | remove_agent(name=…); if it returns AGENT_HAS_ACTIVE_TASKS, show the active task ids and ask before using release_tasks=true | | "Delete this team" / "remove team " | delete_team(team=…, project/area as appropriate); if it returns TEAM_HAS_ACTIVE_TASKS, show the active task ids and ask before using release_tasks=true | | "Wait for these workers" / "Are my agents ready?" | wait_for_agents(names=[…]) and report ready/missing/stale/wrong-scope | | "Show the team board" / "what is everyone doing?" | team_board(team=…) when a team is named; otherwise project_board() rendered with status, active work, review queue, conflicts, pinned risks, handoffs, and next actions | | "What happened recently?" / "show activity" | activity(project/area/team as appropriate) and summarize the chronological timeline | | "What should I do next?" / "show cockpit" | cockpit(project/area/team as appropriate) and report waiting items, ready items, blockers, and suggested next actions | | "Remember X" / "Note that X" | remember(by_agent=, kind="summary", content=…); use pinned=true for handoffs | | "Recall X" / "What did we decide about X" | list_memories() and list_decisions() first; use ask_best(capability="memory", …) only if needed | | "Give me a handoff / session brief" | session_brief() | | "Catch me up on the bus" | recent(limit=20) and render | | "Track this as a task" / "Open a task to do X" | create_task(requested_by=, title=…, description=…, mode=…, expected_output=…, file_scope=…); set ack_required when assigned and review_required for implementation work | | "Put this idea in backlog" / "Save this for later" | create_task(requested_by=, title=…, description=…, state="backlog", milestone=…); backlog tasks are visible but not claimable/blocking until promoted | | "Start this backlog item" / "Promote task X" | update_task(agent=, task_id=…, state="open", priority=…); then assign/delegate or let workers claim_best_task | | "Park task X" / "Move this back to backlog" | update_task(agent=, task_id=…, state="backlog"); this clears active holder/pending assignee fields | | "Delegate this to " / "Assign this to " | Prefer delegate(from=, to_agent=…, title=…, description=…, mode=…, expected_output=…, edit_scope=…); if the task already exists, use assign_task(task_id=…, to_agent=…); use allow_pending_agent=true when the worker is not registered yet | | "Delegate this to the team" / "assign this to everyone on " | delegate_team(from=, team=, title=…, description=…, mode=…, expected_output=…, edit_scope=…); add capability, role, or max_recipients when the user wants only matching members | | "What's on the task list?" | list_tasks() and render the active ones | | "Show the Kanban board" / "show done tasks" | If using CLI, run agent-bus kanban / agent-bus done; with MCP, use list_tasks() filtered by state and render the same columns | | "Did accept the task?" | get_task(task_id=…) and inspect acknowledged_at / acknowledged_by; ask for acknowledge_task if missing | | "Wait for this task" / "Any progress on task X?" | wait_for_task(task_id=…, wait_s=110) when you can block, otherwise task_result(task_id=…) | | "Review / approve this task" | submit_review(reviewer=, task_id=…, approved=…); required reviews gate completion | | "Hand this task to " | handoff_task(from_agent=, task_id=…, to_agent=…, reason=…, memory=…) | | "Can these agents edit the same files?" | check_scope_conflicts(file_scope=[…]) before assigning overlapping edit work | | "Record progress / update phase" | record_task_event(by_agent=, task_id=…, event_type="progress", message=…, phase=…) | | "What are you working on now?" / "mark current work" | now(agent=, task_id=…, phase=…, note=…) when updating your own visible status/task phase | | "Move task X to testing / review / done" | With MCP, use update_task plus record_task_event; with CLI, use agent-bus task-testing, agent-bus task-phase review, or agent-bus task-done | | "Show what happened on this task" | task_result(task_id=…) and summarize task, events, test evidence, memories, and thread messages | | "Cancel this task" | cancel_task(agent=, task_id=…, reason=…) | | "Record that tests passed/failed" | record_test_result(by_agent=, command=…, status=…) | | "Put to sleep" / "wake " | sleep_agent(agent=…) / wake_agent(agent=…) | | "Set blocked / waiting for review" | set_agent_status(agent=…, status=…) | | "Record this decision…" | record_decision(by_agent=, decision=…, rationale=…) | | "Final merge report" | review_gate() first, then final_report(); render blockers, warnings, implemented work, gaps, risks, tests, and safe-to-commit/push flags |

When to choose ask vs send

• ask (synchronous, blocks up to 110s) — when the user is

waiting for the answer to continue and the recipient is online/listening. It fails fast for stale/paused recipients.

• ask_async (non-blocking question) — when the answer can arrive

later or presence is uncertain. It returns the ask id and next actions immediately; check inbox_status, message_status, or why_no_reply later.

• send (fire-and-forget) — when the user wants to delegate and

keep working. Tell them it's dispatched; offer to check the inbox on demand.

• delegate / delegate_team (tracked long work) — when ownership, progress,

acknowledgement, review, file scope, or final evidence matters. Use it instead of ask for work that can outlive one 110s timeout.

• Board-visible work must be a task. send, send_team, ask, and

ask_team are messages only; they do not create open_tasks or active_tasks on project_board / team_board. If the user expects work to appear on a board, use delegate_team for team-wide work, delegate for one known worker, or create_task + assign_task.

• Ideas belong in backlog. Use state="backlog" for future ideas,

deferred risks, and options discovered mid-session. Backlog tasks show on Kanban and session briefs but are ignored by claim-best routing and merge safety until a coordinator promotes them to open.

Delivery vs attention

Agent Bus is a durable local queue, not a pager. Messages are stored and will be visible next time the recipient checks the bus, but MCP alone cannot start another model session's next turn.

Attention comes from one of these:

• A session currently inside inbox(wait_s); directory/whois show it

as listening.

• Claude Code's listener/Stop hook re-entering the inbox loop.
• A background CLI waiter such as

agent-bus wait --agent worker-a --team frontend --notify.

• A host automation or the human prompting the idle session.

If you wait twice and get no new message, stop blind polling. Check directory/whois, inbox_status, and task state, then tell the user whether the target is listening, online-but-idle, stale, or paused.

When to choose a specific name vs ask_best

• Specific name — user named the helper ("ask helper-a", "send

reviewer"). Use ask/send directly.

• Role / capability — user described a skill ("a reviewer", "the

researcher", "someone who knows the schema"). Use ask_best and let the bus route. If ask_best fails with UNKNOWN_AGENT, surface the error verbatim — the user may want to spin up a helper.

• Area / project — by default, routing and reads stay in the current

repo-derived project and .agent-bus.json area. Use area: "*" or project: "*" only when the user asks for cross-area/global routing.

• Team — if agents are registered with team, prefer ask_team,

send_team, or team_board when the user names that workgroup. Use team: "*" only when the user wants cross-team routing.

How to talk while calling tools

Be transparent in ONE short line before each call:

> Asking helper-a (review): "is the token refresh race-free?"

Not:

> I will now invoke the agent-bus MCP ask_best tool with the > parameter capability set to "review"...

When a reply lands, render it in plain English for the user. Don't dump JSON. The user wants the answer, not the message envelope.

User-visible bus status

Do not leave the user staring at a silent bus wait. When you call ask, ask_best, ask_team, wait_for_task, or intentional inbox(wait_s) in an active user-facing session:

• Before waiting, say who or what you are waiting on in one short line.
• When the answer or task evidence arrives, immediately say:

Got 's answer: . Continuing locally with .

• After receiving the needed answer, stop waiting on the bus. Continue

the local task in this session unless the user explicitly asked you to keep listening.

• If the wait times out but diagnostics show the task is still active,

say that clearly: No reply yet, but task #N is still active; I will continue with what I have / check again only if needed.

• Do not chain repeated inbox, inbox_status, message_status, or

why_no_reply calls just because one bus interaction completed.

Example:

Asking verifier for the export risk check.
Got verifier's answer: the main risk is canvas scale parity. Continuing locally by updating the test plan.

Project, area, and team addressing

By name still works (send / ask are direct addressed). ask_best, directory, recent, and task reads default to the current project/area/team. If the user asks broadly ("any reviewer anywhere"), pass project: "*", area: "*", and/or team: "*" intentionally.

For multi-folder repos, use areas to prevent accidental chatter. Agents working in one area should normally route to agents in the same area. A coordinator at the repo root can use area: "*" to see or route across all areas when the user wants cross-area coordination.

Use teams when multiple groups share the same project or area but should mostly coordinate among themselves, such as ios-ui, api, review, or a temporary feature squad. Team is neutral metadata; it does not create roles, prompts, or behavior rules.

Manager workflow defaults

• Use project_board() as the task board: show idle, working,

blocked, waiting_review, sleeping, active tasks, review queue, scope conflicts, pinned risks, handoffs, and suggested next actions.

• Use team_board(team=…) when the user is managing one workgroup

inside a broader project.

• When creating tasks, set mode conservatively:

investigate_only for analysis, propose_patch for patch sketches, edit_files only when edits are intended, and test_only for verifier sessions.

• Set expected_output so replies are comparable. Prefer:

Summary / Files inspected / Findings / Suggested fix / Risks / Test plan / Confidence. -

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: MustaphaSteph
• Source: MustaphaSteph/agent-bus-plugins
• License: MIT

Install and usage instructions live in the source repository linked above.