> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bitfab.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Amp Plugin

> Bitfab skills for Amp (Alpha): instrument, replay, and diagnose AI workflows from the terminal

<Warning>
  **Alpha.** Amp support ships today as a skill pack over the terminal-native CLI flow, not as a native Amp plugin. Setup, instrumentation, replay, and diagnostics work. The improvement loop (datasets, graders, experiments, trace labeling) does not, and needs Claude Code, Cursor, or Codex. See [Alpha limits](#alpha-limits).
</Warning>

Amp discovers skills by name and description and loads one when it becomes relevant. The Bitfab skills dispatch into `bitfab-cli`'s terminal-native flow, so setup decisions, plan review, and edit approvals all stay in your terminal.

## Installation

```bash theme={null}
npx bitfab-cli init --editor amp
```

This installs all three skills into Amp's global skills directory (`~/.config/agents/skills/`), signs you in to Bitfab, and then runs setup in the same terminal.

To install the skills without signing in or running setup:

```bash theme={null}
npx bitfab-cli plugin-install --editor amp
```

Either way, confirm they registered:

```bash theme={null}
amp skill list | grep bitfab-
```

Then ask Amp to instrument something, or invoke a skill directly from the command palette (`Ctrl-O` in the Amp CLI, `Cmd/Alt-Shift-A` in the editor extensions) with `skill: invoke`.

### Installing with Amp directly

`bitfab-cli` runs `amp skill add` for you, so this is the same install by hand:

```bash theme={null}
amp skill add Project-White-Rabbit/bitfab-amp-plugin/skills --global --overwrite
```

Drop `--global` to install into the current project's `.agents/skills/` instead. `--overwrite` is what makes a reinstall work. Without it Amp refuses every skill that already exists, and `amp skill add` exits 0 either way, so a failed reinstall looks like a successful one.

## Requirements

Two independent credentials.

1. **An Agent SDK credential.** Set `ANTHROPIC_API_KEY`, or configure another cloud provider the Claude Agent SDK supports. The setup flow runs on this and exits without it.
2. **A Bitfab account.** Separate from the above. The flow opens a browser to sign in when it needs to and returns to the terminal.

Node 18 or newer.

## Skills

| Skill                 | What it does                                                                                 |
| --------------------- | -------------------------------------------------------------------------------------------- |
| `bitfab-setup`        | Instrument workflows, modify existing traces, inspect, replay, database snapshots, templates |
| `bitfab-analyze-repo` | Scan the repo and upload draft trace plans, with no prompts and no code edits                |
| `bitfab-account`      | Sign in and out, switch organization, health check, session logs                             |

## What the Skills Do

### Setup

`bitfab-setup` runs the same declarative workflow the editor plugins run, with browser plan review and Studio replaced by inline terminal review:

```bash theme={null}
npx bitfab-cli init --v2                 # login, then instrument
npx bitfab-cli setup --v2 instrument     # one mode
npx bitfab-cli setup --v2 --diagram      # print the state graph, no auth, no agent
```

Modes: `wizard`, `explain`, `login`, `instrument`, `modify`, `inspect`, `view`, `replay`, `db-snapshot`, `templates`, `analyze-repo`, `switch-org`, `session-logs`.

Every workflow choice and every permission for a mutating tool comes back to the terminal for you to decide. Edits are previewed as diffs before they are applied.

### Analyze repo

Reconnaissance before you commit to instrumenting anything:

```bash theme={null}
npx bitfab-cli setup --v2 analyze-repo --prompt "focus on the retrieval pipeline"
```

Ranks the AI workflows in the repository, uploads a draft trace plan for each, and prints a report of what it picked, what it skipped, and why. It edits no code. `bitfab-setup` in `instrument` mode picks those drafts up later and reconciles each against current code.

`--prompt` is the only knob on `setup --v2 analyze-repo` itself. It has no `--limit` flag and ignores one silently. To cap the run, go through the top-level command, which does support Amp:

```bash theme={null}
npx bitfab-cli analyze-repo --editor amp --limit 3
```

### Diagnostics

```bash theme={null}
npx bitfab-cli setup --v2 inspect
```

Checks authentication, what is instrumented, SDK freshness, replay coverage, and whether traces are arriving, then offers a fix per finding. Start here for "my traces are not showing up".

## Alpha limits

| Capability                                        |                 Amp                | Claude / Cursor / Codex |
| ------------------------------------------------- | :--------------------------------: | :---------------------: |
| Setup, instrument, modify                         |                 Yes                |           Yes           |
| Replay registry, database snapshots, templates    |                 Yes                |           Yes           |
| Analyze repo                                      |                 Yes                |           Yes           |
| Diagnostics and org switching                     |                 Yes                |           Yes           |
| Improvement loop (datasets, graders, experiments) |                 No                 |           Yes           |
| Studio trace plan review, Edit-with-agent         |                 No                 |           Yes           |
| Bitfab MCP tools available to the host agent      |                 No                 |           Yes           |
| Session log capture                               |                 No                 |           Yes           |
| Skill / plugin update from the CLI                | Yes (`update --editor amp plugin`) |           Yes           |
| SDK update from the CLI                           |                 No                 |           Yes           |

The native Amp plugin is planned and will replace this skill pack in place, closing these gaps.

<Note>
  `npx bitfab-cli update --editor amp sdk` has no Amp path, because the SDK update flow launches an editor agent. To check whether your SDK is behind, run `npx bitfab-cli setup --v2 inspect` and upgrade with your project's own package manager.
</Note>