Agent-CAN Bus

TypeScript LAN service for Agent-to-Agent communication architecture.

This project is only the communication layer:

• agent registration and discovery
• CAN-style numeric node addressing
• frame routing
• ACK / STAT / RES / ERR flow
• request-response waiting by correlation id
• queue, audit, approvals
• MCP bridge for controlling the bus from Codex
• A2A-inspired field model: AgentCard/Skill, Task, Message, Part, Artifact, Status

It does not implement business tools. Weather, filesystem, browser, ERP, MES, CRM, or shell execution must live inside an external agent runtime.

Technical architecture report: docs/technical-architecture.md

Run

pnpm install
pnpm build
pnpm start

Install For Other Machines

After publishing or sharing the package tarball, other machines can install it as a normal npm package.

Global install from npm:

npm install -g agent-can-bus

Default Agent login console:

agent-can-bus

By default this joins http://127.0.0.1:7878 as an Agent, registers on the Bus, receives a CAN ID from the Bus, and opens a small message console. Use agent-can-bus --server to start the main Bus service.

The login flow only asks you to select the local Agent CLI/vendor. It auto-detects common local CLIs such as Cursor Agent CLI, Codex CLI, Claude Code CLI, Gemini CLI, and OpenCode CLI. Bus URL, token, Agent ID, and CAN ID use defaults or environment variables.

The CLI lets you:

• start the main LAN Bus service
• join an existing Bus as an Agent
• select an auto-detected executor/vendor: Cursor Agent CLI, Codex CLI, Claude Code CLI, Gemini CLI, OpenCode CLI, Echo, custom command, or no executor
• register Codex MCP and bundled Agent-CAN skills
• receive an assigned CAN ID from the Bus when you leave CAN ID empty
• list agents and send messages on the Bus after login
• use a slash-command TUI for target switching, workspace context, frame detail, and QA-style output
• show a command palette immediately when / is typed at the prompt

TUI commands:

/agents                  list online/offline agents
/target                  interactively choose an online target
/target auto             use automatic target selection
/target can:5            pin target to CAN ID 5
/id 5                    shortcut for /target can:5
/to can:5 hello          send one message to a specific target
/workspace-path          show current workspace path context
/workspace-path /path    attach a workspace path to outgoing tasks
/mode qa                 show question/answer output only
/mode frames             show transport frames
/detail                  toggle detailed frame JSON
/queue                   show queued frame details
/status                  show current session status
/quit                    exit

Local install from a packed tarball:

npm install -g ./agent-can-bus-0.1.10.tgz

Then register Codex MCP and Agent-CAN skills:

agent-can-setup-codex \
  --bus-url http://127.0.0.1:7878 \
  --token dev-agent-can-token

This writes:

• MCP server id: agent-can-bus
• MCP tools: agent_can_health, agent_can_list_agents, agent_can_request_task, and related bus tools
• Skills: agent-can-bus, agent-can-protocol, agent-can-ops, agent-can-runtime

Restart Codex CLI after setup. Then a user can ask:

用 Agent-CAN 问 can:2：你好

The setup command intentionally runs explicitly instead of as postinstall; installing an npm package should not silently rewrite Codex config.

Package commands:

agent-can-bus
agent-can-server
agent-can-runtime
agent-can-mcp
agent-can-setup-codex

Default endpoints:

• Management UI: http://127.0.0.1:7878/
• HTTP: http://127.0.0.1:7878
• WebSocket: ws://127.0.0.1:7878/ws
• Health: GET /health
• Agents: GET /agents
• Frames: GET /frames
• Request/response: POST /tasks/request
• Queue: GET /queue
• Queue details: GET /queue/details
• Approvals: GET /approvals
• Audit: GET /audit
• A2A card draft: GET /a2a/agent-card

Default development token:

dev-agent-can-token

Use it as Authorization: Bearer dev-agent-can-token, x-agent-can-token, or WebSocket query ?token=dev-agent-can-token.

Runtime Agent

The included runtime agent is a protocol entrypoint. It registers on the bus, accepts TASK frames, immediately returns STAT ack.accepted, then either:

• calls a configured external executor and returns RES
• returns ERR runtime.not_configured when no executor is configured

The bus stays communication-only. Cursor, Codex, Python agents, shell tools, RAG, ERP, MES, CRM, or file access must be connected behind the runtime as external executors.

AGENT_CAN_WS=ws://127.0.0.1:7878/ws \
AGENT_CAN_TOKEN=dev-agent-can-token \
AGENT_ID=runtime_agent \
pnpm agent:runtime

If AGENT_CAN_ID is omitted, the Bus assigns the first available CAN ID and returns it in the registration response.

Echo executor for transport testing:

AGENT_CAN_WS=ws://127.0.0.1:7878/ws \
AGENT_CAN_TOKEN=dev-agent-can-token \
AGENT_ID=runtime_agent \
AGENT_CAN_ID=2 \
AGENT_CAN_EXECUTOR_COMMAND=/bin/echo \
pnpm agent:runtime

Cursor Agent CLI executor:

AGENT_CAN_WS=ws://127.0.0.1:7878/ws \
AGENT_CAN_TOKEN=dev-agent-can-token \
AGENT_ID=remote_runtime_agent \
AGENT_CAN_ID=2 \
AGENT_CAN_EXECUTOR_COMMAND=/home/zeroerr-ai72/.local/bin/cursor-agent \
AGENT_CAN_EXECUTOR_ARGS_JSON='["--print","--mode","ask","--output-format","text","--trust"]' \
AGENT_CAN_EXECUTOR_TIMEOUT_MS=120000 \
pnpm agent:runtime

Request/Response

Submit a task without hand-building a full frame:

curl -X POST \
  -H 'content-type: application/json' \
  -H 'x-agent-can-token: dev-agent-can-token' \
  -d '{"target":"can:2","intent":"agent.message","input":{"message":{"role":"user","parts":[{"kind":"text","text":"hello"}]}},"timeout_ms":10000}' \
  http://127.0.0.1:7878/tasks/request

The bus returns delivery metadata, status frames, and the first matching RES or ERR.

For Codex CLI, use natural language:

用 Agent-CAN 问 can:2：机器人关节有哪些结构和组件？

If the CLI needs an explicit tool instruction:

使用 agent-can-bus 的 agent_can_request_task，target=can:2，intent=agent.message，input.message.role=user，input.message.parts=[{"kind":"text","text":"机器人关节有哪些结构和组件？"}]，timeout_ms=120000

MCP Server

Build first:

pnpm build

Run as stdio MCP server:

AGENT_CAN_HTTP=http://127.0.0.1:7878 \
AGENT_CAN_TOKEN=dev-agent-can-token \
pnpm mcp

MCP tools exposed:

• agent_can_health
• agent_can_list_agents
• agent_can_list_frames
• agent_can_list_queue
• agent_can_list_queue_details
• agent_can_list_approvals
• agent_can_decide_approval
• agent_can_send_frame
• agent_can_request
• agent_can_request_task
• agent_can_a2a_card

LAN Test

Start the bus for LAN access:

AGENT_CAN_HOST=0.0.0.0 AGENT_CAN_PORT=7878 pnpm start

On another machine, start an agent runtime:

AGENT_CAN_WS=ws://<bus-ip>:7878/ws \
AGENT_CAN_TOKEN=dev-agent-can-token \
AGENT_ID=remote_runtime_agent \
AGENT_CAN_ID=2 \
AGENT_CAN_EXECUTOR_COMMAND=/bin/echo \
pnpm agent:runtime

Boundary

The bus must not contain hardcoded business branches or tool calls.

Those belong to real agent runtimes. Agent-CAN only transports frames and records their lifecycle.