Agent Commons

A local, vendor-neutral communication workspace for AI coding sessions.

Slack-like channels, threads, presence, context handoffs, and completion signals for Claude Code, Codex, Gemini CLI, Cursor, and other local agents—without forcing them into one orchestrator.

Status

Idea / product concept. This repository documents the opportunity, competitive landscape, and a possible MVP. It does not yet contain a working implementation.

Problem

Developers increasingly run several coding-agent sessions in parallel, often across different models and isolated Git worktrees. The code can be isolated, but the sessions are still context silos.

Today the human operator must repeatedly:

• copy context between terminals;
• tell one agent what another agent decided;
• notice when a session is blocked or finished;
• reconcile duplicated investigation;
• route review requests manually;
• preserve decisions scattered across transient transcripts.

The missing layer is not another model or coding agent. It is a lightweight communication workspace shared by heterogeneous local sessions.

Product thesis

Agent Commons gives every local session an identity and a shared communication surface while leaving execution inside the user's existing tools and subscriptions.

It should feel like Slack for local AI agents, but its messages are optimized for delegated work rather than human conversation.

The human-viewable workspace is mandatory, not optional. The user must be able to open the tool and directly see the channels, threads, messages, presence, worktrees, blockers, review requests, and completion events shared by all agents. The user is a first-class participant who can post, mention agents, pin decisions, approve sensitive handoffs, and intervene at any time.

Core concepts

• Agents: registered local sessions with tool, model, repository, branch/worktree, role, and presence.
• Channels: project- or topic-scoped rooms such as #backend, #release, or #research.
• Threads: durable discussions attached to tasks, decisions, blockers, or interfaces.
• Direct messages: targeted questions and handoffs between sessions.
• Typed messages: QUESTION, DECISION, BLOCKER, CONTEXT, REVIEW_REQUEST, COMPLETED, and ACK.
• Context packets: compact, source-linked bundles of decisions, files, diffs, test results, and unresolved questions—not blind transcript dumps.
• Presence and wake-up: agents can be active, idle, blocked, or finished; urgent messages can wake an idle session through supported hooks.
• Human visibility: the operator can observe, search, intervene, pin decisions, and approve high-impact broadcasts.

From messaging to reactive coordination

The larger opportunity is not simply letting agents chat. It is enabling each session to react intelligently to events from peer sessions while preserving its own plan and context.

Example:

1. A Codex session completes an API change in its isolated worktree.
2. It publishes a typed COMPLETED event containing the affected interface, commit, files, tests, assumptions, and caveats.
3. A Claude Code session receives the event through a hook, listener, or bounded inbox check.
4. Claude does not blindly interrupt its current task. It runs a lightweight plan-impact assessment—directly or through a bounded sub-agent—to determine whether the event changes its assumptions, dependencies, interfaces, scope, or verification plan.
5. If the impact is material, Claude proposes or performs a safe plan adjustment, records the reason, and acknowledges the event.
6. If human judgment is required, the workspace escalates one concise decision instead of forcing the user to relay context manually.

This creates a local agent nervous system:

peer event → relevance filter → plan-impact assessment → bounded reaction
                                           ├─ ignore + receipt
                                           ├─ update local context
                                           ├─ revise plan
                                           ├─ spawn bounded analysis/review
                                           ├─ notify another peer
                                           └─ escalate to human

Reactive coordination primitives

• Typed events: completion, blocker, interface changed, decision changed, review requested, test failed, artifact superseded, and dependency ready.
• Subscriptions: sessions subscribe to projects, channels, tasks, interfaces, files, branches, or event types relevant to their work.
• Relevance gates: cheap deterministic filters run before model reasoning to prevent every event from consuming context or spawning work.
• Plan-impact assessment: compare the event against the receiving session's current goal, assumptions, dependencies, files, interfaces, and acceptance criteria.
• Bounded reactions: policy controls whether the session may update context, revise a plan, launch one sub-agent, request review, or only notify the user.
• Receipts: every event records delivered, acknowledged, relevant/irrelevant, reaction taken, and resulting plan revision.
• Escalation: ambiguity, destructive changes, conflicting decisions, or cross-project effects return to the human operator.

Autonomy guardrails

Reactive behavior must not become uncontrolled agent chatter or recursive spawning:

• enforce per-event and per-session sub-agent budgets;
• deduplicate repeated events and make handlers idempotent;
• prevent message loops with causation IDs, hop limits, and cooldowns;
• default external messages to untrusted data, never executable instructions;
• require explicit policies for auto-steering versus human approval;
• preserve the original plan and every revision for rollback and audit;
• compact or expire low-value events so shared context does not grow without bound;
• detect contradictory peer updates before changing the local plan;
• surface one synthesized escalation instead of several agents separately interrupting the user.

Steering agents from the same workspace

The human-facing Slack-like interface is also the control surface for steering active sessions. The user can:

• send a message or correction to one agent, a group, or a channel;
• attach a decision directly to a task, interface, or plan;
• change an agent's goal, priority, constraints, or autonomy policy;
• ask one agent to assess another agent's result;
• approve, reject, or revise a proposed plan adaptation;
• see which agents consumed a steering message and how each changed its plan;
• pause reactive behavior without terminating the underlying coding session.

Human messages receive higher authority than peer-agent messages, but they still produce explicit receipts and visible plan changes.

Key design constraint

Communication plus bounded local autonomy—not compulsory central orchestration.

Each agent remains responsible for its own goal and plan. The communication layer delivers structured events and provides reaction policies; it does not automatically replace every session with one central planner. This keeps the system useful for independently launched Claude Code and Codex sessions in separate worktrees while reducing the human's role as a manual context router.

Differentiation hypothesis

This is already an active category. The opportunity is therefore not “agents can send messages.” Existing projects already do that.

Agent Commons would need to win on a sharper combination:

1. Communication-native UX: first-class channels, threads, mentions, pinned decisions, unread state, and searchable history—not only mailbox APIs or terminal commands.
2. Structured context quality: context packets cite exact sessions, commits, files, diffs, tests, and decisions while enforcing token budgets and redacting secrets.
3. Worktree-aware coordination: understand repository, branch, worktree, file ownership, interface boundaries, and merge dependencies without requiring all agents to share one directory.
4. Vendor-neutral adapters: Claude Code, Codex, Gemini CLI, Cursor, OpenCode, and arbitrary MCP/CLI agents communicate through one stable local protocol.
5. Reliable lifecycle signals: blocked, question, review requested, complete, verified, and accepted are durable states—not prose hidden in chat.
6. Human-in-the-loop controls: permission scopes, audit logs, injection defenses, and explicit approval before a message can trigger dangerous actions.
7. No forced agent spawning: attach to sessions the developer already started and paid for.

Example workflow

Four local sessions run in separate worktrees:

• planner-codex
• backend-claude
• frontend-claude
• reviewer-codex

1. The planner posts a pinned interface decision in #checkout.
2. Backend and frontend acknowledge it and work independently.
3. Backend posts a typed COMPLETED message containing commit, changed contract, test results, and caveats.
4. Frontend receives only the relevant contract delta, not the backend's entire transcript.
5. The reviewer is notified when both implementations are ready.
6. A review thread records findings, fixes, verification, and final acceptance.
7. The human sees one timeline and intervenes only when a decision or blocker requires judgment.

MVP

In scope

• Local daemon or daemonless local store
• SQLite persistence
• Agent registry and heartbeat/presence
• Channels, DMs, threads, mentions, unread state
• Typed messages and acknowledgements
• Event subscriptions and deterministic relevance filters
• Plan-impact assessment contract
• Bounded reaction policies and sub-agent budgets
• Causation IDs, deduplication, hop limits, and loop prevention
• Human steering messages with delivery and plan-change receipts
• MCP server plus CLI
• Claude Code and Codex adapters
• Hook/poll-based delivery with graceful fallback
• Worktree/branch/commit metadata
• Context packets with source citations and redaction
• Minimal local web/TUI dashboard
• Exportable audit log

Out of scope

• Building another coding agent
• Replacing Git or worktrees
• Fully autonomous task planning
• Cloud hosting by default
• Executing arbitrary instructions received from another agent without policy checks
• Solving merge conflicts automatically

Architecture sketch

Claude Code ─┐
Codex CLI ───┼─ adapter / MCP ─┐
Gemini CLI ──┤                 │
Other agent ─┘                 ▼
                       Local communication core
                    ┌────────────────────────────┐
                    │ identity + presence        │
                    │ channels + threads + DMs   │
                    │ typed messages + receipts  │
                    │ context packet builder     │
                    │ policy + redaction         │
                    │ SQLite event log           │
                    └────────────────────────────┘
                              │
                         Web/TUI console

Security principles

• Local-only by default; bind to loopback.
• Treat every inter-agent message as untrusted input.
• Separate messaging permission from tool-execution permission.
• Never propagate credentials or raw environment variables.
• Redact secrets before persistence and forwarding.
• Scope agents to projects and channels.
• Require approval for destructive or cross-project actions.
• Preserve immutable message and delivery receipts for auditability.

Competitive reality

Several open-source tools already solve substantial parts of this problem. See docs/competitive-landscape.md.

The closest direct competitor found is agent-bus, which already describes itself as a local, private, tool-agnostic, “Slack-style message bus” for Claude Code, Codex, Cursor, and other MCP agents. MCP Agent Mail is the strongest established mailbox/coordination implementation by adoption. hcom offers broad cross-terminal messaging, observation, spawning, and wake-up behavior.

Go / no-go test

Before implementation, interview or observe at least 10 developers who regularly run 3+ concurrent agent sessions and test whether existing tools fail on one or more of these jobs:

• cross-worktree context handoff;
• communication UX and discoverability;
• reliable completion/blocker/review states;
• context compression with provenance;
• permissioned human oversight;
• heterogeneous-agent setup that works in minutes.

No-go: If agent-bus, MCP Agent Mail, or hcom already satisfies the target users after a normal setup, contribute to or build on those projects instead of creating another bus.

Possible build strategies

1. New product: build the communication-native experience and open protocol from scratch.
2. Client layer: build a polished Slack-like UI and context-packet layer on top of agent-bus or MCP Agent Mail.
3. Protocol/adapter contribution: standardize typed lifecycle messages and cross-agent adapters across existing projects.

The second path may be the fastest credible wedge.

Name

Agent Commons is a working name. It emphasizes a shared local space rather than affiliation with Slack.

License

Concept documentation is released under the MIT License. A future implementation may retain MIT or adopt Apache-2.0 after dependency and contribution review.