Imported from mariomosca/agent-team-os (AGENTS.md). Install upstream with npx skills add mariomosca/agent-team-os. Copyright stays with the author.

AGENTS.md — Agent Team OS

Entry point for an AI coding agent (Claude Code, etc.) reading this repo. Humans: see README.md and the landing page.

What this is

A file-based protocol to coordinate multiple AI coding-agent sessions (one per project/role/repo) that otherwise can't talk to each other. No daemon, no server — just a folder, a JSON message schema, bash helpers, slash commands, and lifecycle hooks. Runtime lives in ~/.agent-team-os/; the integration (hooks/commands/skill/scripts) is copied into ~/.claude/ by the installer.

Install (one command)

git clone https://github.com/mariomosca/agent-team-os && cd agent-team-os && ./install.sh

install.sh is idempotent: copies the lib + v2 modules + hooks + commands + skill into ~/.claude/, creates ~/.agent-team-os/, and drops a starter AGENT_MAP.json if none exists. It does not touch settings.json (you register hooks yourself — see below). Requires jq.

After install:

1. Edit ~/.agent-team-os/AGENT_MAP.json — map your workspace paths to agent names (+ v2: gods[], per-agent domain/god).
2. Register hooks in ~/.claude/settings.json (next section).
3. Open a session in a mapped workspace; try /inbox or /bus.

Hooks — what to register in settings.json

The Stop hook is copied by the installer but NOT auto-registered — it's a behavioral change that affects all sessions, so activation is explicit and gated.

How an agent uses it (runtime contract)

• Read your inbox: at session start, read every file in ~/.agent-team-os/inboxes/<you>/. After handling a message, move its file to inboxes/<you>/.done/.
• Send a message: use /send <agent> <intent>, or write a message JSON (schema below) — never write into another agent's folder directly; the protocol delivers it.
• Message schema (v1.1): { id, version, from, to, thread_id, in_reply_to, type, intent, priority, delivery, payload, context_refs, requires_response, ts }.
• Reply in-thread: /reply <msg-id> <type> (type = accept|decline|response|confirm).
• Slash commands: /bus (roster), /inbox, /read <id>, /send, /reply, /handoff, /thread.

v2.0 — hive-GOD-agentic (optional layers)

• Dual GOD orchestration: GOD agents (gods[] in AGENT_MAP) orchestrate a domain — they decompose, propose to the human, then dispatch. Contract: docs/agentic-v2/GOD-CONTRACT.md. Semi-autonomous: propose → human confirms → dispatch.
• TaskProvider layer: pluggable task manager per domain (scripts/agent-team-os-taskprovider.sh). ab_task_provider <agent> resolves the provider; ab_task_mapping <provider> returns the declared status/assignee/priority/dependsOn/meetingIngestion mapping. Reference impls: Orbit (side), PMOHub (brandart).
• drain-on-Stop hook: keeps agents from closing with an unhandled inbox (opt-in, above).
• harvest/telemetry: scripts/agent-team-os-harvest.sh <cwd> → token + USD cost per agent from ~/.claude/projects/*.jsonl, per-model pricing.

Key files

Source of truth

The authoritative protocol spec lives in the consumer's PLAN-AGENT-TEAM-OS.md (symlinked at ~/.agent-team-os/PROTOCOL.md). This repo is the distributable implementation.