KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#typescript #ai-agents #developer-tools #codex #claude-code #cli #react #mcp #open-source #deepseek-harness #dsh-plugin #ai

agent-infra

★ 84 Open GitHub ↗

Collaboration infrastructure for AI coding agents | AI 编程代理的协作基础设施

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<h1 align="center">Agent Infra</h1>

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 · <a href="./README.zh-CN.md">中文</a>

## 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:

```bash
/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:

```bash
/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.

```bash
/code-task <task-id> # AI writes the fix, adds a test for user+tag@example.com — 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](./docs/en/skills.md).

## 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)**

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

**Option B - Shell script**

```bash
# 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)**

```bash
# 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

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

Check your current version:

```bash
ai version
# or: agent-infra version
```

### 2. Initialize a new project

```bash
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`:

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

```bash
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.

| 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; current built-in clients, including Claude Code and Codex, fail closed before delegation because their native start events do not expose all required evidence |
| `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, then run a structured code review |
| `commit` → `create-pr` → `complete-task` | Commit, open a PR, and archive the task |

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 v2 policy.

See the full catalog — task status, release, security, and project-maintenance skills — in [Built-in AI Skills](./docs/en/skills.md).

## What You Get

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

```text
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/`](./docs/en/README.md):

- [Process Data Archive](./docs/en/process-data.md) — capture, verify, audit, repair, export, privacy, and backup guidance
- [Architecture Overview](./docs/en/architecture.md) — bootstrap CLI, end-to-end flow, layered architecture
- [Platform Support](./docs/en/platform-support.md) — macOS, Linux, Windows; sandbox engines and resources
- [Sandbox](./docs/en/sandbox.md) — sandbox aliases, host-sandbox file exchange, user-level dotfiles channel
- [Benchmark Contract and Threat Model](./docs/en/benchmark.md) — versioned benchmark schemas, trust boundaries, and security guarantees
- [Feishu Bridge](./docs/en/feishu-bridge.md) — configure the Feishu long-connection adapter, command routing, permissions, and TUI selection
- [Built-in AI Skills](./docs/en/skills.md) — the full skill catalog by use case
- [Custom Skills](./docs/en/custom-skills.md) — create and sync project-specific skills
- [Custom TUI Configuration](./docs/en/custom-tui.md) — adapt agent-infra to non-built-in AI TUIs
- [Prebuilt Workflows](./docs/en/workflows.md) — the gated delivery lifecycle and example flow
- [Configuration Reference](./docs/en/configuration.md) — `.agents/.airc.json`, external sources, version management
- [File Management Strategies](./docs/en/file-management.md) — managed / merged / ejected update strategies

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.

## License

[MIT](License.txt)

agent-infra

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README