ghostcode-ai
v1.0.0
Published
Terminal AI coding assistant — chat with LLMs, generate and save code, all from your terminal
Maintainers
Readme
GhostCode
Terminal AI coding assistant with built-in TUI. Chat with multiple AI providers, auto-save code blocks, manage persistent memory, and delegate tasks to subagents.
npm i -g ghostcode-ai
ghostcodeQuick start
npm i -g ghostcode-ai
ghostcodeInside the app, connect an API key:
/api connect groq gsk-<your-key>Get a free key at console.groq.com. Keys are stored in ~/.ghostcode/config.json.
Features
- Hybrid architecture — Node.js CLI (
cli.js) spawns a Python Textual TUI - 8 AI providers — Groq, OpenAI, Anthropic, Ollama, OpenRouter, NVIDIA, and 2 coming-soon
- 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
- Subagent tasks — spawn async subagents for parallel work
- Auto-save — code blocks in AI responses saved to
ghostcode_gen/in cwd - Plan mode — read-only exploration agent for research before implementation
- Security — configurable deny rules and secret scanning
- Hooks — before/after tool hooks and stop hooks via shell commands
In-app commands
| Command | What it does |
|---|---|
| /api | Show provider list with status |
| /api connect <provider> <key> | Set API key directly |
| /api disconnect <provider> | Remove provider's key |
| /model <name> | Switch model for active provider |
| /provider <name> | Switch active provider |
| /clear | Clear chat history |
| /help | Show this help |
| /memory | Manage persistent memory (save/list/delete) |
| /tasks | List and manage subagent tasks |
| /deny | Configure deny rules |
| /hooks | Configure tool hooks |
| /plan | Enter read-only plan mode |
| /review | Review recent work |
| /summary | Show session summary |
| /init | Initialize project config |
| /ask | Ask a question |
| /brief | Get a brief on current state |
| Tab | Switch between code agent and plan agent |
Providers
| Provider | Status | |---|---| | Groq | ✅ | | OpenAI | ✅ | | Anthropic | ✅ | | Ollama | ✅ | | OpenRouter | ✅ | | NVIDIA | ✅ |
API keys stored at ~/.ghostcode/config.json. Environment variables loaded from .env, ~/.ghostcode/.env, and src/.env.
Architecture
This project is a hybrid Node.js/Python application:
- CLI entrypoint —
cli.jsspawnspython -m ghostcodefrom a local.venv - Python package —
src/ghostcode/(setuptools, pyproject.toml) - Agent prompts — system prompts in
src/ghostcode/agents/(code.pyfor full tool access,explore.pyfor read-only) - Tools — 16 tool definitions in
src/ghostcode/tools/defs.py, execution inexecutor.py - Version — single source of truth in
package.json, read at runtime by_version.py
See AGENTS.md for a detailed developer guide.
Requirements
- Node.js >=16, npm >=8
- Python >=3.8
- Dependencies:
textual>=8.0.0,httpx>=0.28.0,python-dotenv>=1.0.0,pygments>=2.15.0
License
Apache 2.0 — see LICENSE.
