# faultline

> faultline is self-hosted, Sentry-compatible error and CI-failure tracking
> (Go + Dolt). You are reading the live agent instructions for the backend at
> https://faultline.live. faultline's primary interface for a coding agent is an MCP server:
> your agent lists the bugs faultline captured, reads the stack trace and
> diagnostic context, fixes the code in your editor, and marks the issue
> resolved — your repo never crosses the network.

## Wire your agent into this backend (https://faultline.live)

1. Install the MCP server (macOS / Linux):

       curl -fsSL https://faultline.live/mcp/install.sh | bash

   Or build from source:

       go install github.com/outdoorsea/faultline/cmd/faultline-mcp@latest

   Windows and manual per-platform downloads: https://faultline.live/mcp

2. Mint an API token (it starts with "fl_"):

       https://faultline.live/dashboard/account/tokens

3. Register the server with your MCP-aware editor (Claude Code, Cursor,
   Windsurf). The config shape is identical across clients:

       {
         "mcpServers": {
           "faultline": {
             "command": "faultline-mcp",
             "env": {
               "FAULTLINE_API_TOKEN": "fl_...",
               "FAULTLINE_BASE_URL": "https://faultline.live"
             }
           }
         }
       }

   FAULTLINE_BASE_URL defaults to https://faultline.live; set it to https://faultline.live
   to point the MCP at this backend.

## Tools your agent gets

- list_issues        — open bugs for the current project
- get_issue          — full detail on one bug (root cause, fix metadata)
- get_issue_context  — stack trace + breadcrumbs + device/OS + last event
- list_events        — recent events for an issue (useful for flaky bugs)
- mark_resolved      — close a bug with root cause + fix explanation + commit SHA
- snooze             — defer a bug until a date, with a reason
- capture_learning   — record a forward-looking lesson (pattern + prevention) so each fix makes future triage smarter
- list_learnings     — list this project's captured learnings; check them when triaging a new issue
- select_project     — list/pick the active project when detection is ambiguous

The first tool response prints a one-line banner naming the backend and the
resolved project, so you know immediately where you are pointed. There are no
bead / "bd" operations here — that is the autonomous Gas Town path, not the MCP.

## Which project am I working in?

The MCP detects it from "git remote origin". To pin it explicitly (most
reliable): set FAULTLINE_PROJECT_ID in the env block, or commit a
.faultline.json file ({"project_id": N}) to the repo. A repo tracked on more
than one backend has a different id on each, so prefer pinning per MCP server.

## Talk to the JSON API directly (no MCP)

Same data, REST shape, Bearer-token auth (Authorization: Bearer fl_...):

    GET   https://faultline.live/api/{project_id}/issues/
    GET   https://faultline.live/api/{project_id}/issues/{issue_id}/
    GET   https://faultline.live/api/{project_id}/issues/{issue_id}/context/
    GET   https://faultline.live/api/{project_id}/issues/{issue_id}/events/
    PATCH https://faultline.live/api/{project_id}/issues/{issue_id}/          (resolve)
    POST  https://faultline.live/api/{project_id}/issues/{issue_id}/snooze/

## More

- https://faultline.live/mcp — human-facing install page (downloads + editor config)
- https://github.com/outdoorsea/faultline — source
- https://github.com/outdoorsea/faultline/blob/main/cmd/faultline-mcp/README.md — full MCP reference
- Autonomous mode (Gas Town polecats fix bugs without you driving):
  https://github.com/gastownhall/gastown