AI公司多智能体操作系统

Prerequisites

• Python >= 3.11; Python 3.12 is recommended for development and validation
• uv (pip install uv)
• Claude Code or Codex with MCP support; hook setup is host-specific
• Node.js >= 20 (Dashboard frontend, optional)

Install uv (Python package runner, required for MCP server)

pip install uv

Restart Claude Code after installation; the first launch configures dependencies

Used to Build This Project

AI Team OS manages its own development — and since v1.7.0, it can prove it with its own telemetry:

Claude Code and Codex sessions use the same task records and channels to exchange implementation and review evidence. Their native execution histories stay distinct; the OS provides the common project record.

• Every feature line from v1.7.0 to v1.9.0 — the observability layer, the knowledge layer, model governance, Memory System v2, tool-loading governance — shipped through CC Workflow runs that the OS tracked itself. Open /workflows and replay how the system built its own features, swimlane by swimlane.
• Competitive research across CrewAI, AutoGen, LangGraph, and Devin feeds the roadmap through multi-agent brainstorming meetings — the minutes live in the OS's own report store.
• It learns from its own incidents, too: every machine-checked invariant in scripts/check_invariants.sh was distilled from a real accident in this repo's history.

The same task wall, reports and observations used in development are available for your projects.

---

Choose an Installation Path

For Claude Code's AI-assisted installation, tell Claude Code: > "Read https://github.com/CronusL-1141/AI-company/blob/master/INSTALL.md and follow the instructions to install AI Team OS"

Claude Code can read the install guide and walk through its plugin setup. Codex users should follow the separate manual path below; the Claude installer is not a Codex installer.

---

Important: Install AI Team OS to your system Python, not inside a project virtual environment. If installed in a venv, AI Team OS will only work in that specific project. Run deactivate first if a venv is currently active, then install.

---

Option A: Claude Code Plugin Install

Pick one of Option A or Option B, not both. Each installs the same MCP server; running both loads it twice in every session. The source installer detects an enabled plugin and skips global MCP registration unless you pass --force-mcp.

```bash

Add marketplace + install plugin

claude plugin marketplace add CronusL-1141/AI-company claude plugin install ai-team-os

(plugin update alone reports the installed version as the latest)

claude plugin marketplace update ai-team-os claude plugin update ai-team-os@ai-team-os ```

Note: Claude Code's first launch configures dependencies; duration depends on the local environment. Verify the loaded MCP tools and installed hooks rather than relying on startup time.

Option B: Claude Code Source Install

Pick one of Option A or Option B, not both. If the plugin is already enabled, install.py prints a skip line for global MCP registration; use --force-mcp only when you intend to run two copies.

```bash

Step 2: Run the Claude Code installer (MCP + CC hooks + CC templates + API)

python3 install.py

Verify Installation

```bash

Preview the Claude Code source uninstaller before deciding what to remove:

python scripts/uninstall.py --dry-run python scripts/uninstall.py # keeps ~/.claude/data/ai-team-os (aiteam.db); add --purge-data to delete it too ```

For Codex, remove only its own MCP/hook registrations and independently copied adapter files. Before removing shared OS data or passing --purge-data to the source uninstaller, inspect the plan, back up the records and confirm no other host still uses the backend. Removing one host's integration is not permission to delete the shared database.

Quick Start

Example: lean core + ecosystem, read-only

AITEAM_TOOLSETS=default,ecosystem AITEAM_READONLY=1 python3 -m aiteam.mcp.server ```

Plan Usage (Codex)

Estimated plan capacity in API-equivalent dollars for the 5-hour and weekly windows, next to the native percentage used, and the monitor that keeps sampling while the page is closed. These are local-sample estimates at standard API rates, not charges or balances.

Why are a model, duration or usage value unknown?

The OS only displays evidence it can attribute. Missing native metadata stays unknown, tool duration needs trustworthy timing, and full Codex token/cost attribution is unfinished. Historical calls without reliable IDs are not marked complete by guesswork.

External Codex Usage

Use aiteam codex-exec run --caller-harness claude-code -- --ephemeral "TASK" to retain minimum usage receipts for an external Codex execution. Add explicit --project-id and --task-id values to attribute it. The command streams native JSONL to stdout and keeps a private local ledger for retry if the API is unavailable. Existing direct codex exec calls are not intercepted. Receipts without verified account, model and tier information remain separate from subscription estimates. See the external execution guide.

Dashboard Screenshots

These screenshots show the v1.15.0 Dashboard running on a seeded demo database (scripts/demo_seed.py): a fictional product team working with Claude Code and Codex sessions. Names, numbers and times are sample data, not measurements from a real project. The captions explain what each view shows.

Option C: Codex Adapter Lifecycle

Codex uses the shared OS backend with its own adapter. The on-demand runtime is validated on macOS; it requires POSIX and has not been validated on Windows. Keep the source checkout and system Python available.

1. Clone this repository and install dependencies with your system interpreter: python3 -m pip install -e .. Follow the interpreter's package-management policy; do not run the Claude installer to configure Codex.
2. Choose the existing local API address, or an available local port for a new service. Install the MCP connection, header helper and complete Hook adapter together:

   python3 scripts/codex_adapter.py install --api-url http://127.0.0.1:8000
   python3 scripts/codex_adapter.py status
   

Replace 8000 with your chosen port. The installer backs up changed files, preserves unrelated settings and hooks, and rolls back failed writes. It respects CODEX_HOME. Opening a new Codex connection starts the API on demand; closing the terminal does not stop it. No login service or scheduled restart is installed. 3. Reload Codex and review its first-time Hook trust prompts in the CLI/TUI or Desktop Hook settings. MCP connectivity and Hook approval are separate checks. 4. After updating the repository and dependencies, run python3 scripts/codex_adapter.py update, then status. Source updates do not replace code already loaded by a running API. Follow the reported restart requirement: coordinate use of the shared service, stop only the runtime-owned API, then reconnect Codex. Externally managed APIs must be restarted by their owner. Unknown source state is not proof that an update is active. 5. Verify a real MCP tool call and the installed Hook observation in the API and Dashboard. File copies and tool discovery alone do not prove the complete observation chain. Script-body changes normally preserve trust; changed registrations may require approval again.

If you already use a stdio MCP connection and only want to update its Hook adapter, run python3 scripts/codex_adapter.py update --hooks-only. This preserves the MCP configuration byte for byte; switching transports requires a separate explicit migration.

Claude Code settings, startup briefings, templates and execution controls remain separate. This release does not enable HTTP/2 or change an existing Dashboard port.

Tool Loading Configuration (optional)

The MCP server can expose the full tool inventory or a smaller set for each client. Two environment variables are read at server startup; configuration changes take effect on the next start, not in an already running server.

AITEAM_TOOLSETS - pick which capability-domain groups register:

• unset or all - the full registered inventory (backward compatible)
• default - core groups only (task,team,memory,infra,reports,notices = 30 tools, hard-capped at <=50)
• a comma list of group names, mixable with default for incremental loading, e.g. AITEAM_TOOLSETS=default,ecosystem
• unknown names are warned on stderr and ignored (a config typo never blocks server start)

AITEAM_READONLY=1 - orthogonal overlay that strips every write tool (create/update/delete/apply/send/... plus os_restart_api) after registration, keeping only read tools. Handy for audit/observer sessions.

The 17 groups (default groups marked *):

```bash

Start the Dashboard (optional)

```bash cd dashboard npm install npm run dev

6. Knowledge Layer — Reference Graph + Unified Search (v1.8.0)

Everything the OS records — task memos, reports, tasks — becomes recallable knowledge:

• Reference graph (P1a): a zero-LLM regex extractor mines OS-native ID references (wf_id / commit hash / task uuid / [[memory]]) out of memos and reports into an append-only knowledge_links table — the graph is a derived view, rebuildable from source text at any time
• Unified search (P1b): /api/search fuses three arms via RRF — BM25 full-text (Chinese bigram native), knowledge-graph fanout (an ID query pulls in everything linked to it), and exact ID-prefix / title match
• Global search box in the Dashboard header, plus MCP tools unified_search / link_query / link_trace — recall past work by natural language ("how was the attribution fix done"), a wf_ id, or a commit hash

Why zero-LLM retrieval? ID extraction and search run locally without a model call, and the graph can be rebuilt from source text. Reading retrieved results into an agent's context still consumes that host's normal context budget.

Plan Capacity and API-Equivalent Pricing

The window's Reset calculation start button explicitly replaces its statistics anchor with the latest saved observation. It preserves usage history and monitor settings, does not trigger a capture, and survives API restarts. A later allowance reset starts a new cycle normally.

An independent, versioned OpenAI price catalog supports per-request estimates through aiteam pricing and /api/pricing. It includes verified public rates, exact aliases, cache read/write prices and context/service-tier rules. Supplement a catalog and recompute the same inputs without retaining missing prices as zero. Results include price provenance, a content hash and request coverage; they are not subscription charges. See the pricing guide and price sources.

The independent /usage/accounts Dashboard page shows the native percentage used and estimated plan capacity in USD, labeled Local-sample estimate. Identified responses use their actual model, input, cache read/write and output usage at verified Standard API rates; when native service_tier is recorded, logged Fast/priority tiers use the catalog Fast rate (2× Standard). Long-context bands use each request's full input, including cache, never the session total. Known dollar contributions are accumulated from the cycle anchor and compared with the same cycle's allowance change. Account attribution and request-price provenance remain separate from the prediction assumption described below. This is an API-equivalent local workload sample, not a subscription charge, cash balance, complete cross-device ledger or official fixed capacity. No request-log import or billing access is required. Existing Token attribution and Claude configuration remain unchanged. See the account guide.

Prediction starts by default after the local Codex account is verified. Users can choose a 30-second to 30-minute interval or explicitly pause prediction; saved choices survive API restarts. The estimate always compares the earliest observation in the current allowance cycle with the latest one: known API-equivalent dollars divided by the increase in percentage points, multiplied by 100. Only a rollback in the account usage percentage, which confirms that the allowance was reset, moves this anchor; a standalone resets_at timestamp change does not. Missing contributions count as zero for this prediction, while the original records retain their unknown or incomplete state. A 1% increase is enough; Spark usage remains separate. This is not an AI-session heartbeat and never launches a model turn.

Usage recording is independent of prediction. An API-lifetime recorder incrementally saves available native usage events, including missing-model and unknown-provider observations, with persistent file cursors. Pausing prediction or closing the page does not stop recording. Complete lines and cursors are committed together; partial tails and late records can be read later. Existing logs can be backfilled after restart, but deleted, never-recorded history and unobserved quota readings cannot be reconstructed. The recorder stores usage fields, not conversation text or credentials; retaining an event does not automatically attribute it to the current account. See the account usage guide.

API server starts automatically when MCP loads. No manual startup needed.

Use the actual running API port; 8000 is the usual default.

curl http://localhost:8000/api/health

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

Remove a Host Integration

```bash

Claude Code plugin:

claude plugin uninstall ai-team-os

Workflows

Every Claude Code Workflow run is recorded automatically with its phases, planned and actual agent counts, tokens, tool calls and duration. Filter the list by project or status.

Workflow Detail - Phase Swim Lane and Per-Agent Telemetry

One Claude Code Workflow run: every phase's agents on a shared timeline, with the failed contract check in red, and a table of tokens, tool calls, duration and state for each agent.

Ecosystem Integration Recipes

AI Team OS can coordinate records and handoffs around other MCP servers instead of reimplementing their capabilities. Recipes describe integrations that you configure and authorize in the host where the work runs:

Use find_skill(level=2, category="integration") to discover recipes, or see the full guide: docs/ecosystem-recipes.md

---

How It Compares

---

FAQ