AI Team OS: Persistent Multi-Agent Coordination Layer for Claude Code and Codex

The Cross-Session State Problem AI Team OS Addresses

An AI coding session ends and the context disappears. A new session on the same project starts with no knowledge of what the previous session decided, which tasks it completed, or what was blocked. In a single-agent workflow, this is a context-management problem. With multiple parallel agents working on the same codebase, it becomes a coordination problem: two agents can own the same task, write conflicting changes, or report contradictory decisions.

AI Team OS stores the shared record outside any single session. Tasks and handoffs live on a project task wall. Project memory and reports persist in a PostgreSQL database. Team messages use project-scoped channels with explicit reader identities and acknowledgements using the MCP tools channel_send, channel_read, and channel_wait. A channel_wait call can return when new messages arrive; the README notes it does not restart an ended Codex turn. A React dashboard exposes current activity, registered sessions, and tool usage, so a new session can read the current state before doing any work.

Project and worktree visibility is also part of the coordination surface: before handing off or continuing a session, an agent can inspect current tasks, observed context, and any uncommitted work in the worktree. This matters for multi-agent projects where one agent is mid-way through a change when a second session starts.

The system does not replace the AI's native tooling. Claude Code continues to use its own hook system and agent tools. Codex continues to use its own MCP configuration. AI Team OS adds a durable shared record that both can read and write through a common MCP surface.

Architecture: FastAPI, PostgreSQL, Redis, and a React Dashboard

The system has four infrastructure components: a FastAPI API server (port 8000 by default), a PostgreSQL database with the pgvector extension (for the BM25 retrieval used in memory reconciliation), a Redis instance (port 6379 by default), and a React dashboard (port 3000 by default). The pyproject.toml requires Python 3.11 or higher.

The docker-compose.yml in the repository defines the database and Redis services:

services:
  db:
    image: pgvector/pgvector:pg16
    ports:
      - '5432:5432'
  redis:
    image: redis:7-alpine
    ports:
      - '6379:6379'

The .env.example file documents the required environment variables, including DATABASE_URL, REDIS_URL, API_PORT, DASHBOARD_PORT, and ANTHROPIC_API_KEY. Copy .env.example to .env and fill in the values before starting the services:

cp .env.example .env
docker compose up -d

The Python package installs via pyproject.toml with the package name ai-team-os. Version 1.14.0 is the current release as of 2026-09-20. The repository also includes an install.py script for bootstrapping the full environment, and a CLAUDE.md and AGENTS.md pair that define project-level instructions for the AI agents operating inside the system.

Beyond the 116 MCP tools, the system exposes 222 REST endpoints accessible from the dashboard or external tooling. The dashboard itself spans 24 pages and provides per-team operational views, tool call history, and cross-host session observation. The repository ships 25 agent templates and 42 ecosystem research tools. These research tools are separate from the coordination surface: they are intended for investigating the broader AI agent ecosystem rather than managing project tasks.

MCP Surface and Progressive Tool Loading

Claude Code connects to AI Team OS through MCP. The system exposes 116 tools covering task management, memory operations, channel communication, report writing, and dashboard observation. The .mcp.json.example file in the repository documents the MCP configuration format.

Version 1.9.0 introduced progressive tool-loading governance to avoid overloading sessions with the full tool list at startup. At session start, a single SQL query computes a hot-tool whitelist based on real call frequency over the preceding seven days. The whitelist is capped at five tools. Tools on the whitelist are loaded into the alwaysLoad set, so Claude Code skips a ToolSearch call for them. The computation requires at least a two-day call span to guard against bursty usage inflating the count. If the statistics query fails, the system silently falls back to loading no auto-included tools.

For Claude Code, ten lifecycle hooks handle startup briefings, session registry observations, compaction checkpoints, and background job visibility. These hooks inject direction-layer context automatically at session start and at sub-agent start. Codex does not use the CC hook system; it reads shared records through its own MCP adapter.

Memory System v2: Direction Layer and Episodic Memos

Memory in AI Team OS divides into two layers. The direction layer stores user preferences, corrections, design intent, and project-specific instructions across four buckets with character quotas: 1,200 characters globally, 1,500 per project, 300 per user, for a total of 3,000 characters. Each entry must be 400 characters or fewer. Entries can supersede earlier ones without deletion, and the system scans writes for invisible characters, instruction-override patterns, and credential shapes before accepting them.

The episodic layer is a task_memos ledger: execution memos promoted to their own database table with row IDs, an invalidation axis, a quality score, and a scope_path. Retrieval uses pure-Python BM25 Chinese retrieval rather than a vector embedding call, which keeps the recall path zero-LLM. The reconciliation command memory_reconcile_candidates clusters candidate memos using BM25, then a human confirmation step triggers memory_reconcile_apply to merge, invalidate, score, and distill the selected entries. The README describes this as 'the agent computes, the tool persists' with no background resident process.

MCP surfaces: memory_add, memory_list, memory_invalidate, memory_search, memory_reconcile_candidates, memory_reconcile_apply.

Limitations and Where AI Team OS Is the Wrong Fit

The infrastructure requirement is the main practical barrier. Running AI Team OS requires a PostgreSQL instance with pgvector, Redis, a running API process, and a dashboard build. Teams that prefer to keep AI tooling ephemeral or that run on machines without persistent storage will find this setup difficult to justify.

The Codex integration has documented boundaries. The README states that Claude Code extensions such as the fleet path for resuming a session, CC hooks for compaction checkpoints, and background job injection are not Codex features. A team using only Codex will not get the full hook-based context injection that Claude Code users get.

CrewAI is a Python framework for multi-agent orchestration that takes a different approach: it defines agent roles and task dependencies in code, runs an execution loop, and writes results to a configurable output. It does not provide a persistent cross-session store or a visual dashboard, but it also requires no PostgreSQL or Redis infrastructure. Teams that want agent coordination in a single script without external services may find CrewAI simpler, at the cost of the cross-session persistence that AI Team OS provides.

The fastmcp version constraint (>=3.4.5,<4) is not conservative; the pyproject.toml comment explains that fastmcp 4.0 removes the 3.x compatibility shim and that the OS shares the system Python with other processes, so an unconstrained pip install -U could silently break the MCP server.

Maintenance and License

The last push to this repository was on 2026-09-20. Version 1.14.0 was released the same day, and v1.13.1 was released on 2026-09-18, indicating frequent recent activity. The repository carries an MIT license. The CONTRIBUTING.md and SECURITY.md files document contribution and responsible disclosure processes. A CHANGELOG.md tracks the full version history.

The 21 machine-checked invariants mentioned in the README refer to automated tests that validate the system's internal consistency properties. The tests/ directory and the tools_run_weekly_summary.py script provide additional operational visibility tooling for longer-running deployments. The .github/ directory contains the CI configuration that runs these checks on every push to the master branch.

Editorial conclusion

AI Team OS suits teams running multiple Claude Code or Codex sessions on the same codebase and who need those sessions to share task state and project memory without rebuilding context each time. Engineers who use only a single AI session and do not need cross-session coordination will find the infrastructure overhead (PostgreSQL, Redis, a running API server, a dashboard) disproportionate. Before deploying, verify that the fastmcp version pinned in pyproject.toml (>=3.4.5,<4) is compatible with your installed MCP client, since the README notes that fastmcp 4.0 removes the 3.x compatibility shim. The MIT license permits commercial use.

Frequently asked questions

Official sources

1. CronusL-1141/AI-company on GitHub
2. Issues
3. License: MIT
4. README
5. Releases