agentic-swe — Claude Code plugin: what it does, how to install

<h1 align="center">Agentic SWE</h1>

<p align="center"><strong>Claude codes your PRs. You review the receipt. Then merge.</strong></p>

<p align="center">
  <a href="https://github.com/agentic-swe/agentic-swe/actions/workflows/ci.yml"><img src="https://github.com/agentic-swe/agentic-swe/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI" /></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT" /></a>
  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg" alt="Node" /></a>
  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-3.4.0-orange.svg" alt="Version" /></a>
  <!-- catalog-counts:start kind=badge-line -->
  <a href="#subagents"><img src="https://img.shields.io/badge/subagents-138%2B-purple.svg" alt="Agents" /></a>
<!-- catalog-counts:end -->
  <a href="https://agentic-swe.github.io/agentic-swe/"><img src="https://img.shields.io/badge/docs-site-informational.svg" alt="Docs site" /></a>
</p>

An open-source autonomous SWE pipeline that runs in your editor or CI, writes every decision into your repo, and gives you a shareable audit trail of what the AI did and why.

**What you get:**

- **Structured PRs** — Claude works through a state machine (lean / standard / rigorous), not one mega-prompt
- **Cost-attributed decisions** — every phase has a dollar amount and an artifact in `.worklogs/<id>/`
- **Audit trail** — `/receipt` renders a shareable summary suitable for a PR description, Slack, or a compliance ticket

## Quickstart

```bash
curl -fsSL https://raw.githubusercontent.com/agentic-swe/agentic-swe/main/install.sh | bash
agentic-swe setup
```

Windows PowerShell:

```powershell
irm https://raw.githubusercontent.com/agentic-swe/agentic-swe/main/install.ps1 | iex
agentic-swe setup
```

Then in Claude Code:

```text
/work Add retry logic to the API client
# ...pipeline runs, opens a PR...
/receipt
```

→ See [Install & first run](#install--first-run) for Cursor, Codex, OpenCode, Gemini CLI, and Claude Code plugin marketplace alternatives.

## What `/receipt` looks like

`/receipt` reads `.worklogs/<id>/` and renders the work item as markdown. Sample from `test/fixtures/receipt/lean-happy/`:

```markdown
# /work add-retry-logic — Add retry logic to the API client

| Field | Value |
|---|---|
| Work ID | add-retry-logic |
| Track | lean |
| Status | completed |
| Duration | 47 min |
| Cost | $1.84 |
| PR | https://github.com/example/repo/pull/142 |

## Decisions made (6)

1. **feasibility → lean-track-check** ($0.08) — lean signal → feasibility.md#L1-L20
2. **lean-track-check → lean-track-implementation** ($0.04) — verdict: simple
3. **lean-track-implementation → validation** ($1.33) — implementation complete → implementation.md
4. **validation → pr-creation** ($0.21) — tests green
5. **pr-creation → approval-wait** ($0.18) — PR opened
6. **approval-wait → completed** ($0.00) — approved by suraj

## Human gates respected (1)

- `approval-wait` resolved by user at 2026-05-17T14:47:00Z — approved by suraj

## Loop counters

- `self_review_iter`: 0
- `doubt_cycles`: 1
- `code_review_iter`: 0

## Verifiable references

- All artifacts: `test/fixtures/receipt/lean-happy/`
- Audit log: `test/fixtures/receipt/lean-happy/audit.log` (9 entries)
```

Every line above is computed from `.worklogs/<id>/` — no LLM summary, no hallucinated PRs. Reproduce locally:

```bash
node scripts/render-receipt.cjs --work-dir test/fixtures/receipt/lean-happy
```

**Docs:** [agentic-swe.github.io/agentic-swe](https://agentic-swe.github.io/agentic-swe/)

---

## Pipeline at a glance

After **feasibility**, **`lean-track-check`** sets **`pipeline.track`** in **`state.json`**. Tracks merge into **PR creation** → **`approval-wait`** → **completed**.

```mermaid
%%{init: {'theme': 'dark', 'fontFamily': 'ui-sans-serif, system-ui, -apple-system, Segoe UI, sans-serif'}}%%
flowchart TD
    start(["/work — start or resume"])
    feasibility["feasibility"]
    check{"lean-track-check<br/>sets pipeline.track"}
    lean["Lean track<br/>lean-track-implementation<br/>validation · pr-creation"]
    std["Standard track<br/>design → verification → test-strategy<br/>implementation → self-review<br/>validation · pr-creation"]
    rig["Rigorous track<br/>design → design-review<br/>verification → test-strategy<br/>implementation → self-review<br/>code-review → permissions-check<br/>validation · pr-creation"]
    gate{{"approval-wait<br/>human gate"}}
    done(["completed"])

    start --> feasibility --> check
    check -->|lean| lean
    check -->|standard| std
    check -->|rigorous| rig
    lean --> gate
    std --> gate
    rig --> gate
    gate --> done

    classDef accent fill:#1f6feb,stroke:#58a6ff,color:#ffffff,stroke-width:2px
    classDef step fill:#21262d,stroke:#30363d,color:#e6edf3,stroke-width:1px
    classDef branch fill:#21262d,stroke:#388bfd,color:#c9d1d9,stroke-width:2px
    classDef decide fill:#21262d,stroke:#d29922,color:#ffdfb8,stroke-width:2px
    classDef gateNode fill:#21262d,stroke:#a371f7,color:#e6edf3,stroke-width:2px

    class start,done accent
    class feasibility step
    class check decide
    class lean,std,rig branch
    class gate gateNode
```

Canonical transitions: **`state-machine.json`** and the fenced graph in **`CLAUDE.md`** (checked in CI).

---

## Install & first run

Beyond the [Quickstart](#quickstart) above, alternate paths:

**Claude Code (plugin marketplace)**

```text
/plugin marketplace add agentic-swe/agentic-swe
/plugin install agentic-swe@agentic-swe-catalog
```

**Other hosts**

| Host | How |
|------|-----|
| **Cursor** | `agentic-swe setup --host cursor` |
| **VS Code** | `agentic-swe setup --host vscode` |
| **Codex** | `agentic-swe setup --host codex` |
| **OpenCode** | `agentic-swe setup --host opencode` |
| **Antigravity** | `agentic-swe setup --host antigravity` |
| **Windsurf** | `agentic-swe setup --host windsurf` |
| **Kiro** | `agentic-swe setup --host kiro` |
| **GitHub Copilot** | `agentic-swe setup --host copilot` |
| **Gemini CLI** | `gemini-extension.json` · **`GEMINI.md`** |

Run setup from the root of the git repository you want to configure. It refuses any other directory, shows the target and the planned changes, and waits for confirmation. `--yes` skips the question. `--dry-run` only prints the plan. Run setup without `--host` to auto-detect installed hosts, or use `--host all`. Run `agentic-swe doctor` to verify an installation. Maintainers see [`docs/PUBLISHING.md`](docs/PUBLISHING.md).

Codex requires approval of repository/plugin hooks. Windsurf hooks are disabled in Restricted Mode. Copilot hooks cover CLI and coding-agent environments; generic IDE chat transcript capture is not guaranteed. The VS Code extension performs automatic memory maintenance but cannot read another extension's private transcript. Cline, Roo, Continue, Junie/JetBrains, Zed, and similar hosts can use `AGENTS.md` plus the MCP fallback in [`integrations/fallback/README.md`](integrations/fallback/README.md).

→ [Full installation guide](https://agentic-swe.github.io/agentic-swe/docs/installation) · [Golden path (~15 min)](https://agentic-swe.github.io/agentic-swe/docs/golden-path)

---

## Commands

| Command | Role |
|---------|------|
| `agentic-swe work` | Same engine from the terminal: `init`, `status`, `transition`, `descent-try` |
| `/work` | Start or resume a work item inside the editor |
| `/plan-only` | Feasibility / design without implementation |
| `/brainstorm` | Design-first exploration (optional UI server) |
| `/write-plan` · `/execute-plan` | Plan bar then execution |
| `/check budget` · `/check transition` · `/check artifacts` | Enforcement before phases / transitions |
| `/subagent` | Browse / invoke specialists |
| `/repo-scan` · `/test-runner` · `/lint` | Evidence helpers |

A new work item starts on the **lean** track. Set **`pipeline.acceptance_command`** in **`.worklogs/<id>/state.json`** to the project’s test command. Moving from **validation** to pull-request creation runs that command and refuses the step when it does not exit 0. The log is **`.worklogs/<id>/verify-result.json`**. Check the active item with **`agentic-swe work status`**.

**Full list:** [Usage](https://agentic-swe.github.io/agentic-swe/docs/usage) · **`commands/`**

---

## Subagents

<!-- catalog-counts:start kind=total-line -->
**138+ specialists** under **`agents/subagents/`**
<!-- catalog-counts:end -->. **Auto-selected** from **`feasibility.md`** signals; manual **`/subagent invoke`** anytime.

<!-- catalog-counts:start kind=inline -->
Across 10 categories — Language Specialists (29), Infrastructure (16), Specialized Domains (15), Quality & Security (14), Data & AI (13), Developer Experience (13), Business & Product (11), Core Development (10), Meta & Orchestration (10), Research & Analysis (7).
<!-- catalog-counts:end -->

**Details:** [Subagent catalog](https://agentic-swe.github.io/agentic-swe/docs/subagent-catalog) · [Catalog routing](https://agentic-swe.github.io/agentic-swe/docs/catalog-routing)

---

## Work state

**`.worklogs/<id>/`** holds **`state.json`** (source of truth), **`progress.md`** (timeline), **`audit.log`** (append-only), and per-phase markdown (e.g. **`feasibility.md`**, **`implementation.md`**, **`validation-results.md`**, **`pr-link.txt`**).

- **State over chat** — resume from files, not from thread memory alone.
- **Evidence** — tie claims to commands, paths, or CI (`templates/evidence-standard.md`).
- **CI parity** — **`scripts/work-engine.cjs`** enforces **`/check`**-style rules.

---

## Architecture

A single **Hypervisor session** (this one) owns transitions, gates, and synthesis. Three **core agents** — **developer**, **git-operations**, **pr-manager** — carry bounded work. A **design panel** (architect, security, adversarial) reviews in parallel on the rigorous track. All consult the **135+ subagent** catalog, auto-selected from repo signals.

→ [Architecture overview](https://agentic-swe.github.io/agentic-swe/docs/architecture) (full diagram)

---

## Extending · CI · License

| Topic | Where |
|-------|--------|
| Extend pipeline | **`/author-pipeline`** · [`references/authoring-pipeline-capabilities.md`](references/authoring-pipeline-capabilities.md) |
| Competitive note | [`docs/competitive-vs-ruflo.md`](docs/competitive-vs-ruflo.md) — win on PR receipt + replay, not swarm/marketplace parity |
| Compliance map | [`docs/compliance-mapping.md`](docs/compliance-mapping.md) — ASI / NIST AI RMF / EU AI Act coverage (pack-boundary, not a certification) |
| CI | [`.github/workflows/ci.yml`](.github/workflows/ci.yml) — **`npm run ci`** locally |
| Research basis | [`CLAUDE.md` — Research basis](CLAUDE.md#research-basis) |
| License | [MIT](LICENSE) · [Licensing](https://agentic-swe.github.io/agentic-swe/docs/licensing) |