Metadata-Version: 2.4
Name: ghoast
Version: 0.5.4
Summary: Deterministic local repo chronology for AI coding agents.
Author: Ghoast
License-Expression: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Ghoast

[![Tests](https://github.com/electricwolfemarshmallowhypertext/Ghoast/actions/workflows/test.yml/badge.svg)](https://github.com/electricwolfemarshmallowhypertext/Ghoast/actions/workflows/test.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

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

```text
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](https://github.com/electricwolfemarshmallowhypertext/Ghoast/blob/main/docs/demo.md)
- [Agent starter prompt](https://github.com/electricwolfemarshmallowhypertext/Ghoast/blob/main/docs/agent-starter-prompt.md)
- [Handoff examples](https://github.com/electricwolfemarshmallowhypertext/Ghoast/blob/main/docs/handoff-examples.md)
- [Architecture paper](https://github.com/electricwolfemarshmallowhypertext/Ghoast/blob/main/docs/ghoast-paper.md)
- [Current tech map](https://github.com/electricwolfemarshmallowhypertext/Ghoast/blob/main/docs/tech-map.md)

## 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:

```bash
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:

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

For local development:

```bash
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.

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

Typical output:

```text
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:

```text
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

```bash
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:

```text
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:

```text
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.

```bash
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:

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

## What It Creates

```text
.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

```bash
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:

```bash
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:

```bash
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:

```bash
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](docs/compatibility-checklist.md)
- [Compatibility results](docs/compatibility-results.md)

## Learning From Repo History

```bash
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:

```bash
ghoast hooks uninstall
```

Remove integrations:

```bash
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:

```bash
ghoast reset
```

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

```bash
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
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](https://github.com/electricwolfemarshmallowhypertext/Ghoast/blob/main/examples/basic-agent-handoff/README.md)
- [Current tech map](https://github.com/electricwolfemarshmallowhypertext/Ghoast/blob/main/docs/tech-map.md)
- [Architecture paper](https://github.com/electricwolfemarshmallowhypertext/Ghoast/blob/main/docs/ghoast-paper.md)
- [Terminal walkthrough](https://github.com/electricwolfemarshmallowhypertext/Ghoast/blob/main/docs/demo.md)
- [Agent starter prompt](https://github.com/electricwolfemarshmallowhypertext/Ghoast/blob/main/docs/agent-starter-prompt.md)
- [Handoff examples](https://github.com/electricwolfemarshmallowhypertext/Ghoast/blob/main/docs/handoff-examples.md)
- [Sample current report](https://github.com/electricwolfemarshmallowhypertext/Ghoast/blob/main/examples/sample-current.md)
- [Sample handoff](https://github.com/electricwolfemarshmallowhypertext/Ghoast/blob/main/examples/sample-handoff.md)
- [Sample patterns](https://github.com/electricwolfemarshmallowhypertext/Ghoast/blob/main/examples/sample-patterns.md)
- [Launch copy](https://github.com/electricwolfemarshmallowhypertext/Ghoast/blob/main/docs/launch-copy.md)
- [Screenshots needed](https://github.com/electricwolfemarshmallowhypertext/Ghoast/blob/main/docs/screenshots-needed.md)
