# @sailfish-ai/autofix

Standalone installer for Sailfish Autofix — enables AI-powered bug fixing across AI coding agents without the desktop app.

## Quick Start

```bash
npx @sailfish-ai/autofix setup
```

This single command will:

1. Open your browser to authenticate with Sailfish
2. Detect which AI coding agents are installed on your machine
3. Install the Autofix skill and MCP server for each detected agent

Once setup is complete, open any supported agent and use `/sailfish-autofix <issue-id>` to investigate and fix issues.

## Prerequisites

- **Node.js** >= 18.0.0
- A **Sailfish account** (sign up at [app.sailfish.ai](https://app.sailfish.ai))
- At least one supported AI coding agent installed

## Installation

### Option A: One-command setup (recommended)

No global install needed — `npx` runs it directly:

```bash
npx @sailfish-ai/autofix setup
```

### Option B: Install globally

```bash
npm install -g @sailfish-ai/autofix
sailfish-autofix setup
```

### Option C: From the Sailfish web app

Click "Fix with CLI" on any issue page to get a one-liner with an embedded auth token:

```bash
npx @sailfish-ai/autofix setup --token <token>
```

### Option D: Via Agent Skills

If your tool supports the [Agent Skills](https://agentskills.io) standard:

```bash
npx skills add @sailfish-ai/autofix
```

Note: This installs only the skill. Run `npx @sailfish-ai/autofix setup` separately to configure authentication and the MCP server.

## Supported Agents

| Agent | Skill Location | MCP Config Location |
|-------|---------------|---------------------|
| Claude Code | `~/.claude/skills/` | `~/.claude.json` |
| Cursor | `~/.cursor/skills/` | `~/.cursor/mcp.json` |
| Codex (OpenAI) | `~/.codex/skills/` | `~/.codex/config.toml` |
| GitHub Copilot | `~/.agents/skills/` | `~/.vscode/mcp.json` |
| OpenCode | `~/.agents/skills/` | `~/.config/opencode/config.json` |
| Windsurf | `~/.windsurf/skills/` | `~/.windsurf/mcp.json` |
| Gemini CLI | `~/.gemini/skills/` | `~/.gemini/settings.json` |
| Goose | `~/.agents/skills/` | `~/.config/goose/config.yaml` |
| Generic (Agent Skills) | `~/.agents/skills/` | Manual MCP setup |

All agents also get a copy at `~/.agents/skills/sailfish-autofix/` (cross-client convention).

## Commands

### `setup` — All-in-one install

```bash
npx @sailfish-ai/autofix setup [options]
```

Authenticates, detects agents, and installs the skill + MCP server configuration.

| Option | Description |
|--------|-------------|
| `--token <token>` | Use a pre-authenticated token from the Sailfish web app |
| `--global` | Install skill globally for all projects (default: true) |
| `--agents <list>` | Comma-separated list of agents to configure (e.g. `claude-code,cursor`) |
| `-y, --yes` | Skip confirmation prompts |

### `uninstall` — Clean removal

```bash
npx @sailfish-ai/autofix uninstall [options]
```

Removes all installed skills, MCP configurations, and optionally credentials.

| Option | Description |
|--------|-------------|
| `--keep-credentials` | Keep authentication credentials (only remove skill + MCP config) |
| `-y, --yes` | Skip confirmation prompts |

### `login` — Authenticate

```bash
npx @sailfish-ai/autofix login [options]
```

Opens your browser to sign in via OAuth. Credentials are stored at `~/.sailfish/credentials.json`.

| Option | Description |
|--------|-------------|
| `--token <token>` | Exchange a short-lived token instead of browser flow |

### `logout` — Remove credentials

```bash
npx @sailfish-ai/autofix logout
```

### `status` — Show current state

```bash
npx @sailfish-ai/autofix status
```

Displays authentication status and which agents have the skill and MCP server installed.

### `doctor` — Diagnose issues

```bash
npx @sailfish-ai/autofix doctor
```

Checks credentials, backend connectivity, and agent installations. Suggests fixes for any issues found. If credentials are expired, doctor will attempt to re-authenticate automatically.

### `serve` — Run MCP server

```bash
npx @sailfish-ai/autofix serve
```

Starts the MCP server in STDIO mode. This command is used internally by agent configurations — you don't need to run it manually.

### `fork` — Resume an autofix session in another agent

```bash
npx @sailfish-ai/autofix fork <issue-id> [--agent <target>]
```

Downloads the conversation from the latest Autofix run for an issue and **resumes it inside a coding agent of your choice** — so you can pick up where the automated run left off, in the tool you prefer. It reconstructs the session (task, action log, tool outputs, files touched, decisions) and opens the agent on it, then the agent greets you with a short **branch/worktree orientation** that asks how you want to proceed before it touches any code.

**Prerequisites:** you must be authenticated first (`login` or `setup`) — `fork` downloads the run from the Sailfish backend. For the auto-launching targets you also need that agent's CLI on your PATH. The `<issue-id>` is the numeric ID from the issue's page in the Sailfish web app.

| Option | Description |
|--------|-------------|
| `--agent <target>` | Which agent to resume in (default: `claude-code`). See targets below. |
| `--native` | `opencode`/`gemini` only: use the native import/checkpoint path (higher fidelity, but pinned to the tool's version) instead of the default portable `RESUME.md`. |
| `--cwd <path>` | Repo to resume in (default: current git root). The session's file paths are patched to this checkout. |

**Targets** (`--agent <target>`):

| Target | Aliases | Default | How it resumes |
|--------|---------|---------|----------------|
| `claude-code` *(default)* | `cc`, `claude` | native | writes the session into `~/.claude`, `claude --resume` |
| `goose` | — | native | `goose session import` (via goose's own CC importer) → resumes the named session |
| `codex` | — | portable | `.sailfish-resume/` package, auto-launches Codex pointed at it |
| `cursor` | `cursor-agent` | portable | `.sailfish-resume/` package, auto-launches Cursor (`@.sailfish-resume/RESUME.md`) |
| `opencode` | `oc` | **portable** | `.sailfish-resume/` package + manual steps. `--native`: `opencode import` (pinned to opencode's version) |
| `gemini` | `gemini-cli` | **portable** | `.sailfish-resume/` package + manual steps. `--native`: `/chat resume` checkpoint (pinned to gemini's version) |
| `windsurf` | `devin` | portable | `.sailfish-resume/` package + manual "@-mention in Devin Desktop" steps |

**Resume modes.** `claude-code` and `goose` resume **natively** — they ride on Claude Code's own transcript format, so it's robust. `opencode` and `gemini` *can* resume natively, but their native paths reverse-engineer those tools' private, version-pinned formats, so they **default to the portable path** (a `RESUME.md` the agent reads, which survives version bumps); pass `--native` for full-fidelity native resume. `codex`/`cursor`/`windsurf` are portable-only (no native path — `--native` errors).

`codex`/`cursor` **auto-launch** the portable package; `opencode`/`gemini`/`windsurf` print **manual** steps — open the agent, then paste the one-line resume prompt it prints in a framed block. That prompt `@`-mentions `@.sailfish-resume/RESUME.md`, so the agent pulls the file into context and follows it. Their TUIs/GUI can't be launched with an initial prompt.

The portable package lands in a dedicated **`.sailfish-resume/`** subdir with a bundled `.gitignore` — so it never clobbers a file you own and never lands in a commit.

```bash
# Resume issue 3088309's autofix run in Cursor
npx @sailfish-ai/autofix fork 3088309 --agent cursor
```

When it works, the agent opens already loaded with the run's conversation and greets you with the branch/worktree orientation. `No autofix run found for issue …` means autofix hasn't run on that issue yet; `No session log found for this run` means the run is still in progress or too old to resume.

> **Note:** Copilot and the Generic target (listed under *Supported Agents* above) are configured by `setup` but are **not** `fork` targets — use one of the agents in the table above.

## How It Works

The package installs two things for each detected agent:

1. **Agent Skill** (`SKILL.md`) — A workflow file following the [Agent Skills](https://agentskills.io) open standard. It tells the AI agent how to investigate and fix issues using Sailfish telemetry data.

2. **MCP Server** — A [Model Context Protocol](https://modelcontextprotocol.io) server that provides 12 tools for accessing telemetry:

   | Tool | Description |
   |------|-------------|
   | `autofix_get_issue_overview` | Fetch the issue overview: description, customer report, exception details, stack traces, session IDs |
   | `autofix_get_backend_logs` | Server-side logs for a recording session |
   | `autofix_get_exceptions` | All captured exceptions in a session/window (co-occurring or unattributed, not just the issue's) |
   | `autofix_get_frontend_logs` | Browser console logs |
   | `autofix_get_network_request_logs` | HTTP request/response logs |
   | `autofix_get_network_hops` | Service-to-service call chain (distributed tracing) |
   | `autofix_get_print_statements` | stdout/print output |
   | `autofix_get_user_actions` | User interaction events (clicks, navigation) |
   | `autofix_get_frontend_display_data` | Frontend display state snapshots |
   | `autofix_update_issue_status` | Report fix progress back to Sailfish |
   | `autofix_create_pull_request` | Create a PR via GitHub/Bitbucket integration |
   | `autofix_clone_repos` | Clone company repos locally |

## Credentials & Authentication

Credentials are stored at `~/.sailfish/credentials.json` with mode `0600` (owner read/write only).

The MCP server reads credentials via the `SAILFISH_JWT_FILE` environment variable, which is set automatically in agent configurations.

### Coexistence with Desktop App

This package works alongside the Sailfish desktop app (Veritas). They use compatible credential formats but separate configuration paths:

- **Desktop app**: writes MCP config as `sailfishTelemetry` / `sailfishEnterprise`
- **Standalone CLI**: writes MCP config as `sailfishAutofix`
- Both can coexist in the same agent configuration

## Troubleshooting

### "No supported agents detected"

The installer checks for known config directories and binaries. If your agent isn't detected:

```bash
npx @sailfish-ai/autofix setup --agents claude-code
```

### "Credentials expired"

```bash
npx @sailfish-ai/autofix login
```

### "Cannot reach backend"

Run `npx @sailfish-ai/autofix doctor` to diagnose connectivity issues. Ensure you can reach `https://ui-api.sailfish.ai` from your network.

### Verify installation

```bash
npx @sailfish-ai/autofix status
```

Shows which agents have the skill and MCP server installed. All entries should show `skill` and `mcp`.

## License

MIT