AI Team OS: a persistent team layer for Claude Code and Codex

The problem: a session ends and the team's context goes with it

The README opens with the failure mode it targets: a session can end without taking the team's context with it. In practice that means parallel agents are only useful if you can answer who owns a piece of work, what actually happened, and where to resume. Those answers normally live in a chat transcript, and a transcript is not a record you can hand to the next session.

AI Team OS is for people already running Claude Code or Codex on projects that outlive one conversation. It is not an agent framework in the LangChain or AutoGen sense; the README states the project uses pure Claude Code native integration rather than those libraries. The OS records and exposes the work, while your chosen host runs the agents and you decide what they are authorized to do. That division is the whole design, and it is worth taking literally: if you want something that spawns and supervises agents on its own, this is a different kind of tool.

The repository describes persistent teams, structured meetings, a task wall and a real-time React dashboard, with 116 MCP tools, 212 REST endpoints and 23 dashboard pages according to the README header. Treat those numbers as scope indicators, not as quality signals.

How the shared record works across hosts

The mechanism is a shared store plus MCP tools. Tasks and handoffs (ownership, progress memos, blockers, completion records) stay on the project task wall. Project memory and reports hold earlier decisions and evidence. Team communication runs through channel_send, channel_read and channel_wait, with explicit reader identities and acknowledgements. The dashboard then shows Leaders, members, tool activity and project totals.

Session ownership is the part that shapes everything else. Each root session has its own Leader, and the implementation combines registered sessions with Claude file observations to label Claude Leader and Codex Leader explicitly. Native Codex children join the parent team instead of becoming extra Leaders. A Claude Leader and a Codex Leader can contribute to the same project without pretending to be the same process or sharing host configuration.

Memory is split into two layers. The direction layer holds user preferences, corrections and design intent in four kinds, with character quotas: global 1200, 1500 per project and 300 for user, 3000 total, capped at 400 characters per entry. Replacement happens through supersedes, and invalidation is auditable rather than a delete. Writes are scanned for invisible characters, instruction-override patterns and credential shapes. The episodic layer is a task_memos ledger with row IDs, an invalidation axis, a quality score and scope_path, recalled through pure-Python BM25 Chinese retrieval. memory_reconcile does zero-LLM BM25 candidate clustering and then merges, invalidates, scores or distills on agent confirmation. The README's phrasing for this is that the agent computes and the tool persists, with no background resident process.

Fresh busy evidence drives the current roster; waiting, closed and stale records stay available as history rather than being deleted. Unknown source or model information stays unknown.

Installing AI Team OS and running a first session

The repository ships install.py at the top level, plus INSTALL.md and INSTALL.zh-CN.md. Docker Compose is provided for the development environment, with a pgvector PostgreSQL 16 image and Redis 7. Start there if you want the backing services without installing them yourself.

docker compose up -d

The compose file defines two services, db and redis, with healthchecks on both. Ports default to 5432 and 6379 and are overridable through DB_PORT and REDIS_PORT. The database service mounts docker/init.sql into the entrypoint directory.

Next, copy the environment template and edit it. The file itself says to copy .env.example to .env.

cp .env.example .env

The keys you will most likely touch are DATABASE_URL, REDIS_URL, API_PORT (8000) and DASHBOARD_PORT (3000). The template also carries POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB, DB_PORT, REDIS_PORT, ANTHROPIC_API_KEY and AITEAM_ENV, which accepts development, staging or production.

For the host side, the top level contains install.py, .mcp.json.example and a .claude-plugin/ directory, so the plugin route and the source-installer route both exist. The README for v1.13.0 states the source installer stops registering a second server next to an enabled plugin, which is a hint that running both paths at once was previously a source of confusion. Read INSTALL.md before choosing, because the per-host MCP and hook configuration differs between Claude Code and Codex.

Python must be 3.11 or newer; pyproject.toml declares requires-python >=3.11 and lists fastapi>=0.115.0, uvicorn[standard]>=0.32.0, sqlalchemy>=2.0, alembic>=1.14.0 and fastmcp>=3.4.5,<4. Once configured, the first real use is to resolve a project, read its task wall, memos and memory, let the session's Leader coordinate authorized work, and record progress through the shared MCP tools so the next session can pick it up.

The fastmcp pin is deliberate, and it constrains upgrades

The dependency line fastmcp>=3.4.5,<4 comes with a comment in pyproject.toml explaining the upper bound. fastmcp 4.0 removes the 3.x compatibility shim, and the comment states the OS has no venv isolation layer, so four process types share the system Python. A single pip install -U could swap out the MCP server on the user's machine. The lower bound of 3.4.5 is there because 3.4.3's Host/Origin guard interrupted the ASGI-mounted /mcp/ path, and the comment says the official fix landed in 3.4.4.

That is an honest constraint rather than a packaging accident, and it tells you something about the deployment model. This is not a library you can drop into an isolated virtualenv and forget. If your environment shares a system Python across services, a routine dependency bump elsewhere can break the MCP surface. The comment also notes that allowing 4.x requires validating the private surface first, referencing mcp/_alwaysload.py and mcp/tools/__init__.py. If you plan to run this long term, pin your own lockfile and treat fastmcp as a component you upgrade on purpose.

A second packaging detail worth knowing: greenlet is declared explicitly because its own platform markers omit Apple Silicon macOS, where platform_machine is arm64. Without it, the async SQLAlchemy engine raises ValueError on first connection. That is a real failure mode on M-series machines if you assemble dependencies by hand.

Instruction bloat and honest MCP registration in v1.13.0

The v1.13.0 release notes describe an audit of the instruction set shipped to Claude Code, cut to what a model would otherwise get wrong. The role templates went from 167 KB to 17 KB. The plugin no longer force-loads all 116 tool schemas into every session. The source installer stops registering a second server next to an enabled plugin, and a read-only script reports drift in Codex-side installed hook copies.

This is a useful signal about the project's maturity curve. Shipping 116 tools means every session pays a context cost unless the schemas are loaded selectively, and the release notes indicate that cost was being paid until recently. The drift-reporting script addresses a different problem: two hosts with separate hook configuration can diverge silently, and a read-only check is a cheap way to notice.

The earlier v1.12.3 release was titled Now on Codex as Well, and v1.12.4 was Root Sessions Have Owners. Read together with the README's insistence that native agent tools, host settings and hook trust remain separate, the picture is a project that added a second host and then spent releases making the ownership model explicit. If you are evaluating it, read CHANGELOG.md rather than the release titles; the README says historical details live there.

Where AI Team OS is the wrong tool

The boundaries are stated plainly. The OS does not replace either host's scheduler, permissions or agent lifecycle. Codex can read the shared records through MCP with its own adapter handling supported observations, but the README says the Claude Code execution and injection paths, including resuming a Claude session for one turn, compaction checkpoints and background-job visibility, are not Codex features. If your workflow depends on hooks injecting startup briefings automatically, you are on the Claude Code side of the product.

Channel waits have a similar limit. A pending wait can return new messages; the README states it does not restart an ended Codex turn. So the channel is a communication record, not a wake-up mechanism.

There is also a scale question the documentation does not answer. The direction layer is capped at 3000 characters total, with 400 per entry. That is a deliberate budget, and it means the memory is tuned for durable preferences and corrections, not for accumulating project knowledge. Long design documents belong somewhere else. Finally, the project describes itself as Beta in pyproject.toml classifiers, so expect the interface to move between minor versions.

Alternatives and the actual difference in approach

The obvious comparison is an agent framework such as LangChain or AutoGen, and the README draws the line itself: AI Team OS uses pure Claude Code native integration instead. The difference is what each thing owns. A framework owns the agent loop, so you write orchestration code and the library decides how agents are constructed, messaged and stopped. AI Team OS owns the record and leaves the loop with Claude Code or Codex. You do not get a programmatic agent scheduler, and in exchange you do not rewrite your agents to fit a framework's abstractions.

A second comparison is the host's own session history. Claude Code and Codex already keep conversation state, and for a single continuous session that is enough. AI Team OS matters when work crosses sessions, hosts or people and you need ownership, acknowledgements and an auditable invalidation trail rather than a scrollback. The direction layer's supersedes mechanism and the task_memos ledger's invalidation axis are the concrete differences; a transcript has no concept of either.

A third option is a general project tracker with an MCP bridge. That gets you durable records, but not the per-root-session Leader model or the dashboard's distinction between fresh busy evidence and folded-away history. Whether that distinction is worth a separate system depends on how often you hand work between sessions.

Licence, maintenance and the upgrade cost you should budget

The licence is MIT, declared in pyproject.toml and referenced from the LICENSE file at the repository root. MIT is permissive, so you can use, modify and redistribute the code with the copyright notice intact. This is not legal advice; check the LICENSE file and your own obligations, particularly if you redistribute a modified plugin.

Maintenance looks current rather than dormant. The last push was on 2026-09-14, and v1.13.0 was released the same day, with v1.12.4 hours earlier and v1.12.3 on 2026-09-09. The repository is not archived. That cadence also defines the upgrade cost: three releases in six days means you should not treat the master branch as a stable surface. The v1.13.0 notes mention upgrade notes in the changelog, so read those before pulling.

The practical costs are the fastmcp pin, the shared-Python deployment assumption, and the hook configuration that differs per host. Budget time for the first one especially. If your team runs Codex alongside Claude Code, the read-only drift script mentioned in the v1.13.0 notes is the cheapest way to keep the two hook copies honest.

Editorial conclusion

Adopt AI Team OS if you already run Claude Code or Codex on long-lived projects where context dies with the chat: the task wall, direction layer and channel tools exist precisely to keep ownership and evidence outside the session. Do not adopt it if you want the OS to schedule or supervise agents for you, or if you expect Codex to get the same hook-driven startup briefings Claude Code gets; the README states those execution and injection paths are not Codex features. Before committing, verify three things on your own machine: that your Python is 3.11 or newer, that fastmcp resolves inside the pinned >=3.4.5,<4 range, and that your PostgreSQL and Redis services match the DATABASE_URL and REDIS_URL you put in .env.

Frequently asked questions

Official sources

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