fitlab-ai 开源 agent-infra：为 Claude Code、Codex 等 AI 编码智能体提供协作基础设施

Collaboration infrastructure for AI coding agents — skills, workflows, and sandboxes for Claude Code, Codex, Antigravity CLI, and OpenCode.

From issue to merged PR through a risk-selected lifecycle. Every task starts with analysis, and every implementation receives an independent code review.

English · 中文

Why agent-infra?

Teams increasingly mix Claude Code, Codex, Antigravity CLI, OpenCode, and other AI TUIs in the same repository, but each tool tends to introduce its own commands, prompts, and local conventions. Without a shared layer, the result is fragmented workflows, duplicated setup, and task history that is difficult to audit.

agent-infra standardizes that shared infrastructure. It gives every supported AI TUI the same task lifecycle, the same skill vocabulary, the same project governance files, isolated development sandboxes, and the same upgrade path, so teams can switch tools without rebuilding process from scratch.

See it in Action

The demo is stored with Git LFS. Install Git LFS and run git lfs install before cloning, or run git lfs pull in an existing checkout. If the image is a small text pointer or is missing, verify git lfs ls-files, then retry git lfs pull.

Once initialized, open the project in your AI TUI and install the latest skills:

/update-agent-infra

AI reads .agents/.airc.json, auto-locates the installed template root, and syncs the latest skill manifests, managed files, and registry deterministically via sync-templates.js.

Scenario: Issue #42 reports "Login API returns 500 when email contains a plus sign". Every task starts with analysis, which records one canonical path from observable facts:

File count, module count, or a merely possible risk does not select the full path. A later finding can return work to analysis, planning, or code when new evidence justifies it; independent review-code remains part of every path.

Suppose the analysis selects the standard path because the application-layer boundary needs an explicit plan:

/import-issue 42           # AI reads the issue, creates a task, extracts requirements
/analyze-task --task <task-id>    # AI scans the codebase, records the selected path, writes analysis.md
/plan-task --task <task-id>       # AI proposes a fix plan

You review the plan and reply in natural language:

The plan looks right, but don't change the DB schema.
Just fix it at the application layer in LoginService.

AI re-runs /plan-task to update the plan accordingly and confirms.

/code-task --task <task-id>       # AI writes the fix, tests it, and creates a local checkpoint commit
/review-code --task <task-id>     # A fresh isolated reviewer reports one minor finding
/code-task --task <task-id>       # AI fixes the minor issue, re-validates, and creates a new checkpoint
/review-code --task <task-id>     # The reviewer approves the current checkpoint
/create-pr --task <task-id>       # The reviewed branch is published to its task-bound target; PR links issue #42
/complete-task --task <task-id>   # task archived

One analysis-selected path, one natural-language correction, and an independent code review. The lifecycle keeps the evidence and review depth proportional to the task.

Every command above works the same way in Claude Code, Codex, Antigravity CLI, and OpenCode. Switch tools mid-task — the workflow state follows. For what each skill does under the hood, see Built-in AI Skills.

Key Features

• Multi-AI collaboration: one shared operating model for Claude Code, Codex, Antigravity CLI, and OpenCode
• Bootstrap CLI + skill-driven execution: initialize once, then let AI skills drive day-to-day work
• IM command bridge: route Feishu messages to built-ins, read-only task views, sandbox management, and controlled lifecycle skill runs
• Bilingual project docs: English-first docs with synchronized Chinese translations
• Template-source architecture: templates/ mirrors the rendered project structure
• AI-assisted updates: template changes can be merged while preserving project-specific customization
• Auditable process-data archive: preserve local tasks and GitHub evidence in append-only, verifiable snapshots

Sandbox control boundary

Direct-host lifecycle and workflow commands execute in the current CLI process. Task-bound sandboxes route requests to their broker; the broker verifies the request, manifest, generation, owner, lease, and controller before starting a one-request executor. There is no host socket, worker token, or user-level task-control service.

The task directory exposed inside a task-bound sandbox is writable only for its bound task. Artifact commands accept typed workflow operations and canonical artifact basenames. The executor opens candidates with O_NOFOLLOW, reads and hashes them through one file descriptor, checks observable metadata changes, and atomically lands validated bytes into the authoritative task directory.

Quick Start

1. Install agent-infra

Option A - npm (recommended)

npm install -g @fitlab-ai/agent-infra

Option B - Shell script

# Convenience wrapper — detects Node.js and runs npm install -g internally
curl -fsSL https://raw.githubusercontent.com/fitlab-ai/agent-infra/main/install.sh | sh

Option C - Homebrew (macOS)

# Newer Homebrew refuses to load formulae from third-party taps until trusted,
# which silently blocks upgrades. Trust the tap once before installing.
brew trust fitlab-ai/tap
brew install fitlab-ai/tap/agent-infra

Updating agent-infra

ai update

ai update updates the installed agent-infra CLI. In an initialized project, use ai sync to refresh project seed files and the file registry.

The equivalent package-manager commands remain:

npm update -g @fitlab-ai/agent-infra
# or, if installed via Homebrew:
brew upgrade agent-infra

Check your current version:

ai version
# or: agent-infra version

2. Initialize a new project

cd my-project
ai init
# or: agent-infra init

The CLI collects project metadata, lets you select the enabled Agent Clients, installs any client-specific update-agent-infra seed commands, and generates .agents/.airc.json.

ai is a shorthand for agent-infra. Both commands are equivalent.

3. Render the full infrastructure

Open the project in any AI TUI and run update-agent-infra:

This detects the packaged template version and renders all managed files. The same command is used both for first-time setup and for future template upgrades.

Core Commands

Manage the five built-in Agent Clients independently from the project lifecycle:

ai agent-client list
ai agent-client status
ai agent-client enable codex
ai agent-client disable antigravity-cli
ai agent-client configure

The most-used lifecycle commands, in delivery order. The command prefix varies by TUI (/skill in Claude Code/Antigravity/OpenCode/TraeCode and $skill in Codex); the workflow semantics stay the same.

Start with one atomic role policy, for example: $run-task --task 42 --executor-model <id> --executor-reasoning-effort <value> --reviewer-model <id> --reviewer-reasoning-effort <value>. Both roles may use the same model. With no explicit policy, run-task reads the current Agent Client's optional agentClients[].orchestration; if neither source is complete, it shows the host model-selection guidance before creating any run. Re-entry uses the persisted run policy. Finish or clear active runs before upgrading agent-infra; unsupported disk state fails closed without rewriting.

See the full catalog — task status, release, security, and project-maintenance skills — in Built-in AI Skills.

What You Get

After setup, your project gains a complete AI collaboration infrastructure:

my-project/
├── .agents/               # Shared AI collaboration config
│   ├── .airc.json         # Central configuration
│   ├── workspace/         # Task workspace (git-ignored)
│   ├── skills/            # Built-in AI skills
│   ├── workflows/         # 4 prebuilt workflows
│   └── templates/         # Task and artifact templates
├── .claude/               # Claude Code config and commands
├── .opencode/             # OpenCode config and commands
└── AGENTS.md              # Universal AI agent instructions

Documentation

In-depth guides live under docs/en/:

• Process Data Archive — capture, verify, audit, repair, export, privacy, and backup guidance
• Architecture Overview — bootstrap CLI, end-to-end flow, layered architecture
• Platform Support — macOS, Linux, Windows; sandbox engines and resources
• Sandbox — sandbox aliases, host-sandbox file exchange, user-level dotfiles channel
• Benchmark Contract and Threat Model — versioned benchmark schemas, trust boundaries, and security guarantees
• Feishu Bridge — configure the Feishu long-connection adapter, command routing, permissions, and TUI selection
• Built-in AI Skills — the full skill catalog by use case
• Custom Skills — create and sync project-specific skills
• Custom Tool Invocations — configure custom-tool next-step commands
• Prebuilt Workflows — the gated delivery lifecycle and example flow
• Configuration Reference — .agents/.airc.json, external sources, version management
• File Management Strategies — managed / merged / ejected update strategies

Contributing

See CONTRIBUTING.md for development guidelines.

License

MIT