Agent Infra: Unified AI Coding Collaboration

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". Here is the full fix lifecycle — AI does the heavy lifting, you stay in control:

/import-issue 42           # AI reads the issue, creates a task, extracts requirements
/analyze-task <task-id>    # AI scans the codebase, finds the root cause, writes analysis.md
/review-analysis <task-id> # An isolated reviewer checks the analysis
/plan-task <task-id>       # AI proposes a fix plan
/review-plan <task-id>     # A fresh isolated reviewer checks the 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-id>       # AI writes the fix, adds a test for [email protected] — green
/review-code <task-id>     # A fresh isolated reviewer reports one minor finding
/code-task <task-id>       # AI fixes the minor issue and re-validates
/commit
/create-pr <task-id>       # PR opened, auto-linked to issue #42
/complete-task <task-id>   # task archived

11 commands. 1 natural-language correction. From issue to merged PR. That is the entire SOP — programming can have a standard operating procedure too.

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

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

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 their 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 four 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 and $skill in Codex); the workflow semantics stay the same.

Start with one atomic role policy, for example: $run-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 TUI Configuration — adapt agent-infra to non-built-in AI TUIs
• 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