| name | codegrid-agent-bus |
| description | How to collaborate with other AI agents running in CodeGrid using the codegrid-agent-bus MCP tools (list_agents, read_pane, message_agent). Use this skill whenever the user asks you to delegate to, consult, coordinate with, review with, hand work to, or get a second opinion from another agent ("ask Codex to…", "have Gemini review…", "get the other agent to…", "split this up between the agents"). Covers the read→message→read protocol, identifying agents, orchestration patterns (delegate, review, pipeline, parallel fan-out, monitor, debate), etiquette, scope/safety, loop prevention, failure recovery, and worked end-to-end examples. |
| metadata | {"product":"CodeGrid","vendor":"ZipLyne LLC","homepage":"https://codegrid.app/agent-bus","docs":"https://codegrid.app/docs/agent-bus","version":2} |
Collaborating with other agents in CodeGrid
You are running inside CodeGrid, where multiple coding agents (Claude,
Codex, Gemini, Cursor, Grok, shells) run side by side, each in its own pane. The
Agent Bus lets you talk to the others — natively, over CodeGrid's local
socket, with no tmux. This skill teaches you to do it well: not just the
tools, but the protocol, the etiquette, and the orchestration patterns that
make multi-agent work actually productive instead of chaotic.
Core principle: you are an orchestrator, not a spammer. Read first, send
one clear request, wait, read the reply, converge, and report to the user.
1. Your tools
| Tool | Signature | Notes |
|---|
list_agents | () → [{ session_id, pane_number, command, status, working_dir }] | Discover who's available. command tells you the role (claude/codex/gemini/cursor/grok/…). status ∈ running, idle, waiting, error, dead. |
read_pane | (session_id, max_bytes?) → text | Recent output, ANSI-stripped, ~last 40 lines. Always safe — read freely. |
message_agent | (session_id, text, submit?) → ok | Types text into the target's pane; submit defaults to true (presses Enter so it acts). Set submit:false to stage a draft without sending. |
The session_id is the address. Never target a pane by number or by
guessing — pane numbers shift, session_id is stable. Get it from list_agents.
2. The protocol — read → message → read
Every interaction follows the same loop. Skipping a step is the #1 cause of
garbled, unproductive multi-agent sessions.
- List.
list_agents → find the target by role (its command) and grab
its session_id. Confirm it isn't dead.
- Read first.
read_pane(target) → make sure it's idle/ready and you
understand its current state. Don't talk over a busy agent.
- Message once.
message_agent(target, text) with a clear, self-
contained request. Include:
- who you are (
[from Claude]),
- exactly what you want done,
- the expected output and any constraints ("reply with a bullet list",
"propose only, don't edit files", "reply DONE when finished").
- Wait, then read. Give the agent time to think and work. Re-
read_pane
after a pause to collect the reply. If it's still working, read again —
do not send another message.
list_agents() → target = the "codex" pane, session acc7bc6d-…
read_pane(acc7bc6d-…) # idle, ready
message_agent(acc7bc6d-…,
"[from Claude] Review src/auth.ts for security issues. Reply with a short
bullet list of findings, ranked by severity. Do not edit any files.")
… wait …
read_pane(acc7bc6d-…) # collect the findings
→ report to the user / act on them
3. Identifying agents
- By role: match the
command field — claude, codex, gemini,
cursor-agent, grok. If several panes share a role, disambiguate by working_dir
or pane number, then keep using the session_id.
- Yourself: you usually appear in
list_agents too. Don't message yourself.
- No other agents? If the list shows only you, there's nobody to collaborate
with — tell the user to open another agent pane (
⌘N) and stop.
4. Orchestration patterns
Delegate (hand off a task)
You stay the lead; another agent does a unit of work.
read_pane(codex) → message_agent(codex, "Implement X. Reply DONE + a summary.")
→ poll read_pane(codex) until DONE → verify → report.
Review / second opinion
Finish your own change, then have another model critique it.
message_agent(gemini, "Review this approach: <paste/describe>. List risks and a
better alternative if you see one. Don't change files.") → read → apply judgment.
Pipeline (chained hand-offs)
Specialize roles; each hand-off is its own read→message→read.
Gemini researches the API → you implement → Codex reviews the diff.
Parallel fan-out + gather
Kick off independent subtasks on different agents, then collect.
message_agent(codex, "Do subtask A. Reply DONE-A when finished.")
message_agent(gemini, "Do subtask B. Reply DONE-B when finished.")
… periodically read_pane each … gather both results → synthesize.
Use git worktrees (one per agent) so parallel file edits don't collide.
Monitor
Watch a long-running build/test/shell pane and react.
read_pane(shell) → if it shows a failing test, fix it (or delegate the fix).
Debate / consensus (use sparingly)
Ask two agents the same question, compare, and you decide. Cap it at one round
each — do not let them argue back and forth unbounded (see §6).
5. Etiquette & scope safety
- One message, then wait. Multiple messages before a reply interleave into
the target's input box and corrupt it. Patience beats spam.
- Be explicit about scope. Many agents run in autonomous / YOLO mode and
will act on whatever you send — including editing files or running commands.
If you only want analysis, say "propose only — do not edit files or run
anything." If you want action, say so and define "done."
- Hand off context, not just a command. The other agent doesn't share your
conversation. Include the file paths, the goal, and constraints in the message.
- Prefer
read_pane when unsure. Observing is always safe; messaging changes
another agent's state.
- Use
submit:false when you want to place text for the user to review/edit
before it runs.
- Respect the user's machine. Don't instruct another agent to run
destructive commands (
rm -rf, force-push, credential access) on your own
initiative.
6. Loop & runaway prevention (critical)
Multi-agent setups can ping-pong forever or fork-bomb work. Guard against it:
- Converge and report. Your job is to reach a result and tell the user —
not to keep two agents talking indefinitely.
- If an agent might message you back, don't reflexively reply. Decide whether
another round adds value; usually it doesn't.
- Bound debates to one round per side.
- Don't spawn unbounded helpers. Delegate to existing panes; don't create new
agents in a loop.
- Set a step budget in your own head (e.g. "at most 3 hand-offs"); if you're
not converging, summarize the state for the user and ask how to proceed.
- Detect stalls. If
read_pane shows no progress after a reasonable wait,
re-read once more, then report "agent X appears stuck" rather than nagging it.
7. Failure modes & recovery
| Signal | Meaning | Do |
|---|
| "Can't reach CodeGrid" | App not running / socket gone | Stop; tell the user CodeGrid must be open. |
list_agents shows only you | No collaborators | Tell the user to open another agent pane (⌘N). |
message_agent errors | Wrong/dead session_id | Re-run list_agents; the pane may have closed. |
Target status: dead | Process ended | Don't message it; tell the user (they can Restart the pane). |
| Reply never appears | Agent is busy, waiting on a prompt, or off-track | Re-read_pane once; if it's stuck on a prompt, report it — don't keep sending. |
| Garbled input in the target | You sent multiple messages | Stop; let it settle; read; resend one clean message. |
8. Anti-patterns (don't do these)
- ❌ Messaging before reading the target's state.
- ❌ Firing several messages in a row "to be safe."
- ❌ Addressing by pane number instead of
session_id.
- ❌ Sending a bare command with no context or success criterion.
- ❌ Letting two agents converse with no termination condition.
- ❌ Telling another agent to do something destructive on your own initiative.
- ❌ Assuming the other agent shares your memory/conversation.
9. Worked example — delegate + review
User: "Have Codex add an Export button, then check its work."
1. list_agents()
→ me (claude, pane 1), codex (acc7bc6d-…, pane 2, idle)
2. read_pane(acc7bc6d-…) # idle, at a prompt — ready
3. message_agent(acc7bc6d-…,
"[from Claude] In this repo, add an 'Export' button to the toolbar that
downloads the current view as JSON. Implement it and reply 'DONE' with a
one-line summary of the files you changed.")
4. … wait ~20–40s …
read_pane(acc7bc6d-…) # "DONE — added ExportButton.tsx, wired onClick"
5. (optional) read the changed files yourself / git diff, apply a fix if needed.
6. Report to the user: what Codex did, your review, and the final state.
10. Combining with other CodeGrid features
- Broadcast (
⌘B) is you → all panes. The bus is agent → agent. Use
broadcast to fan a prompt out from yourself; use the bus to let agents
coordinate among themselves.
- Worktrees keep parallel agents on separate branches — pair them with
fan-out so simultaneous edits never conflict.
- For full control of the workspace (spawning panes, opening folders, the raw
socket), see the companion
using-codegrid skill.
Reference: https://codegrid.app/docs/agent-bus.
