teamo

The shared brain between teammates' AI coding agents.

Two developers. One feature. Two different harnesses (Claude Code, Codex, Cursor...). teamo gives every agent the same brief, an explicit slice of the work, and a live feed of teammates' decisions — enforced at edit time, so an agent physically cannot write code with stale knowledge of what the other is doing.

   Mamoun                          Ahmed
┌─────────────────┐          ┌─────────────────┐
│  Claude Code    │          │     Codex       │   ← keep your harness
├─────────────────┤          ├─────────────────┤
│  teamo MCP      │          │  teamo MCP      │   ← shared brain
│  + pre-edit hook│          │  + pre-edit hook│     (brief, assignment,
└────────┬────────┘          └────────┬────────┘      decision ledger)
         └───────────┬───────────────┘
              .teamo/ (SQLite + git mirror)

The problem it kills

You and Ahmed build a navbar, 3 links each. Without teamo: both AIs build the whole navbar, Mamoun's picks #3B82F6 + NavBar.tsx, Ahmed's picks a slightly different blue + Navbar.jsx — duplicate work and merge hell, because neither AI knows the other exists.

With teamo:

1. teamo start "navbar with 6 links" → invite code; teamo join <CODE> for Ahmed
2. teamo plan splits units (Mamoun: home/about/contact · Ahmed: pricing/blog/login) and ratifies a contract: NavBar.tsx, NavLink, tailwind, #0EA5E9
3. Both agents start from the identical brief (teamo_get_brief)
4. When one agent decides anything, it announces it — the other agent receives it before its next edit (pre-edit hook), adapts, and moves on
5. Same decision key twice? First write wins; the loser is told whose decision to adopt

Quickstart (npm)

Requires Node 22.13+ (uses the built-in node:sqlite; zero native deps).

cd /path/to/your-project

# mamoun
npx teamo-ai@latest init                 # .teamo/, .mcp.json, Claude hook, AGENTS.md
npx teamo-ai@latest start "navbar with 6 links" --name mamoun --harness claude-code
#   → code like X7K2AB

# ahmed
npx teamo-ai@latest join X7K2AB --name ahmed --harness codex

# split the work and lock conventions
npx teamo-ai@latest plan \
  --assign mamoun=home,about,contact \
  --assign ahmed=pricing,blog,login \
  --files mamoun=src/nav-left/** \
  --files ahmed=src/nav-right/** \
  --contract contract.json        # { "component": "NavBar.tsx", "tokens": { "primary": "#0EA5E9" }, ... }

npx teamo-ai@latest ratify --level session --by mamoun

# during the session
npx teamo-ai@latest status               # who's doing what, recent decisions
npx teamo-ai@latest announce "primary color #0EA5E9" --key nav/colors.primary -t file:src/** token:colors.primary
npx teamo-ai@latest catch-up             # what your teammates decided since you last looked

Then open your harness as usual. The agent picks up the teamo tools via .mcp.json and the working rules via AGENTS.md; the pre-edit hook is already installed in .claude/settings.json.

npm install
alias teamo='npx tsx packages/cli/src/cli.ts'    # from the teamo monorepo root
teamo init && teamo start "..."                  # same commands as above

What teamo init installs

| File | Purpose | |---|---| | .teamo/teamo.db | the coordination plane (SQLite, WAL) — sessions, contracts, ledger | | .teamo/local.json | your identity in this clone (hook + MCP read it) | | .teamo/projects/**/ledger.jsonl | git-mirrored ledger: async transport + audit | | .mcp.json | registers the teamo MCP server (6 tools) with your harness | | .claude/settings.json | PreToolUse hook on Edit/Write/MultiEdit → runs the pre-edit check | | AGENTS.md | prompt contract so agents use the tools correctly |

The MCP tools (what your agent sees)

• teamo_get_brief — shared task context + ratified conventions + team roster + your slice
• teamo_my_assignment — units you own, files you may edit, units owned by others
• teamo_changes_since — new teammate events relevant to you (optionally scoped to paths you're about to edit)
• teamo_announce — publish a decision/intent/done; key + expected_version give first-write-wins (on conflict you get the winner and are told to adopt it)
• teamo_ask — ask the team a question
• teamo_heartbeat — presence

The guarantee

The hook is enforcement, not a suggestion: before each edit it checks the ledger for teammate events overlapping that file and denies the edit once, injecting the updates into the reason — the model re-plans with fresh knowledge and retries. Delivery is exactly-once per event (cursor advances on read), your own events are never echoed back, and any hook failure fails open (never block work on infra).

Packages

| Package | What it is | |---|---| | packages/core | schema (workspace→project→session hierarchy, day-1 scale bake-ins), ledger engine (first-write-wins, monotonic versions), scope filter (glob-based relevance), contract merge, brief compiler | | packages/mcp | MCP server over stdio | | packages/cli | teamo CLI + the standalone pre-edit hook (packages/cli/hook/hook.mjs, zero-dep) | | packages/server | optional WebSocket relay: presence + instant event fan-out (teamo-server) |

Development

npm install
npm test          # unit (core) + integration (scripted navbar test through the real hook & MCP stdio)
npm run typecheck

The integration test is the product invariant: mamoun announces a decision → ahmed's edit is denied once with the decision injected → retry allowed; and the real MCP server serves brief/announce/conflict correctly.

Honest scope (v0.1)

• MVP coordination is per-clone (two terminals on one checkout, or a shared filesystem). Cross-machine realtime comes with the hosted relay (server package is the seed); the git-mirrored ledger already gives async teammates catch-up via replay.
• Claude Code hooks are first-class; other harnesses work via the MCP tools + AGENTS.md contract (hook adapters next).
• teamo merge (worktree → PR ritual) and the planning agent pass are M3.

Docs: VISION.md (what & why) · PLAN.md (the full plan) · RESEARCH.md (landscape).

License: MIT