Agent Infra

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

From issue to merged PR in 11 commands. Define a requirement, let AI handle analysis, planning, coding, and three-stage review — you only step in when it matters.

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

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:

TUI	Command
Claude Code	/update-agent-infra
Codex	$update-agent-infra
Antigravity CLI	/update-agent-infra
OpenCode	/update-agent-infra
TraeCode CLI	/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.

Command	Purpose
create-task / import-issue	Start a task from a description or a GitHub Issue
run-task	Resume the lifecycle with fresh isolated executors/reviewers when the selected client exposes verified actual model/effort evidence; Codex now has an experimental Hooks + App Server evidence channel, but orchestration remains disabled until that channel is connected to delegation receipts
analyze-task → review-analysis	Capture scope and risks, then review the analysis
plan-task → review-plan	Design the approach, then review the plan
code-task → review-code	Implement and test; code-task creates a local checkpoint, then a structured review checks that checkpoint
create-pr → complete-task	Publish the approved checkpoint to the task-bound target branch, then archive after merge and final gates

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