ai-team-os

English | 中文

AI Team OS

Shared context, accountable work, native agents.

AI Team OS is a shared operating layer for Claude Code and Codex. Keep tasks, project memory, reports and team messages in one place, and follow work across sessions in one Dashboard. Each host keeps its native agent tools; the OS provides the durable record that makes their work understandable and reusable.

🤝 Codex is supported. Use Codex or Claude Code on its own, or connect both to the same OS task wall, project memory, reports, channels and Dashboard. Codex uses its own MCP and hook configuration; native agent tools, host settings and hook trust remain separate. See the installation and capability sections below for the per-host setup and boundaries.

⚡ v1.16.0 - OS data gets its own directory, and every path follows your Claude Code and Codex config folders. Data moves from inside the Claude Code config folder to ~/.aiteam (AITEAM_DATA_DIR overrides it); an update you start moves it only after seven safety checks pass, and otherwise leaves it in place with a notice. CLAUDE_CONFIG_DIR and CODEX_HOME are respected throughout, and aiteam paths shows what a shell resolves. Codex pricing adds the Ultrafast tier, and codex exec launches from Claude Code are recorded with the tier they requested. Close other Claude Code and Codex sessions before updating; afterwards restart the API and reopen every session; see the changelog.

Full version history: CHANGELOG.md

118 MCP tools · 242 REST endpoints · 24 dashboard pages · 25 agent templates · 42 ecosystem research tools · 30 machine-checked invariants

A session can end without taking the team's context with it. Tasks, memos, decisions and reports remain available to the next authorized session, whether it runs in Claude Code or Codex.

What Carries Across Sessions

Parallel agents are useful only when you can tell who owns the work, what actually happened and where to resume. AI Team OS keeps those answers outside any single chat:

• Tasks and handoffs: ownership, progress memos, blockers and completion records stay on the project task wall.
• Project memory and reports: retrieve earlier decisions and evidence instead of rebuilding context from scratch.
• Team communication: send and read project-scoped messages across hosts, with explicit reader identities and acknowledgements.
• Operational visibility: inspect Leaders, members, tool activity and project-level totals in one Dashboard.

The OS records and exposes the work. Your chosen host runs the agents, and you decide what they are authorized to do.

How It Works

You set the scope. Each root session has its own Leader. A Claude Leader and a Codex Leader can contribute to the same project without pretending to be the same process or sharing host configuration.

1. Resolve the project and read its task wall, relevant memos and memory.
2. Let the session's Leader coordinate authorized work using its host's native agent tools. Members belong to their parent team; Codex's native nicknames stay distinct from roles and task names.
3. Record progress, decisions and reports through the shared MCP tools. Other sessions can pick them up through the same project records and channels.
4. Inspect the Dashboard to compare recorded work with current activity. The observation updates label the host, show only fresh working evidence in current views and fold waiting or historical records away without deleting them.

Claude Code's installed hooks can supply startup briefings and direction-layer context automatically. Codex can read the same records through MCP, with its own adapter handling supported observations. The OS does not replace either host's scheduler, permissions or agent lifecycle.

Core Capabilities

1. Cross-Session Coordination

Shared project records and channels connect sessions while execution stays native to each host:

• One Leader per root session: the implementation combines registered sessions with Claude file observations and labels Claude Leader and Codex Leader explicitly. Native Codex children join the parent team instead of becoming extra Leaders.
• Current work and history: fresh busy evidence drives the current roster; waiting, closed and stale records remain available as history. Unknown source or model information stays unknown.
• Project and worktree visibility: inspect current tasks, observed context and uncommitted work before handing off or continuing a session.
• Cross-host messages: use channel_send, channel_read and channel_wait for explicit communication. A pending wait can return new messages; it does not restart an ended Codex turn.
• Claude Code extensions: the existing fleet path can resume a Claude session for one turn, and installed CC hooks support compaction checkpoints, session-registry observations and background-job visibility. These execution and injection paths are not Codex features.

2. Memory System v2 - Shared Direction and Task History

Keep team preferences and task evidence available across sessions, without relying on a single chat's remaining context.

• Direction layer (user preferences / corrections / design intent, 4 kinds): stored with per-bucket character quotas (global 1200 + 1500 per project + user 300 = 3000 chars, <=400 chars per entry), replacement via supersedes and auditable invalidation rather than deletion. Writes are scanned for invisible characters, instruction-override patterns and credential shapes. Claude Code's SessionStart and SubagentStart hooks inject this context; Codex retrieves the shared records through its configured tools.
• Episodic layer (task_memos ledger): task-level execution memos promoted to a dedicated table (row IDs / invalidation axis / quality score / scope_path), recalled on demand via pure-Python BM25 Chinese retrieval; 123 legacy memos backfilled with zero loss.
• On-demand reconcile (memory_reconcile): zero-LLM BM25 candidate clustering, then merge / invalidate / score / distill on agent confirmation — "the agent computes, the tool persists", with no background resident process introduced.

Surfaces: MCP memory_add / memory_list / memory_invalidate / memory_search / memory_reconcile_candidates / memory_reconcile_apply.

3. Progressive Tool-Loading Governance (new in v1.9.0)

Choose the MCP surface for each client instead of loading every capability into every session.

• alwaysLoad dynamic rotation: at session start a single SQL recomputes the hot-tool whitelist by 7-day real call frequency (>=2-day span gate against bursty spikes + 20% hysteresis, hard cap <=5), and CC skips ToolSearch for them. Not additive, not hand-tuned; any stats failure silently degrades to all-defer, and every whitelist is logged for audit.
• AITEAM_TOOLSETS group switch: 17 capability-domain toolsets; a startup env var decides which modules register. default core profile = task/team/memory/infra/reports/notices (30 tools, hard cap <=50), with incremental default,ecosystem - fits non-CC clients that cap tool counts.
• AITEAM_READONLY read-only profile: an orthogonal overlay that strips every write tool by explicit allowlist and keeps only read tools — ideal for audit / observer sessions.
• 6 Claude Code templates declare least privilege: meeting-facilitator / debate advocate & critic / technical-writer / project-manager / tech-lead carry disallowedTools entries for destructive OS tools (delete project, delete team, restart API). Claude Code 2.1.281 enforces them for both project- and user-level definitions (verified 2026-09-25); older versions may treat them as declarations only. Codex uses its own native permission controls rather than interpreting CC template fields.

4. Claude Code Workflow / ultracode Observability (v1.7.0)

The OS does not intercept CC's built-in ultracode/Workflow — it becomes its persistent governance layer. Every Workflow run is automatically tracked into the OS, with no manual team setup:

• Auto-tracking: a hook turns each Workflow run into an OS "team" (workflow-<wf_id>) the moment it starts
• Dashboard /workflows: a live feed of run cards, a phase swimlane timeline, and per-agent telemetry — tokens / duration / status / tool-call counts, advancing live via incremental journal tailing while a run executes
• Calibrated stall detection: the stall threshold was calibrated on 3,378 real agent intervals (p99 = 77.6s, longest healthy silence 173.8s) and set at 5.2× the worst healthy case — it flags late rather than crying wolf
• Project-detail integration: workflow team rows carry an inline run summary (status / agent count / duration / finish time) plus a "view swimlane" deep link; members display semantic phase labels (e.g. audit:sourceA) instead of ids
• Claude Leader file observations: the backend can supplement registered Leaders with session, model and liveness observations from Claude's local records. Codex identity follows its separate native metadata path.
• MCP tools: workflow_list (browse runs), workflow_get (full archive + per-agent rows), workflow_reconcile (repair from on-disk snapshots after the OS was offline)
• Self-healing ingestion: hook receipt anchors + on-disk snapshot reconciliation + a reaper backstop close offline gaps automatically — finished runs on disk are ingested idempotently; cross-project attribution matches the on-disk path slug against registered projects

5. Ecosystem Research Platform — 42 tools

A project-isolated knowledge base that accumulates research findings over time. Each repo progresses through 4 stages (a progressive funnel, since v1.5.0), with token-efficient triggers and append-only history:

• Stage 0 — Auto shallow-summary on archive: newly-archived repos automatically get a 200-400 char ai-engineer summary (core function / positioning / advantages). 8-class failure handling with self-learning hooks (3+ same-class fails surface through self_learning_pending; the queue exposes recorder/searcher injection points you can wire to your own lesson store)
• Stage 1 — On-demand architecture analysis: user picks research direction ("memory_system") → batch-dispatch backend-architect agents to read architecture key files
• Stage 2 — Multi-perspective debate: triggers existing debate_start (NOT a built-in debate engine — reuses meeting system)
• Stage 3 — Reference / Integrate marking: mark_as_reference adds tag for future quick recall; start_integration triggers existing task_create for actual implementation
• Active vs Full dual-view: data is append-only forever. Stars-falling repos kept (just is_active=False); stars climbing back auto-promotes + re-queues Stage 0