https://github.com/amitmishrg/ghostcode
Provider-agnostic terminal coding harness with PLAN/BUILD modes, local-first runtime, and customizable TUI.
https://github.com/amitmishrg/ghostcode
agentic-coding ai anthropic bun cli coding-harness developer-tools ghostcode harness llm local-first openai terminal-ui tui typescript
Last synced: 15 days ago
JSON representation
Provider-agnostic terminal coding harness with PLAN/BUILD modes, local-first runtime, and customizable TUI.
- Host: GitHub
- URL: https://github.com/amitmishrg/ghostcode
- Owner: amitmishrg
- License: mit
- Created: 2026-05-28T09:54:00.000Z (27 days ago)
- Default Branch: main
- Last Pushed: 2026-05-28T12:31:06.000Z (27 days ago)
- Last Synced: 2026-05-28T13:09:42.519Z (27 days ago)
- Topics: agentic-coding, ai, anthropic, bun, cli, coding-harness, developer-tools, ghostcode, harness, llm, local-first, openai, terminal-ui, tui, typescript
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/ghostcode-cli
- Size: 283 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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](docs/BUILD-YOUR-OWN-HARNESS.md)** — the five files that power the loop, fork paths, 30-minute checklist
🤝 **[Contributing](CONTRIBUTING.md)**
## 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](https://docs.anthropic.com/en/docs/claude-code), [OpenCode](https://github.com/anomalyco/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`](packages/shared/src/schemas.ts), [`system-prompt.ts`](packages/shared/src/system-prompt.ts), [`local-tools.ts`](packages/cli/src/lib/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](https://bun.sh).
```bash
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:
```bash
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`](packages/cli/) | TUI, `LocalChatTransport`, local tools, sessions |
| [`@ghostcode/shared`](packages/shared/) | Tool schemas, modes, system prompts, models |
See [Build your own harness](docs/BUILD-YOUR-OWN-HARNESS.md) for the agent loop diagram and file map.
## Configuration & storage
### Runtime store
```text
~/.ghostcode/
settings.json
Ghost.md
projects/
/
.jsonl
```
### Project-level files
```text
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`:
```text
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](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