{"id":50680416,"url":"https://github.com/amitmishrg/ghostcode","last_synced_at":"2026-06-08T18:04:26.766Z","repository":{"id":360917614,"uuid":"1252216900","full_name":"amitmishrg/ghostcode","owner":"amitmishrg","description":"Provider-agnostic terminal coding harness with PLAN/BUILD modes, local-first runtime, and customizable TUI.","archived":false,"fork":false,"pushed_at":"2026-05-28T12:31:06.000Z","size":290,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-28T13:09:42.519Z","etag":null,"topics":["agentic-coding","ai","anthropic","bun","cli","coding-harness","developer-tools","ghostcode","harness","llm","local-first","openai","terminal-ui","tui","typescript"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/ghostcode-cli","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/amitmishrg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-28T09:54:00.000Z","updated_at":"2026-05-28T12:31:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/amitmishrg/ghostcode","commit_stats":null,"previous_names":["amitmishrg/ghostcode"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/amitmishrg/ghostcode","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amitmishrg%2Fghostcode","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amitmishrg%2Fghostcode/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amitmishrg%2Fghostcode/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amitmishrg%2Fghostcode/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/amitmishrg","download_url":"https://codeload.github.com/amitmishrg/ghostcode/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amitmishrg%2Fghostcode/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34073842,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-coding","ai","anthropic","bun","cli","coding-harness","developer-tools","ghostcode","harness","llm","local-first","openai","terminal-ui","tui","typescript"],"created_at":"2026-06-08T18:04:22.475Z","updated_at":"2026-06-08T18:04:26.752Z","avatar_url":"https://github.com/amitmishrg.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GhostCode\n\n\u003e **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.\n\nGhostCode is a **local-first**, **provider-agnostic** harness: your API keys, your machine, full source over prompts, tools, and UI. No hosted account stack.\n\n**Don't rent a harness—start from one.** TUI + tool loop + sessions. Fork it, rename it, ship your version.\n\n📖 **[Build your own harness](docs/BUILD-YOUR-OWN-HARNESS.md)** — the five files that power the loop, fork paths, 30-minute checklist  \n🤝 **[Contributing](CONTRIBUTING.md)**\n\n## Who this is for\n\n- Developers who want to **understand** how coding agents work (streaming, tools, persistence)\n- Solo hackers who want to **own and customize** prompts, tools, and terminal UX\n- Anyone building **their own** harness and looking for a small reference repo to fork\n\n## Who this is not for\n\n- 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\n- You want a **fully managed** turnkey product with vendor roadmap → GhostCode is intentionally small and hackable\n- You want benchmark-winning autonomy out of the box → this is a **starting template**, not a feature parity play\n\n## Why this harness\n\n- **Reference implementation** — AI SDK tool loop: stream → tool call → local execute → resend → save session\n- **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)\n- **Provider-agnostic** — swap Anthropic and OpenAI models at runtime\n- **Local-first** — no server or database in the harness loop\n- **PLAN / BUILD** — read-only planning vs full file/shell execution\n- **Project memory** — layered `Ghost.md` (global, project, and local files — see Configuration below)\n- **Session persistence** — per-project JSONL under `~/.ghostcode/projects/`\n\n## GhostCode vs turnkey agents\n\n| | Turnkey agents (Claude Code, OpenCode, Codex) | GhostCode |\n| --- | --- | --- |\n| Goal | Best-in-class product | **Template you own** |\n| Source | Vendor-controlled | Full repo, MIT |\n| Models | Often locked or broad hosted | BYOK: Claude + GPT (extend in code) |\n| Scope | Large ecosystems | ~2 packages, ~5 core files to learn |\n\nIf you prefer managed polish, use those tools. If you want to **build or fork your harness**, start here.\n\n## Screenshots\n\n### Launch Screen\n\n![GhostCode launch screen](docs/screenshots/launch-screen.png)\n\n### Session View (Markdown + Tooling)\n\n![GhostCode session view](docs/screenshots/session-view.png)\n\n### Theme Picker\n\n![GhostCode theme picker](docs/screenshots/theme-picker.png)\n\n### Command Palette\n\n![GhostCode command palette](docs/screenshots/command-palette.png)\n\n## Quick try\n\nRequires [Bun](https://bun.sh).\n\n```bash\ncurl -fsSL https://bun.sh/install | bash\nnpm install -g ghostcode-cli\nexport ANTHROPIC_API_KEY=sk-ant-...\ncd your-project\nghostcode\n```\n\nOr clone and develop:\n\n```bash\ngit clone https://github.com/amitmishrg/ghostcode.git\ncd ghostcode\nbun install\ncp .env.example .env   # optional: add keys here for local dev\nexport ANTHROPIC_API_KEY=...\nbun run dev:cli\n```\n\n## Harness capabilities\n\n- **Terminal UI** — full-screen, keyboard-driven (OpenTUI + React)\n- **PLAN / BUILD modes** — Tab to toggle; tools gated by mode\n- **Local toolchain** — `readFile`, `writeFile`, `editFile`, `glob`, `grep`, `bash`\n- **Multi-model** — Claude Sonnet/Haiku/Opus, GPT-5.4 family\n- **Commands** — `/models`, `/sessions`, `/theme`, `/agents`, `/new`, `/exit`\n\n## Architecture\n\n| Package | Purpose |\n| --- | --- |\n| [`ghostcode-cli`](packages/cli/) | TUI, `LocalChatTransport`, local tools, sessions |\n| [`@ghostcode/shared`](packages/shared/) | Tool schemas, modes, system prompts, models |\n\nSee [Build your own harness](docs/BUILD-YOUR-OWN-HARNESS.md) for the agent loop diagram and file map.\n\n## Configuration \u0026 storage\n\n### Runtime store\n\n```text\n~/.ghostcode/\n  settings.json\n  Ghost.md\n  projects/\n    \u003cencoded-project-path\u003e/\n      \u003csession-id\u003e.jsonl\n```\n\n### Project-level files\n\n```text\nmy-app/\n  Ghost.md\n  Ghost.local.md\n  .ghostcode/\n    settings.json\n    settings.local.json\n    preferences.json\n```\n\nTheme precedence:\n`settings.local.json` → `.ghostcode/preferences.json` → `settings.json` → `~/.ghostcode/preferences.json` → `~/.ghostcode/settings.json`\n\nThemes: `Spectre`, `Haunt`, `Poltergeist`, `Wraith`, `Phantasm`, `Glitch`\n\nRecommended `.gitignore`:\n\n```text\nGhost.local.md\n.ghostcode/settings.local.json\n```\n\n## Modes\n\n| Mode | Tools |\n| --- | --- |\n| `PLAN` | `readFile`, `listDirectory`, `glob`, `grep` |\n| `BUILD` | PLAN + `writeFile`, `editFile`, `bash` |\n\n## Development scripts\n\n| Script | Description |\n| --- | --- |\n| `bun run dev:cli` | Run CLI with file watch |\n| `bun run build:cli` | Build CLI into `packages/cli/dist` |\n| `bun run link:cli` | Link `ghostcode` globally |\n| `bun run pack:cli` | Generate npm tarball |\n| `bun run publish:cli` | Bump patch and publish `ghostcode-cli` |\n\n## Environment variables\n\n| Variable | Description |\n| --- | --- |\n| `ANTHROPIC_API_KEY` | Required for Claude models |\n| `OPENAI_API_KEY` | Required for GPT models |\n| `GHOSTCODE_CONFIG_DIR` | Override `~/.ghostcode` |\n| `GHOSTCODE_DEV` | Run from source (`src`) via bin |\n\n## License\n\nMIT — see [LICENSE](LICENSE). Forks welcome; keep attribution.\n\n## Star / issue / fork\n\n- **Star** if the template helps you\n- **Open an issue** if install breaks on your OS (helps everyone)\n- **Fork** and rename if you're shipping your own harness—we'd love to hear what you built\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famitmishrg%2Fghostcode","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famitmishrg%2Fghostcode","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famitmishrg%2Fghostcode/lists"}