Tests that write themselves. And fix themselves.
A local-first AI agent that watches your Python project, generates pytest suites for every change, runs them, and autonomously heals failures — all in your terminal.
Writing tests is tedious. AI codegen produces one-shot output with no feedback loop. Ghost closes the loop — it generates, runs, captures errors, and heals. Continuously. Autonomously. While you write code.
Three steps. Zero friction.
Understands your code
Ghost parses your project's AST to build a complete dependency map. Every generated test uses correct imports, class hierarchies, and function signatures.
Generates & executes
pytest runs in a subprocess. stdout, stderr, and stack traces are captured. Every test is verified to actually run — not just look pretty.
Heals itself
Syntax errors? Runtime errors? Ghost patches the test and re-runs. The Judge protocol prevents validating buggy source code.
Built for serious
Python work.
Context-aware
AST-parses your project to build a dependency graph. Generated tests use correct imports, class hierarchies, and function signatures.
Self-healing
Closed-loop control: generate → run → capture errors → patch → re-run. Supports unlimited healing cycles, configurable, default 3.
Judge protocol
On assertion failures, a secondary LLM call determines if the bug is in the test or the source. Smart enough to know when not to change the test.
Multi-provider
Groq, OpenAI, Anthropic, Ollama, OpenRouter, LM Studio — or any OpenAI-compatible endpoint. Your API key, your model, your call.
Local & private
Full support for Ollama and LM Studio. Your code never leaves your machine. Air-gapped. Your code stays yours.
Daemon mode
Background process with PID file, rotating logs (10MB × 5), graceful shutdown. Set it and forget it.
Generate. Run. Heal.
Repeat.
Ghost implements a closed-loop control system. Every test goes through up to 3 healing iterations (configurable). Each cycle: run, capture, classify, patch, re-run.
Smart enough to know
when not to change
the test.
On assertion failures, a secondary LLM call determines if the bug is in the test or in your source code. If the source is buggy, Ghost alerts you instead of breaking the test.
Your key. Your model.
Your call.
Quickstart
From zero to self-healing tests in under 2 minutes.
That's it. Save any .py file and Ghost will generate, run, and heal tests automatically. See the GitHub repo for the full source.
Installation
Three ways to install Ghost. Pick your favorite.
Requirements: Python 3.10+. Optional: Ollama or LM Studio for local-only mode.
Configuration
The ghost.toml file lives in your project root. Created by ghost init.
| Section | Key | Default |
|---|---|---|
| ai | provider | groq |
| ai | rate_limit_rpm | 30 |
| tests | max_heal_attempts | 3 |
| tests | use_judge | true |
| watcher | debounce_seconds | 15 |
ghost init
Scan your project, create configuration, build context map.
Walks your project tree with CodeAnalyzer, builds a JSON map of every function, class, and import. Skips .venv, __pycache__, etc.
ghost watch
Foreground file watcher. Stays in your terminal.
Uses watchdog filesystem monitoring. Press Ctrl+C to stop.
ghost start / stop / status
Run Ghost as a background daemon.
Rotating logs at 10MB × 5 files. SIGHUP is ignored. ghost logs -f tails the log file.
ghost generate
One-shot test generation for a specific file. Perfect for CI/CD.
Use in CI pipelines: ghost generate && pytest on every PR.
ghost config
View or edit configuration.
Env var precedence: env var > ghost.toml > defaults. .env file auto-loaded if present.
ghost providers
List available providers and check connectivity.
Auto-detect order: Ollama → LM Studio → env vars (GROQ_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, OPENROUTER_API_KEY).
ghost doctor
Diagnose your Ghost installation.
Run this first if anything isn't working. Exits with code 1 if any check fails.
How it works
The complete pipeline from file save to passing test.
The Judge Protocol
How Ghost knows when NOT to change the test.
When pytest raises an AssertionError (classified as LOGIC), Ghost doesn't blindly "fix" the test. Instead it makes a secondary LLM call — the Judge — passing it the source code, the test code, and the error trace.
This prevents the failure mode where an AI "fixes" tests to match buggy source code, silently validating incorrect behavior. Source: ghost/chat.py.
Daemon Internals
How Ghost runs as a background process.
Source: ghost/daemon.py, ghost/job_queue.py.
Provider Comparison
All 7 providers supported by Ghost.
| Provider | Privacy | Speed | Cost |
|---|---|---|---|
| Groq | Cloud | Blazing (100+ tok/s) | Free tier |
| OpenAI | Cloud | Fast | Pay-per-use |
| Anthropic | Cloud | Fast | Pay-per-use |
| Ollama | 100% local | Moderate (HW dependent) | Free |
| LM Studio | 100% local | Moderate (HW dependent) | Free |
| OpenRouter | Cloud | Fast | Pay-per-use |
| Custom | Varies | Varies | Varies |
All providers implement BaseProvider ABC. Source: ghost/providers.py.
Error Classification
How Ghost decides what to do with a failing test.
| Type | Examples | Behavior |
|---|---|---|
| SYNTAX | IndentationError, ImportError | Auto-heal |
| RUNTIME | AttributeError (hallucinated method) | Auto-heal |
| LOGIC | AssertionError | Consult Judge |
| UNKNOWN | Any other error | Auto-heal |
Source: ghost/runner.py (classify_error), ghost/main.py (check_test).
FAQ
Common questions, answered.
Only if you choose a cloud provider (Groq, OpenAI, Anthropic, OpenRouter). With Ollama or LM Studio, everything stays local.
Python 3.10 and above.
Yes. ghost generate <file> runs one-shot generation — perfect for pipelines.
Yes. View on GitHub.
From zero to self-healing in one command.
What developers say. (Trust me bro)
Ghost wrote 47 tests for our legacy auth module overnight. Three of them caught a real bug we'd been chasing for weeks.
The Judge protocol is the part that sold me. Other tools blindly "fix" tests to match buggy code. Ghost actually knows the difference.
Ran it on Ollama with a local Llama model. Zero data egress, zero API costs. Our security team actually approved it.
Stop writing tests.
Start shipping code.
Install Ghost in your project today. Watch your coverage climb while you sleep.