mcp server

agent-interface-protocol

Zero-infrastructure multi-agent orchestration via tmux + filesystem. 11 CLI backends, one MCP server, zero dependencies beyond the MCP SDK.

dev-boz/agent-interface-protocolcommunitylistedunreviewed

Use tool

Set up

Runs on your computer. Pick your agent and operating system.

Before you start

uv (`curl -LsSf https://astral.sh/uv/install.sh | sh`)

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "agent-interface-protocol": {
      "command": "uvx",
      "args": [
        "agent-interface-protocol"
      ]
    }
  }
}

same format Cursor, GitHub Copilot CLI, Junie, JetBrains AI Assistant, Augment (Auggie CLI), Factory Droid, Kiro, Devin CLI +12

Values in angle brackets are placeholders. Restart Claude Desktop after editing its config.Claude Desktop docs

README

synced Oct 25, 2026

Agent Interface Protocol (AIP)

Status: Work in Progress — the core works and currently has 213 passing tests, plus 9 opt-in live checks that stay skipped by default. Contributions, feedback, and new backend adapters are very welcome.

Provider-agnostic multi-agent orchestration with near-zero infrastructure. tmux handles process management, inter-process communication, and session persistence. A shared MCP server and filesystem workspace handle coordination. LLMs can already parse each other's natural-language output, so protocol normalization between agents may be unnecessary.

The Idea

Instead of...	AIP uses...
Message broker	tmux server (shared memory)
Agent framework	bash + tmux commands
Custom protocol	Agents read each other natively (LLMs as parsers)
Service discovery	`tmux list-windows`
Database for state	Filesystem with atomic `mv`
SSE streaming	tmux pane buffers
HTTP transport (remote)	SSH
Observability	`workspace/events.jsonl` (append-only log)

Architecture

tmux server "aip"
├── window 0: orchestrator (any CLI agent)
├── window 1: coder (claude/gemini/aider/etc)
├── window 2: reviewer (any CLI agent)
└── ...spawned and killed as needed

workspace/
├── summaries/          ← agent output summaries (markdown)
├── status/             ← agent status files (JSON, merge semantics)
├── tasks/              ← task queue (atomic claiming via mv)
│   ├── pending/        ← unclaimed tasks
│   ├── claimed/        ← in-progress (agent-name prefixed)
│   ├── done/           ← completed
│   ├── failed/         ← move back to pending/ to retry
│   └── packets/        ← persisted IMX task packets
├── transcripts/        ← normalized session transcripts
├── gates/              ← file-backed review / advisor exchange
├── locks/              ← resource lock files
├── route-requests/     ← AIP → IMX routing requests
├── route-decisions/    ← IMX → AIP routing outcomes
├── dream-candidates/   ← gitmem Dream ingestion candidates
├── events.jsonl        ← append-only event log
└── agent_tree.json     ← teammate hierarchy and parent/child links

Heartbeat files (HEARTBEAT-{agent}.md) and presence sentinels ({agent}.present) live at the workspace root so liveness stays inspectable even without reading pane buffers.

File-Backed Routing Seam

AIP can now emit IMX-ready routing artifacts directly from its MCP/runtime surfaces:

request_task can persist a full task_packet at workspace/tasks/packets/{task_id}.json and store the packet reference on the queued task.
request_route writes workspace/route-requests/{task_id}.json, always produces a minimal compatible task packet, and can merge richer packet fields such as budgets, worktree metadata, memory refs, and chain_depth.
IMX can consume those files with imx route-aip and write the resulting decision back to workspace/route-decisions/{task_id}.json.

Three-Tier Memory

Tier	Storage	Access	Survives Restart
Hot	tmux pane buffers	`tmux capture-pane`	No (rolling window)
Event log	`workspace/events.jsonl`	`tail -n 50`	Yes
Cold	workspace files (summaries, status, tasks, routing artifacts)	`cat`	Yes

Read Hierarchy (Token Efficiency)

Always check in this order — never jump to pane reads when structured data exists:

Level	Command	Cost	When
1	`tail -n 20 workspace/events.jsonl`	~50 tokens	What happened?
2	`cat workspace/status/coder.json`	~20 tokens	Who's doing what?
3	`cat workspace/summaries/coder-0317.md`	~100 tokens	What did they produce?
4	`read_pane(incremental=true)`	~20 tokens	What's changed since last check?
5	`tmux capture-pane -pt aip:coder -S -5`	~30 tokens	Quick peek (last 5 lines)
6	`tmux capture-pane -pt aip:coder -S -20`	~100 tokens	More context
7	Full pane read	~1000+ tokens	Almost never needed

Quick Start

pip install -e .

# Initialize workspace and tmux session
aip init --ensure-session

# Spawn an agent
aip agent spawn coder "gemini"

# Read what the agent is doing
aip agent capture coder

# Send it a task
aip agent send coder "implement the auth module"

# List all agents
aip agent list

See examples/two-agent-review.sh for a full two-agent scenario you can run in under a minute (no API keys needed).

Supported Backends

AIP currently has adapters for 11 CLI agents across two integration tiers:

Backend	Tier	Hook Config	Notes
Claude Code	Tier 1 (native)	`.claude/settings.json`	Hooks + MCP
Copilot	Tier 1 (native)	`.github/copilot/hooks.json`	Hooks + MCP
Gemini	Tier 1 (native)	`.gemini/settings.json`	Hooks + MCP
Kiro	Tier 1 (native)	`.kiro/agents/{name}.json`	Hooks + MCP
Codex	Tier 1 (native)	`.codex/hooks.json`	Hooks + MCP
OpenCode	Tier 1 (native)	Plugin events	MCP, manual hook wiring
Cursor	Tier 1 (native)	`.cursor/settings.json`	Hooks + MCP
Qwen	Tier 1 (native)	`.qwen/settings.json`	Hooks + MCP
Kilo	Tier 1 (native)	Plugin events	OpenCode fork
Vibe (Mistral)	Tier 2 (shim)	`aip-shim` intercept	MCP + shim watcher
Amp	Tier 2 (shim)	`aip-shim` intercept	MCP + shim watcher

Adding a new backend is one of the easiest ways to contribute — see CONTRIBUTING.md.

What's Next

AIP is usable today for local multi-agent workflows, but there's plenty of room to grow:

PyPI publish — installable via pip install agent-interface-protocol
More end-to-end examples — real-world scenarios beyond the demo script
aip dashboard — live multiplexed view of all agents working in real time
Additional Tier 2 shims — Windsurf, Cline, Aider, and other CLIs without native hooks
ACP/A2A compatibility layer — optional flag to emit ACP-formatted events alongside file writes
Remote multi-machine orchestration — SSH-based workspace sync across hosts
IDE extension (VSIX) — integrate AIP transparently into VS Code, Cursor, Windsurf

If any of these interest you, open a discussion or grab a good first issue.

Installation

One runtime dependency: the mcp SDK. Everything else is Python stdlib.

git clone https://github.com/dev-boz/agent-interface-protocol.git
cd agent-interface-protocol
pip install -e .          # installs `aip` and `aip-mcp` commands
pip install -e '.[dev]'   # also installs pytest for development

Requirements: Python 3.10+, tmux.

Development

python -m pytest tests/ -q

Optional live suites:

AIP_RUN_LIVE_TMUX=1 python -m pytest -q tests/integration/test_live_core.py
AIP_RUN_LIVE_TMUX=1 AIP_RUN_LIVE_CLI=1 python -m pytest -q tests/integration/test_live_backends.py

The suite currently spans 213 passing tests, plus 9 opt-in live checks that stay skipped by default, covering workspace primitives, queue and lock behavior, routing artifacts, hook normalization, MCP tools, CLI commands, multi-backend collaboration, and live tmux/CLI coverage. See CONTRIBUTING.md for details.

Documentation

License

MIT