GhostInTheCodebase

See what the AI builds. Know when it breaks it.

Black-box recorder and time-travel autopsy for AI coding agents.

Live demo · Playground · How it works · Features · Roadmap

🎯 One-liner for judges: TestSprite tells you the PR is red. Ghost tells you which prompt turned it red — and rolls the file back.

Agentic coding moved the bottleneck from writing code to understanding what was written. A diff can be green on types and still leak memory, spin the CPU, or slow a p95 down by 400 ms. Existing tools stop at "something is broken".

Ghost is agent-agnostic by construction: it watches the filesystem and the running process, not the agent. Cursor, Claude Code, Codex, OpenCode, or a human typing manually — they all produce the same recording.

1. Open the playground — it replays a recorded 7-turn agent session over a demo invoice app.
2. Scrub the tape dock at the bottom: turn 3 adds an unbounded in-memory cache, turn 4 re-uses it blindly, and the app starts leaking ~38 MB per request.
3. Watch the metrics chart climb, then the autopsy panel opens its verdict: the leak is attributed to turn 4, naming the file that caused it.
4. Read the AI panel: it drafts the heal prompt that fixes the cache — copy it, paste it to your agent, and the curve flattens.
5. Every step is rendered in a 3D code city: buildings are files, heat auras are runtime stress, so you feel the regression before you read it.

The replay dashboard — tape rail, 3D city, autopsy verdict on turn 4:

Full session view — seven turns, timeline dock at the bottom, live metrics:

🔍 Why this is honest: the demo session is a committed fixture (src/data/fixture.ts), and every verdict is computed live by src/autopsy/engine.ts from that data — nothing is hard-coded into the UI. The recorder underneath is live and shipped (see the status table).

The capture layer is no longer a sketch — it ships in this repository and runs today:

Ghost never needs your agent account. Mode B/C below record everything from the outside; Mode A upgrades fidelity per agent.

sequenceDiagram
    autonumber
    participant U as Developer
    participant A as Coding agent
    participant FS as Filesystem
    participant R as Ghost recorder
    participant M as Runtime monitor
    participant AT as Autopsy engine
    participant D as Dashboard

    U->>A: prompt
    A->>FS: edits code
    R->>FS: watches changes (file watcher)
    R->>R: checkpoint the change burst
    M->>A: polls app metrics (cpu, rss, latency)
    AT->>AT: detect anomaly vs baseline
    AT->>U: verdict: turn N caused the regression (with diff)
    D->>U: timeline + diff + city + attribution
    U->>U: accept rollback or copy the heal prompt
    M-->>AT: curve flattens ✔ heals confirmed

flowchart LR
    S[Metric samples<br/>per turn] --> T{Hard threshold<br/>breach?}
    S --> P{Trend slope over<br/>sliding window?}
    T -->|yes| V[Mark anomaly<br/>type + severity]
    P -->|yes| V
    V --> B[Bisect sample history<br/>per turn boundary]
    B --> BL[Blamed turn + file<br/>+ evidence window]
    BL --> H{Re-measure after rollback}
    H -->|flat| OK[Confirmed heal]
    H -->|still rising| NO[Blame rejected<br/>must keep bisecting]

Anomalies detected on the demo session: memory leak (unbounded in-memory cache), attributed to turn 4, severity high, confirmed healed at the end of the session.

flowchart TB
    subgraph DEV[Developer machine]
        subgraph AGENT[Coding agent — unchanged workflow]
            OC[OpenCode]
            AG[Antigravity / Cursor / Claude Code]
        end
        subgraph GHOSTLOCAL[Ghost Local]
            AD[Agent adapter<br/>A — events]
            FW[Filesystem watcher<br/>B — changes]
            SG[Checkpoints / diffs]
            RM[Runtime monitor<br/>C — probes]
            LQ[Local queue]
        end
        APP[(App under<br/>observation)]
    end
    subgraph GHOSTCLOUD[Ghost Cloud — dashboard]
        API[Session API]
        DB[(Metadata · metrics<br/>session summaries)]
        UI[Timeline · diff ·<br/>anomaly · autopsy]
    end
    OC -->|plugin events| AD
    AG -.->|optional adapter| AD
    AD --> FW
    FW --> SG --> LQ
    RM --> LQ
    APP --> RM
    LQ -->|consented sync:<br/>metadata + metrics,<br/>never source code| API --> DB --> UI
    HUB[Agent Tools Hub] -.->|discover ·<br/>install ·<br/>configure| GHOSTLOCAL

The demo dashboard in this repository is the UX of Ghost Cloud, replaying a session that the recorder produced. Three recording modes keep Ghost useful on day one and progressively richer:

Mode B/C first; Mode A per agent. Autopsy never fabricates a turn id: if an agent event provides one, Ghost uses it; otherwise attribution is time-based and labeled as estimated.

Ghost ships as hybrid: a local recorder + a cloud dashboard. Neither a pure SaaS (cloud servers cannot see your filesystem, your processes, or the app running on your laptop) nor a pure CLI (results get hard to share, review, and onboard onto).

• Ghost Local runs next to the repository: filesystem watcher, checkpoints/shadow-git, runtime probes, agent adapters, and a local queue. Recording must work fully without any cloud account — local-only mode is the default.
• Ghost Cloud owns accounts, projects, session history and the autopsy view. Foundation stack: Vercel for the dashboard + Session API and PostgreSQL for structured metadata, metrics, and summary verdicts. The cloud never reads files off your machine — the local recorder is the only thing that observes, and it syncs deliberately.
• Agent adapters normalize each agent's events into one internal event contract: a plugin watches OpenCode session/file/tool events, the adapter translates them, and the shared recorder + autopsy engine never change per agent. Antigravity and others plug in later without rewriting the engine.

Agent Tools Hub is the doorway, not the workspace — discover Ghost, pick your agent, read compatibility + install steps there; recording always runs on the user's machine, next to their code.

1. Sign in, create a project, point it at a repository → project_id.
2. Connect the machine: Ghost Local authenticates as a device via a one-time pairing code confirmed in the browser — the agent's account is never OAuth'd into Ghost.
3. Turn on an agent adapter (OpenCode first). No adapter? Modes B/C still record; turn identity is then marked as estimated, never invented.
4. Ghost takes a baseline, watches changes, probes the running app.
5. The dashboard shows timeline, diff, metrics, autopsy — local-only by default, sync is explicit opt-in.

timeline
    title Ghost milestones
    MVP 1 done : Local recorder persists a session : shadow-git store, dashboard replay
    MVP 2 done : Ghost Cloud - auth, projects, session API
    MVP 3 done : CLI + cloud pairing : consented sync, metadata and metrics only
    MVP 4 done : OpenCode adapter streams live session events : recorder accepts real turns
    MVP 5 next : Antigravity adapter : resilient sync : CI workflows : Agent Tools Hub listing

The recording modes and adapters are deliberately behind one internal event contract (src/types.ts): agents vary, the engine does not.

Recording works in three layers, from always-works to richest-context:

Mode B/C are the base; Mode A is added per agent. Autopsy never fabricates a turn id: when an agent event provides one it is used; otherwise attribution is time-based and explicitly labeled as estimated. Agent events (coding activity) and runtime events (app condition) are two separate data streams — the autopsy engine joins them only through timestamps, session identity, checkpoints, and test evidence.

Seed data is deterministic: users alice and bob, invoice inv-1001 owned by alice — so every status code above is reproducible on demand.

The API above is deliberately small and observable, so an end-to-end suite can be asserted precisely:

Suite status: green — 24/24 (23 unit-style backend tests + 1 integration flow) against https://ghostinthecodebase.vercel.app. Verified three ways:

1. CLI batch executions — TestSprite CLI, all tests passed (executions ddf5126a and later re-runs).
2. GitHub Actions check — .github/workflows/testsprite.yml reruns the suite on every pull request; it went green on PR #5, PR #6 and PR #7.
3. Exported test code — the exact tests TestSprite executes are committed under docs/testsprite-exports/ for full transparency.

The work behind that green: the suite flagged two real issues — a live BOLA hole on preview (missing SECURE_MODE env) and per-instance state loss on serverless — both fixed and narrated in docs/test-prd.md → Suite maintenance log. The list/shape tests were then hardened to be count-tolerant (the suite's own create tests legitimately add records on shared instances) and the integration flow was re-synced to the deployed contract after a test-code/signature mismatch caused portal-only failures.

Cases 11–13 run the actual src/autopsy/engine.ts against the committed fixture — the detector must always converge on the leak, blame turn 4, and confirm the heal. No verdict is fabricated in this repository: if the engine cannot prove it, the dashboard cannot show it.

The dashboard replays a recorded session end-to-end. The recorder underneath is live: the Ghost CLI records real agent sessions into a shadow-git store and syncs them to Ghost Cloud when a device is paired. Nothing in the UI fakes live behavior: parts that are not wired yet are not presented as working.

npm install
npm run dev        # http://localhost:3000
npm run build      # production build
npm run typecheck  # tsc --noEmit

Deploy on Vercel with framework: Next.js — no environment variables required; ownership in the demo API is enforced in code, not behind a flag.

The recorder is a plain Node script (no packages, no build step). Requires Node.js >= 18 and curl + tar (both ship with macOS, most Linux distros, and Windows 10+).

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/arko33/ghostinthecodebase/main/packages/ghost/install.sh | bash

Windows (PowerShell):

curl -fsSL https://raw.githubusercontent.com/arko33/ghostinthecodebase/main/packages/ghost/install.ps1 -o ghost-install.ps1
powershell -ExecutionPolicy Bypass -File ghost-install.ps1

Both installers download the recorder from this repo, place it in ~/.ghost, and put a ghost command on your PATH. Then, from any project directory:

ghost status     # repo head, cloud pairing state, sync policy
ghost watch      # record: watch the working tree, checkpoint each change burst, sample runtime metrics
ghost sessions   # list sessions stored in .ghost
ghost setup      # optional: pair the device with Ghost Cloud (metadata-only sync; source code never leaves the machine)

While ghost watch runs it also opens Ghost Studio in your browser — http://127.0.0.1:5417 (the recorder's own zero-dependency page): the live session shows the repo, the real turns (prompts), the files being changed with per-file churn, and the runtime samples from your app's /api/health. Data never leaves the machine.

For the full 3D playground (the same interface as the published demo, fed by YOUR recording instead of the fixture): run this repo's dashboard locally (npm run dev) and open /playground?live=1. It streams the live recording through a loopback bridge — the cloud playground sees sessions only after explicit pairing (ghost setup), never raw disks.

Using OpenCode? (Mode A — real turn ids, richest context) copy the one-file adapter into your project, then start ghost watch and use OpenCode as usual:

mkdir -p .opencode/plugins
curl -o .opencode/plugins/ghost.ts \
  https://raw.githubusercontent.com/arko33/ghostinthecodebase/main/packages/opencode-plugin/index.ts

The adapter reports turn.started (the prompt admission — the authoritative turn boundary) and turn.completed to the local recorder on 127.0.0.1:5417/events. Note: ghost watch recording — it does not start your app. Run your project as usual (e.g. npm run dev) in another terminal so the runtime probes have something to measure.

No plugin? Recording still works — the filesystem watcher + runtime probes capture everything from the outside and turns are marked estimated, never invented. Not a git repository? File recording still works; run git init to unlock shadow-git checkpoints.

• The red suite is the point. The demo ships a hole in the API; the suite catches it; PR #2-fixed-style changes make it green. Enforcing ownership is the "green" half; the regression narrative is the "catch" half.
• The deployed dashboard replays the committed fixture, so the same demo view is reproducible with no API key, no login, no network.
• npm run typecheck is part of the workflow; UI work must not touch contracts in app/api/*, src/autopsy/engine.ts, or src/types.ts.

ghostinthecodebase/
├─ app/
│  ├─ page.tsx                  # landing
│  ├─ playground/page.tsx       # playground route
│  ├─ login/page.tsx            # GitHub sign-in (Ghost Cloud)
│  ├─ pair/page.tsx             # device pairing confirm
│  ├─ styles/{landing,dashboard}.css
│  └─ api/
│     ├─ invoices/                  # live target API (+ [id])
│     ├─ auth/github/               # OAuth start + callback (+ logout)
│     └─ v1/                        # pair (+ confirm), sessions — Ghost Cloud sync
├─ src/
│  ├─ components/               # Dashboard, AIPanel, CodeDiff, GhostCity, MetricsChart
│  │  ├─ playground/            # AutopsyPanel, SessionBar, TimelineDock, city scene
│  │  └─ site/                  # landing engine: SceneLayer, GhostCanvas, Terminal, ...
│  ├─ data/fixture.ts           # the recorded demo session
│  ├─ store/invoices.ts         # in-memory store with ownership-scoped reads
│  ├─ collector/opencode.ts     # OpenCode event contract (TS mirror of the shipped plugin)
│  ├─ runner/metrics.ts         # MetricSample contract (TS mirror of ghost probes)
│  ├─ autopsy/engine.ts         # detection + attribution + heal check
│  └─ types.ts                  # Turn, MetricSample, Session contracts
├─ packages/
│  ├─ ghost/                    # the local recorder CLI — install.sh / install.ps1 (curl, no npm)
│  │  ├─ ghost.mjs              # setup / watch / status / sessions commands
│  │  └─ lib/                   # shadow-git checkpoints, session store, runtime probes
│  └─ opencode-plugin/          # Mode A adapter: streams OpenCode events to the recorder
├─ docs/
│  ├─ test-prd.md               # suite maintenance log (BOLA catch, per-instance findings)
│  └─ testsprite-exports/       # the exact test code TestSprite executes
└─ publics/ghost.png            # brand asset

Built for TestSprite Hackathon Season 4 (October 2026) — the pitch: every other tool watches the merge; Ghost watches the maker.

• Live demo: https://ghostinthecodebase.vercel.app
• Playground: https://ghostinthecodebase.vercel.app/playground

Shipped for evaluation in TestSprite Season 4. Built from scratch for this event; reuse the ideas, credit the project.