Agent Grid - Autonomous Agent Discussion & Turn-Taking Protocol

Agent Grid is a turn-based multi-agent discussion protocol over MCP. You start a session, add participants (2 to 10), and the server enforces who can speak at each step, so agents cannot post out of order or race each other.

The core model is event-sourced: every action is appended to a session event log, and derived state is rebuilt from those events. That gives you deterministic turn flow, replayability, and easier recovery when an agent times out or disconnects.

Human-in-the-loop is first-class. Any participant can pause progress with human_request when a hard decision or missing constraint blocks work. The same requester must resolve that request explicitly before normal turn-taking continues.

As the discussion progresses, agents can attach structured artifacts (feature_list, task_breakdown, decision_record) and finalize into a Markdown plan. Session data is persisted locally under ~/.agent_grid/.

What it does

• Deterministic turn-taking: strict post-time enforcement with optional next_speaker override.
• Structured collaboration: messages can include typed planning artifacts (feature_list, task_breakdown, decision_record).
• Human gating: pause on missing constraints, then explicitly resume once a human answer is available.
• Live observability: render and monitor session progress in HTML (render_session_html).
• Local durability: event log + derived state on disk for replay, recovery, and auditability.
• Low orchestration overhead: agents follow a simple loop: wait_for_turn -> message_post -> wait_for_turn.

Why not Bash?

You can coordinate agents with Bash scripts, shared files, and polling loops. That works for trivial flows, but gets brittle fast once multiple agents, retries, and human pauses are involved.

Typical Bash failure modes:

• Turn order is policy, not enforcement.
• State is inferred from logs/text instead of validated structures.
• Every agent has to duplicate wait/retry/timeout logic.
• Recovery after crashes or partial writes becomes custom glue code.

Agent Grid moves those concerns into protocol-level guarantees. wait_for_turn blocks with watch/poll fallback, message_post enforces ordering and blocking rules, and artifacts are validated rather than scraped from free-form text. Agents stay focused on decisions while Agent Grid handles session coordination and durability.

Installation

npm install -g agent-grid

Requires Node.js 20+.

Usage

As an MCP server (recommended)

agent-grid init discovers supported clients and lets you choose which configs to update:

agent-grid init

Currently the CLI supports: Claude Code, Codex, Gemini, OpenCode, Amp Code for direct installation of the MCP server.

To target specific agents:

agent-grid init --clients claude,codex
agent-grid init --all

Or configure manually in your MCP config:

{
  "mcpServers": {
    "agent-grid": {
      "command": "agent-grid-stdio"
    }
  }
}

This gives you the full set of MCP tools: init, wait_for_turn, message_post, join_session, leave_session, read, human_request, finalize_plan, close_session, render_session_html.

Claude Code users: also install the plugin for slash commands and guided workflows — see Plugin below.

As a CLI

agent-grid --help

View a session:

agent-grid view <session-id>           # display history and exit
agent-grid view <session-id> --watch   # display then tail live events
agent-grid view <session-id> --watch --full  # no message truncation

Note: Sessions are stored in ~/.agent_grid/sessions/{session_id}/. The finalized plan is written to ~/.agent_grid/sessions/{session_id}/plan.md.

Plugin

Agent-grid includes a Claude Code plugin in this repository with slash commands and a protocol skill. Note: npm package installs the CLI/MCP server binaries; plugin assets are installed from GitHub/marketplace.

Install the plugin:

npx skills add PraneshASP/agent-grid

Claude plugin:

claude plugin marketplace add PraneshASP/agent-grid

Slash commands:

| Command | Description | | ------------------------------------------------------ | ---------------------------------------- | | /agent-grid:start-discussion [session-id] [topic] | Start a new session | | /agent-grid:join-discussion [session-id] [agent-id] | Join an existing session | | /agent-grid:recover-session [session-id] [agent-id] | Recover a stuck or timed-out session | | /agent-grid:finalize-session [session-id] [agent-id] | Run quality checks and finalize the plan |

Skill: agent-grid-protocol is automatically loaded when Claude uses agent-grid MCP tools. It teaches the turn-taking loop, message quality rules, and exit conditions — no manual invocation needed.

MCP tools

| Tool | Description | | --------------------- | --------------------------------------- | | init | Create or resume a session | | wait_for_turn | Block until it is your turn | | message_post | Post a message (enforces turn order) | | join_session | Add an agent to an active session | | leave_session | Remove an agent from a session | | read | Non-blocking state check | | human_request | Block session pending human input | | finalize_plan | Compile artifacts into a plan and close | | close_session | Close without finalizing | | render_session_html | Generate a live HTML view |

Agent protocol

Every agent must follow this loop:

1. Call wait_for_turn — blocks until it is your turn
2. Call message_post when your_turn: true
3. Immediately call wait_for_turn again
4. Exit only when session_status === "closed" or finalized === true

On wait_for_turn timeout: call read to check state, retry up to 3 times (2s / 5s / 10s backoff). If read fails after all retries, post a final error summary and exit.

Development

pnpm install
pnpm dev       # hot reload
pnpm build     # production build
pnpm start     # run stdio server

Publishing

pnpm build
npm publish --access public