Ghost

Commit intentions, not code.

Ghost is a CLI that flips the git workflow: instead of committing code, you commit prompts. An AI coding agent generates the artifacts; the commit captures both the intent and the output. Your git history becomes a chain of prompts + their results.

Supports claude, gemini, codex, and opencode — swap agents per-commit or set a default.

The Idea

Code is ephemeral. Intent is permanent.

Every ghost commit answers: what did I want to happen here? Not what bytes changed. Each commit is reproducible from its prompt — if the code breaks, you have the exact instruction that generated it. The git log reads like a design document, not a diff summary.

git log --oneline

a3f2c1b  add JWT authentication middleware
7e91d4a  create user registration endpoint with email validation
2bc0f88  scaffold Express app with TypeScript and Prettier

Each of those is a ghost commit. Behind each message is an AI that turned words into working code, and a session ID that ties the output back to the generation.

Why Intent-Based Commits?

Code is the artifact, intent is the source of truth.

When you read a traditional git log, you see what changed. With ghost, you see prompts — the human decision that triggered the change. A year from now when LLMs are more amazing you can replay the git log and generate a better version.

Every commit is reproducible. The prompt is preserved with some extra attributes about which model and agent was used. You can re-run any commit against a fresh checkout to see what Claude generates from the same instruction.

The log becomes a design document. Read ghost log top-to-bottom and you’ll see the intent behind every architectural decision, not just the code that resulted from it.

Diffs show what the AI decided; messages show what you asked for. The two together give you full context: the goal and the implementation, inseparably linked.

How It Works

you: ghost commit -m "add user auth with JWT"
     ↓
agent generates code → files written to working tree
     ↓
ghost detects changes → stages new/modified files
     ↓
git commit with enriched message (prompt + agent + model + session + file list)

Quick Start

Commands

Examples

# New feature (default agent: claude)
ghost commit -m "add a login page with email/password form and client-side validation"

# Use Gemini
ghost commit --agent gemini -m "refactor the database layer to use connection pooling"

# Use Codex
ghost commit --agent codex -m "fix the race condition in the payment processing queue"

# Use OpenCode
ghost commit --agent opencode -m "add OpenAPI documentation for all endpoints"

# With a specific model
ghost commit --agent claude --model claude-opus-4-6 -m "architect a microservices migration plan as code comments"

# Preview without committing
ghost commit --dry-run -m "add OpenAPI documentation for all endpoints"

# Set default agent via env
GHOST_AGENT=gemini ghost commit -m "scaffold a new service"

# Manual commit (bypass ghost entirely)
GHOST_SKIP=1 ghost commit -m "bump version to 1.2.0"

Commit Message Format

Every ghost commit has an enriched message body:

add a login page

ghost-meta
ghost-prompt: add a login page
ghost-agent: claude
ghost-model: claude-sonnet-4-6
ghost-session: 7f3a2b1c-4d5e-6f7a-8b9c-0d1e2f3a4b5c
ghost-files: src/pages/login.tsx,src/hooks/useAuth.ts,src/api/auth.ts

Configuration

Requirements

• git 2.x+
• bash 4+
• uuidgen (available on macOS and most Linux distros)
• Agent CLI installed and configured for whichever agent(s) you use:
  • claude: claude CLI
  • gemini: gemini CLI
  • codex: codex CLI
  • opencode: opencode CLI

Running Tests

The integration test spins up a temp git repo, runs a full ghost workflow including generating and compiling a C program, and verifies all metadata fields.