Skip to main content
Glama

Ghostkeep

Verified handoffs between free AI coding tools.

tests

Ghostkeep demo: one command reads every tool's session log and checks each claim against git

When you switch from Claude Code to Antigravity CLI (limit hit, missing feature, second opinion), the files carry over but the story doesn't. The next agent can't tell what was asked, who changed what, or whether the last agent's claimed work actually happened. Ghostkeep keeps one append-only ledger per project and checks every claim against git, with no LLM, no API key and no server.

Status: v0.5.0 (auto-handoff + doctor), early and improving. Automatic capture from Claude Code, Antigravity (IDE + CLI) and Codex session logs, claims checked against git, decisions captured in your own words, and ghostkeep handoff. Tests and a labeled eval gate run on Windows, macOS and Linux on every push.

Install and run

Needs Python 3.10+. No dependencies, no server, no API key.

# run it once, nothing to install (needs uv)
uvx --from git+https://github.com/Akshu24Tech/ghostkeep ghostkeep handoff

# or install the command
pipx install git+https://github.com/Akshu24Tech/ghostkeep
# or
pip install git+https://github.com/Akshu24Tech/ghostkeep

# reading Codex's older compressed (.zst) sessions is an optional extra
pipx install "ghostkeep[codex] @ git+https://github.com/Akshu24Tech/ghostkeep"
cd your-project
ghostkeep handoff            # read session logs, check claims against git, write .ghostkeep/HANDOFF.md

Then tell the next agent: "Read .ghostkeep/HANDOFF.md first." For a browser chat, paste the file in.

Or set it up once per project so you don't have to ask:

ghostkeep setup     # Claude Code: a SessionStart hook loads the handoff automatically
                    # Codex / Antigravity: a "read the handoff first" block in AGENTS.md
ghostkeep doctor    # is every tool's log being read? did the hook actually run?

The Claude Code hook is automatic: it runs on every start, resume, /clear and compaction, never breaks the session (it always exits 0) and records each run so doctor can prove it ran. The AGENTS.md block is advice an agent can skip. If a tool's log format changes and Ghostkeep can no longer read it, the handoff says so at the top instead of quietly showing less. ghostkeep setup --remove undoes it.

ghostkeep handoff reads the logs these tools already keep on disk, so no agent has to follow a rule:

Tool

Log read

Claude Code

~/.claude/projects/<repo-path>/<session>.jsonl

Antigravity IDE agent

~/.gemini/antigravity/brain/<id>/.system_generated/logs/transcript.jsonl

Antigravity CLI

~/.gemini/antigravity-cli/brain/<id>/.system_generated/logs/transcript.jsonl

Codex

~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl (older .zst files need the codex extra)

Expected line counts come from the agent's own edit calls, not its summary. Codex edits through shell commands, so its files are found in apply_patch and file-write commands. Secrets are redacted. These are internal formats and can change in any update.

Manual logging still works for tools without readable logs:

ghostkeep init
ghostkeep log --tool antigravity-ide \
  --asked 'Add one line "it is completed" at the end of docs/RESULTS.md.' \
  --claimed "Added the line." --file docs/RESULTS.md:+1-0
ghostkeep check              # exit 1 if any mismatch or orphan change
ghostkeep show
[BAD] mismatch    e_a7ce363193a7 antigravity-ide
      count_mismatch    docs/RESULTS.md  (expected +1 -0, actual +3 -0)
[???] orphan      no claim
      no_claim          stray.py  (untracked)

Related MCP server: MCP Shared Memory Hub

Decisions over time

A handoff is a budgeted slice; .ghostkeep/STATE.md is the full picture, rebuilt from the ledger on every ghostkeep handoff (or ghostkeep state). No LLM, nothing in the ledger is ever rewritten.

  • Decisions stay pinned while they're in force, however many sessions came after.

  • A decision is replaced only on explicit wording ("SQLite instead of JSON", "switch from Flask", "no longer use Redis") that names something an older decision used. Shared words alone never replace anything.

  • Unfinished work stays open until a later session finishes it (same request, or same files checked against git), not just for the last three sessions.

  • You can correct it, and your call always wins:

ghostkeep state                      # what's in force, what's open, what was replaced
ghostkeep retire d_1a2b              # this decision no longer holds
ghostkeep supersede d_1a2b d_9f8e    # d_9f8e replaced d_1a2b
ghostkeep done e_77c1                # that unfinished task is finished
ghostkeep reopen d_1a2b              # undo any of the above

How well this holds up is so far measured on 7 synthetic long-run eval cases (old decision after 10 sessions, reversal, false reversal, user corrections, interrupted work, 50 decisions) plus two real sessions. A long real-world run is still to come.

Statuses

Status

Means

verified

The file changed exactly as the agent claimed, and it's committed

uncommitted

Matches the claim, not committed yet

mismatch

The claim doesn't match git, e.g. "added 1 line" but the diff shows 3

claimed but not on disk

The agent said it edited a file and git shows no change: still pending in the IDE, or rejected

orphan

A file changed and no session claims it

superseded

A later session changed the same file

The accept/reject click in an IDE isn't recorded in any session log, so git is the ground truth. See docs/LEDGER.md for the ledger format.

Why

Measured on a real project (10 Nov 2026): after a tool switch, plain agents found what changed but got who, status or the task itself wrong in 4 of 5 answers, and Antigravity CLI confidently resumed the wrong task after a Claude session was cut off mid-way.

Then the same test with Ghostkeep (11 Nov 2026): Claude cut off mid-task, ghostkeep handoff run, Antigravity CLI told to read .ghostkeep/HANDOFF.md first. It named the right task and the interrupted file, and continued without being re-told.

Earlier version

The v2.1 "Claims Register" prototype (watcher, extractor, auditor, MCP server) is kept on the legacy branch and in this repo's history. v0.1 restarts the code around one narrower job: checking agent claims about their own work at the moment you switch tools. Ideas carried over: append-only log, the writer never sets its own status, deterministic checks only, and decision/preference capture from the user's own words.

Tests and evals

python -m pytest -q          # unit tests
python evals/run.py          # 39 labeled cases scored on 17 metrics, writes evals/RESULTS.md
python evals/run.py --gate   # exit 1 if any metric is below target (what CI runs)
python evals/label_real.py   # label Ghostkeep's output on your own sessions, then --score

The eval cases are small fake projects with session logs in each tool's real format and the right answer written down: claimed files and line counts, verdicts, orphans, who changed what, decisions captured, unfinished work first, plus adversarial cases (planted instructions in an agent's message, secrets, malformed logs, sessions from another repo). Cases in the realdata group reproduce bugs found by labeling real sessions. Latest numbers: evals/RESULTS.md. How Ghostkeep scores against an agentic system design review, and what's left: docs/DESIGN_AUDIT.md.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides persistent, searchable memory for MCP-compatible agents, enabling recall by meaning, automatic decay, trust scoring, and cross-agent handoffs.
      5
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables multiple MCP-compatible AI clients to share persistent, versioned project knowledge across sessions with conflict-safe updates, provenance, hybrid retrieval, stale-memory handling, and context-budgeted recall.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides persistent, shared memory for AI agents via MCP, enabling retrieval of relevant memories instead of loading entire context. Allows agents across projects, machines, and tools to share a single auditable, markdown-native brain.
      5
      AGPL 3.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables self-hosted, provenance-aware shared memory with scoped access, attributed observations, correction history, disagreement tracking, and durable idempotent writes for humans and AI agents via REST and MCP.
      1
      Apache 2.0