GhostCode

Terminal AI coding assistant. Chat with 9 AI providers, auto-save code blocks, keep persistent memory, and delegate read-only exploration to a subagent.

npm i -g ghostcode
ghostcode

Requirements

• Node.js ≥ 22 (npm distribution), or Bun ≥ 1.1 (preferred — single binary, no install step)
• SQLite via bun:sqlite (Bun) or better-sqlite3 (Node fallback)

Install

# npm (Node 22+)
npm i -g ghostcode

# single binary (Bun) — build yourself
bun run build:binary
./dist/ghostcode

# Homebrew / Scoop (see distrib/ for manifests)
brew install ghostcode
scoop install ghostcode

Quick start

# connect a provider key
ghostcode api connect openai sk-...

# start the chat REPL
ghostcode

# non-interactive question, writes files on approval
ghostcode ask "add error handling to src/main.ts"

# point the agent at a directory (security boundary)
ghostcode --dir ~/my-project

# pick a different provider/model for this session
ghostcode --provider grok --model grok-3

Features

• 9 AI providers — OpenAI, Grok (xAI), Anthropic, Ollama (local), Groq, OpenRouter, NVIDIA, OpenCode Zen, OpenCode Go
• Tool-calling — file read/write/edit, shell commands, web search/fetch, grep, glob
• Persistent memory — save/recall knowledge across sessions with 4 types: user, feedback, project, reference
• Auto-save — code blocks in AI responses saved to ghostcode_gen/ in cwd
• Security — configurable tool approval (ask/auto/deny) and secret scanning
• Multi-runtime — same code runs on Bun (primary) and Node 22+, shipped as ESM via tsup

In-app commands

| Command | What it does | |---|---| | /help | List commands | | /quit or Ctrl-C | Exit | | /provider <id> | Switch provider | | /model <name> | Switch model | | /api connect <provider> <key> | Save an API key | | /memory | Manage memories | | /plan | Read-only exploration agent | | /deny | Add a deny rule | | /clear | Clear session context |

CLI commands

| Command | What it does | |---|---| | ghostcode | Interactive chat REPL | | ghostcode ask <question> | One-shot question, tool-approved writes | | ghostcode api <list\|connect\|disconnect> | Manage provider API keys | | ghostcode providers | List available providers | | ghostcode model [provider] [model] | Set or list default model | | ghostcode config | Show current configuration | | ghostcode init [--provider --model] | Analyze codebase and write GHOST.md | | ghostcode memory <list\|save\|search\|delete\|summary> | Manage persistent memories | | ghostcode update --check | Check for updates |

Configuration

Runtime state lives in ~/.config/ghostcode/:

• config.json — default provider, saved models, API keys (via conf)
• ghostcode.db — SQLite database for persistent memory

Per-project settings and secrets go in .env (see .env.example).

Architecture

src/
  index.ts          citty CLI — subcommands, env/config boot
  commands/         one file per CLI subcommand
  core/             chat session, prompt building, security, file ops
  ai/               provider registry + per-kind clients (openai-compat/anthropic/ollama)
  tools/            tool definitions + executor (security-gated)
  storage/          config (conf) + SQLite adapter (bun:sqlite / better-sqlite3)
  utils/            logger (consola), env loader, markdown renderer, platform
  agents/           subagent definitions

• UI — consola for logging, @clack/prompts for interactive input
• Build — tsup (ESM for Node) and bun build --compile (single binary)
• Distribution — npm + Homebrew + Scoop manifests in distrib/

Development

bun install
bun run dev          # run from source
bun run typecheck    # tsc --noEmit
bun run build        # tsup → dist/index.js
bun run build:all    # tsup + bun build --compile

License

Apache-2.0