Ghoast

Ghoast writes a local handoff file so the next AI coding session knows what changed, what broke, what passed, and what to do next.

Ghoast keeps AI coding agents from losing the plot.

It is a deterministic ride-along memory layer for AI coding agents.

It is for developers using Claude Code, Codex, Cursor, or VS Code with AI coding agents.

The Handoff

You are continuing work in this repo.

Read this state first:

- Changed files:
  - src/parser.py
  - tests/test_parser.py
- Why changed: Goal: fix parser fallback behavior
- Tested: python -m pytest -q passed
- Risks: fallback path changed; watch empty-input behavior
- Current issue: none recorded
- Do next: review parser fallback, then keep changes scoped
- Verify with: python -m pytest -q

Do not rewrite unrelated code.

That is the point: the next agent starts from repo state, not from a vague prompt.

See also:

• Terminal walkthrough
• Agent starter prompt
• Handoff examples
• Architecture paper
• Current tech map

Use Ghoast When

• an AI coding session is getting long
• you are switching between Claude Code, Codex, Cursor, or VS Code
• tests failed and you need the next session to know why
• you want a clean handoff before stopping
• you want repo-local context without cloud memory

Status

Ghoast is an early local CLI devtool.

Tested with:

• Claude Code
• Codex CLI
• Cursor Agent
• VS Code adapter
• Git post-commit hooks
• CLI workflow

Current install:

python -m pip install git+https://github.com/electricwolfemarshmallowhypertext/Ghoast.git

PyPI release is pending final checks and explicit upload approval.

The Problem

AI coding agents can edit quickly, but long sessions lose chronology.

After a few rounds, the important context is scattered:

• what changed
• what broke
• what was tested
• what the next agent should do first
• what should not be touched

Ghoast writes that state down locally so the next session starts from repo context instead of guesswork.

Tested With

• Claude Code
• Codex CLI
• Cursor Agent
• VS Code adapter
• Git post-commit hooks
• Plain CLI workflow

Ghoast is local-first and agent-agnostic. Agents do not need a special SDK to use it; they only need to read the files and reports Ghoast writes.

Install

Install from GitHub:

python -m pip install git+https://github.com/electricwolfemarshmallowhypertext/Ghoast.git

For local development:

git clone https://github.com/electricwolfemarshmallowhypertext/Ghoast.git
cd Ghoast
python -m pip install -e .

The editable install puts ghoast on PATH. Git hooks call the installed command first; without it, hooks may fall back to module execution or write a warning to .ghoast/hook.log.

The installed Python package provides the Ghoast CLI. Claude commands, Cursor rules, and Git hooks are installed into your target repo by Ghoast commands. The VS Code adapter is experimental and source-checkout only for now.

Quickstart

Ghoast works inside any Git repo.

cd your-repo
ghoast setup
ghoast test "python -m pytest -q"
ghoast short
ghoast handoff

Typical output:

3 changed paths.
Main change: src/ghoast/cli.py and 2 more
Current problem: none recorded
Next step: review changed files, then run the relevant tests.

First successful setup looks like this:

Ghoast setup complete.

Installed:
- .ghoast/ runtime state
- Claude Code commands
- Cursor rule
- Git post-commit hook

Next:
- Run: ghoast snapshot
- Run: ghoast test "<your test command>"
- Run: ghoast handoff

Notes:
- VS Code adapter is source-checkout only.
- Runtime state stays in .ghoast/ and is usually not committed.

Core Commands

ghoast init
ghoast setup
ghoast snapshot
ghoast note "Current issue: fallback test still fails."
ghoast resolve
ghoast test "python -m pytest -q"
ghoast status
ghoast short
ghoast report
ghoast handoff
ghoast learn
ghoast receipts
ghoast receipts show latest
ghoast context init
ghoast context check
ghoast context activate "fix parser fallback"
ghoast context refs "handoffs#Current Handoff"
ghoast context audit
ghoast handoff --task "fix parser fallback"
ghoast audit
ghoast doctor
ghoast reset

Use this starter prompt with a new agent session:

Read Ghoast state first. Summarize the repo state. Do not edit files yet.

ghoast handoff prints context a new agent session can read before changing code:

You are continuing work in this repo.

Read this state first:

- Changed files:
  - src/ghoast/cli.py
  - tests/test_cli.py
- Known repo patterns: .ghoast/patterns.md
- Why changed: not recorded
- Tested: passed via `python -m pytest -q`
- Risks: none recorded
- Current issue: none recorded
- Do next: review changed files, then run the relevant tests.
- Verify with: python -m pytest -q

Do not rewrite unrelated code.

ghoast handoff is deterministic. It reports recorded facts only:

• Changed files
• Why changed
• Tested
• Risks
• Current issue
• Do next
• Verify with

Use notes such as Goal: ..., Why: ..., Risk: ..., or Risks: ... to fill the matching handoff fields. Use ghoast resolve or ghoast note --clear to clear the active issue.

ghoast test stores stdout and stderr in local receipt files. Avoid running commands that print secrets.

ghoast status prints a concise repo and Ghoast setup summary: Git state, changed path count, current problem, latest test, hook status, and integration status.

ghoast report refreshes .ghoast/current.md, .ghoast/timeline.md, .ghoast/issues.md, and .ghoast/patterns.md when patterns are already available or there is enough history.

ghoast receipts lists recent test receipts. ghoast receipts show latest prints the latest recorded test receipt.

Context Integrity

Ghoast preserves work state. Context integrity proves the state still matches the repo.

ghoast context init
ghoast context check
ghoast context activate "fix parser fallback"
ghoast context refs "handoffs#Current Handoff"
ghoast context audit

ghoast context init creates a small markdown memory graph under .ghoast/context/. It uses wiki-style links such as [[handoffs]] and source backlinks such as # @ghoast: [[handoffs#Current Handoff]].

ghoast context check validates context links, source-file links, and source backlinks. ghoast context refs shows what references a context target. ghoast context audit and the shorter ghoast audit print a Ghoast receipt focused on:

• what changed
• what context was affected
• what next

ghoast context activate "<task>" prints only the context sections relevant to that task. ghoast handoff --task "<task>" adds those selected snippets to the handoff instead of dumping the whole context graph.

By default this state stays local in .ghoast/context/. For CI, keep a context folder in a committed path and run:

ghoast audit --dir <committed-context-dir>

What It Creates

.ghoast/
  events.jsonl
  current.md
  timeline.md
  issues.md
  patterns.md
  context/
  receipts/

These files stay local by default. They are repo memory for tools and agents, not a hosted account or cloud sync layer.

Runtime state belongs in .ghoast/ and should usually stay uncommitted. Integration files such as .claude/commands/ and .cursor/rules/ are normal project files when a repo chooses to share agent setup.

Commit	Do Not Commit
.claude/commands/	.ghoast/
.cursor/rules/	.ghoast/receipts/
integration config files your project intentionally shares	.ghoast/hook.log
	.tmp_pytest/

Integrations

ghoast install cursor
ghoast install claude
ghoast hooks install
ghoast install vscode

ghoast install cursor writes .cursor/rules/ghoast.mdc.

ghoast install claude writes project commands under .claude/commands/.

ghoast hooks install writes .git/hooks/post-commit. The hook snapshots after commits and logs output to .ghoast/hook.log.

ghoast install vscode prints source-checkout setup steps for the experimental VS Code extension adapter. The Python package does not install integrations/vscode/ into every user repo.

To run the VS Code adapter locally:

git clone https://github.com/electricwolfemarshmallowhypertext/Ghoast.git
cd Ghoast/integrations/vscode
npm install
npm run compile

If you are already inside the Ghoast source checkout:

cd integrations/vscode
npm install
npm run compile

Then open integrations/vscode in VS Code and press F5 to launch an Extension Development Host.

Use the convenience command to install the project integrations:

ghoast install all

ghoast install all installs CLI-side project integrations: Claude commands, the Cursor rule, and the Git hook when a Git repo is present. It does not install the VS Code adapter. Run ghoast install vscode for source-checkout Extension Development Host instructions.

ghoast dashboard serves an experimental local dashboard at http://127.0.0.1:8765. The core launch surface is still the CLI, handoff text, integrations, and hooks.

Compatibility

Ghoast has been manually tested with:

• Claude Code
• Codex CLI
• Cursor Agent
• VS Code adapter
• Git post-commit hooks
• Plain CLI workflow

See:

• Compatibility checklist
• Compatibility results

Learning From Repo History

ghoast learn

ghoast learn writes .ghoast/patterns.md from local Ghoast history. It extracts common verification commands, common changed paths, a simple workflow summary, and the next likely verification command when enough history exists.

No network calls. No model calls. No probabilistic claims.

Local And Deterministic

Ghoast uses local files, Git status, test output, timestamps, and user notes.

It does not require:

• cloud sync
• accounts
• telemetry
• a daemon
• an agent SDK
• an LLM

Design Principles

• Local first
• Plain files
• Deterministic reports
• Agent agnostic
• Git-compatible, not Git-replacing
• No cloud memory claims

Known Limitations

• The VS Code adapter is source-checkout only and not published to the marketplace.
• PyPI install is not available yet; install from GitHub for now.
• The dashboard is experimental, local-only, and not the primary product surface.
• Ghoast records repo state, but it does not understand intent unless you add notes or run tests through it.
• Git hooks are best-effort and should not be treated as the only source of truth.

What Ghoast Is Not

Ghoast is not:

• an AI agent
• a coding assistant
• a cloud memory service
• a task runner
• a project manager
• a replacement for Git

It is a local repo-memory layer that writes down what changed so the next coding-agent session has context.

Why Not Just README And Git Log?

README explains the project. Git log explains committed history. Ghoast captures the working state between commits: changed files, latest tests, notes, issues, patterns, and the next handoff. It is for the messy middle of an agent session.

Uninstall Or Reset

Remove the Git hook:

ghoast hooks uninstall

Remove integrations:

ghoast uninstall claude
ghoast uninstall cursor
ghoast uninstall hooks
ghoast uninstall vscode
ghoast uninstall all

ghoast uninstall vscode does not delete integrations/vscode/; those files are source-checkout repository code, not generated user state.

Remove local runtime state:

ghoast reset

Remove committed integration files only if your project no longer wants shared agent setup:

rm -rf .claude .cursor

Local Test Notes

On Windows, if pytest cannot write to the default temp directory, use a repo-local temp directory:

powershell -ExecutionPolicy Bypass -File scripts/test.ps1

Demo And Examples

Some documentation links point to files in the GitHub repository. The Python package installs the CLI, not the full repository docs tree into each target project.

• Basic agent handoff example
• Current tech map
• Architecture paper
• Terminal walkthrough
• Agent starter prompt
• Handoff examples
• Sample current report
• Sample handoff
• Sample patterns
• Launch copy
• Screenshots needed