GhostCode

Open-source starter template for a terminal coding harness. Use it, learn from it, or fork it—you don't need Claude Code, OpenCode, or Codex to run an agent loop.

GhostCode is a local-first, provider-agnostic harness: your API keys, your machine, full source over prompts, tools, and UI. No hosted account stack.

Don't rent a harness—start from one. TUI + tool loop + sessions. Fork it, rename it, ship your version.

📖 Build your own harness — the five files that power the loop, fork paths, 30-minute checklist
🤝 Contributing

Who this is for

• Developers who want to understand how coding agents work (streaming, tools, persistence)
• Solo hackers who want to own and customize prompts, tools, and terminal UX
• Anyone building their own harness and looking for a small reference repo to fork

Who this is not for

• You need subagents, MCP, LSP, or IDE plugins today → use Claude Code, OpenCode, or similar
• You want a fully managed turnkey product with vendor roadmap → GhostCode is intentionally small and hackable
• You want benchmark-winning autonomy out of the box → this is a starting template, not a feature parity play

Why this harness

• Reference implementation — AI SDK tool loop: stream → tool call → local execute → resend → save session
• Yours to customize — change schemas.ts, system-prompt.ts, local-tools.ts
• Provider-agnostic — swap Anthropic and OpenAI models at runtime
• Local-first — no server or database in the harness loop
• PLAN / BUILD — read-only planning vs full file/shell execution
• Project memory — layered Ghost.md (global, project, and local files — see Configuration below)
• Session persistence — per-project JSONL under ~/.ghostcode/projects/

GhostCode vs turnkey agents

	Turnkey agents (Claude Code, OpenCode, Codex)	GhostCode
Goal	Best-in-class product	Template you own
Source	Vendor-controlled	Full repo, MIT
Models	Often locked or broad hosted	BYOK: Claude + GPT (extend in code)
Scope	Large ecosystems	~2 packages, ~5 core files to learn

If you prefer managed polish, use those tools. If you want to build or fork your harness, start here.

Screenshots

Launch Screen

Session View (Markdown + Tooling)

Theme Picker

Command Palette

Quick try

Requires Bun.

curl -fsSL https://bun.sh/install | bash
npm install -g ghostcode-cli
export ANTHROPIC_API_KEY=sk-ant-...
cd your-project
ghostcode

Or clone and develop:

git clone https://github.com/amitmishrg/ghostcode.git
cd ghostcode
bun install
cp .env.example .env   # optional: add keys here for local dev
export ANTHROPIC_API_KEY=...
bun run dev:cli

Harness capabilities

• Terminal UI — full-screen, keyboard-driven (OpenTUI + React)
• PLAN / BUILD modes — Tab to toggle; tools gated by mode
• Local toolchain — readFile, writeFile, editFile, glob, grep, bash
• Multi-model — Claude Sonnet/Haiku/Opus, GPT-5.4 family
• Commands — /models, /sessions, /theme, /agents, /new, /exit

Architecture

Package	Purpose
ghostcode-cli	TUI, LocalChatTransport, local tools, sessions
@ghostcode/shared	Tool schemas, modes, system prompts, models

See Build your own harness for the agent loop diagram and file map.

Configuration & storage

Runtime store

~/.ghostcode/
  settings.json
  Ghost.md
  projects/
    <encoded-project-path>/
      <session-id>.jsonl

Project-level files

my-app/
  Ghost.md
  Ghost.local.md
  .ghostcode/
    settings.json
    settings.local.json
    preferences.json

Theme precedence: settings.local.json → .ghostcode/preferences.json → settings.json → ~/.ghostcode/preferences.json → ~/.ghostcode/settings.json

Themes: Spectre, Haunt, Poltergeist, Wraith, Phantasm, Glitch

Recommended .gitignore:

Ghost.local.md
.ghostcode/settings.local.json

Modes

Mode	Tools
PLAN	readFile, listDirectory, glob, grep
BUILD	PLAN + writeFile, editFile, bash

Development scripts

Script	Description
bun run dev:cli	Run CLI with file watch
bun run build:cli	Build CLI into packages/cli/dist
bun run link:cli	Link ghostcode globally
bun run pack:cli	Generate npm tarball
bun run publish:cli	Bump patch and publish ghostcode-cli

Environment variables

Variable	Description
ANTHROPIC_API_KEY	Required for Claude models
OPENAI_API_KEY	Required for GPT models
GHOSTCODE_CONFIG_DIR	Override ~/.ghostcode
GHOSTCODE_DEV	Run from source (src) via bin

License

MIT — see LICENSE. Forks welcome; keep attribution.

Star / issue / fork

• Star if the template helps you
• Open an issue if install breaks on your OS (helps everyone)
• Fork and rename if you're shipping your own harness—we'd love to hear what you built