README
¶
👻 A lightning-fast, beautiful AI assistant that lives in your terminal — powered by free models.
Hey there! 👋 Welcome to Ghost — a terminal-based AI assistant built to be fast, beautiful, and free.
Ghost ships pre-configured with generous free AI providers, so you can get world-class answers, code suggestions, and command help without entering a credit card. If you live in the terminal and want instant help without alt-tabbing to a browser, Ghost is for you.
Note on UI: Ghost's interface is built on the foundation of Crush by Charm. Huge thanks to the Charm team for the gorgeous terminal toolkit.
✨ Why Ghost?
- Free out of the box. Pre-wired to free providers — no subscription, no API key required to get started.
- Cross-platform. A single native Go binary for Linux, macOS, and Windows (amd64 + arm64).
- Beautiful TUI. A responsive, themeable terminal interface (Dracula theme included).
- Bring your own keys. Optionally connect paid/keyed providers like Google Gemini, Groq, Cerebras, GitHub Copilot, and OpenRouter through the built-in Catwalk registry.
🧠 Models out of the box
These providers work with no API key required:
| Provider | Models | Notes |
|---|---|---|
| OpenCode Zen | Big Pickle, DeepSeek V4 Flash Free, Xiaomi MiMo V2.5 Free, Qwen 3.6 Plus Free, Nemotron 3 Super Free |
Free tier, no key needed |
| OI VSCode Server | MiniMax M2.7 (thinking) |
Free, no key needed |
Add a key to unlock more:
| Provider | How to enable | Example models |
|---|---|---|
| Nvidia NIM | set NVIDIA_API_KEY |
Nemotron 3 Ultra, DeepSeek V4 Pro/Flash, GLM 5.1, Kimi K2.6, Qwen 3.5, Mistral Medium 3.5, Step 3.7 Flash, MiniMax M2.7, DiffusionGemma |
| Google Gemini / Groq / Cerebras / Copilot / OpenRouter | ghost login (via Catwalk registry) |
provider-specific |
Model availability is curated by each provider and may change over time.
🚀 Getting Started
The fast way (macOS & Linux)
Detects your OS/architecture and installs the latest release to /usr/local/bin:
curl -fsSL https://raw.githubusercontent.com/swadhinbiswas/Ghost/main/install.sh | bash
Manual download (Windows, macOS, Linux)
- Go to the Releases page.
- Download the archive for your system (
.tar.gzfor macOS/Linux,.zipfor Windows). - Extract it and move the
ghostbinary somewhere on yourPATH.
Build from source
Requires Go 1.26 or newer:
git clone https://github.com/swadhinbiswas/Ghost.git
cd Ghost
go build -o ghost ./main.go
sudo mv ghost /usr/local/bin/
💻 Usage
Start an interactive chat session:
ghost
Run a one-off prompt without entering the full UI:
ghost run "Write a python script to parse a CSV file"
Other handy commands:
ghost free # pick a free model to chat with
ghost models # list available models
ghost login # add credentials for keyed providers
ghost theme # switch the TUI theme
ghost update-providers # refresh the provider registry
ghost session # manage saved sessions
ghost --help # see everything Ghost can do
🛠️ Configuration
Ghost reads JSON config from standard locations ($XDG_CONFIG_HOME/ghost/ghost.json or ~/.config/ghost/ghost.json). A few useful environment variables:
| Variable | Purpose |
|---|---|
GHOST_DISABLE_PROVIDER_AUTO_UPDATE |
Disable automatic provider/model refresh |
GHOST_DISABLE_DEFAULT_PROVIDERS |
Skip all built-in providers (BYO only) |
NVIDIA_API_KEY |
Enable the Nvidia NIM provider |
GHOST_NVIDIA_NIM_MODELS_URL |
Override the remote Nvidia NIM model catalog URL |
GHOST_OPENCODE_MODELS_URL |
Override the OpenCode Zen models endpoint |
On startup, Ghost refreshes the OpenCode Zen and Nvidia NIM model lists in the background (non-blocking) and caches them for the next session. This honors GHOST_DISABLE_PROVIDER_AUTO_UPDATE. The Nvidia NIM catalog is sourced from nvidia_nim_models.json at the repo root and fetched from its GitHub raw URL, so the model list can be updated without a new release. Run ghost update-providers to refresh on demand.
🙏 Acknowledgments
- UI foundation: Crush and the Charm ecosystem (
lipgloss,bubbletea,catwalk). - Free providers: OpenCode Zen, the OI VSCode community, Nvidia, and everyone democratizing access to great AI models.
📄 License
Ghost is open-source software licensed under the MIT License. Fork it, mod it, make it your own.
Documentation
¶
There is no documentation for this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
agent
Package agent is the core orchestration layer for Ghost AI agents.
|
Package agent is the core orchestration layer for Ghost AI agents. |
|
agent/tools
Package tools provides the semantic_search agent tool.
|
Package tools provides the semantic_search agent tool. |
|
agent/tools/mcp
Package mcp provides functionality for managing Model Context Protocol (MCP) clients within the Ghost application.
|
Package mcp provides functionality for managing Model Context Protocol (MCP) clients within the Ghost application. |
|
cmd
Package cmd: ghost free - list and activate free models.
|
Package cmd: ghost free - list and activate free models. |
|
config/providers
cerebras.go: Cerebras Inference provider (free dev tier, ultra-fast).
|
cerebras.go: Cerebras Inference provider (free dev tier, ultra-fast). |
|
csync
Package csync provides concurrent data structures for safe access in multi-threaded environments.
|
Package csync provides concurrent data structures for safe access in multi-threaded environments. |
|
embedder
Package embedder provides text embedding for semantic search.
|
Package embedder provides text embedding for semantic search. |
|
filetracker
Package filetracker provides functionality to track file reads in sessions.
|
Package filetracker provides functionality to track file reads in sessions. |
|
filewatcher
Package filewatcher provides file system watching for external changes.
|
Package filewatcher provides file system watching for external changes. |
|
home
Package home provides utilities for dealing with the user's home directory.
|
Package home provides utilities for dealing with the user's home directory. |
|
lsp
Package lsp provides a manager for Language Server Protocol (LSP) clients.
|
Package lsp provides a manager for Language Server Protocol (LSP) clients. |
|
network
Package network centralizes Ghost's network-egress policy.
|
Package network centralizes Ghost's network-egress policy. |
|
oauth/copilot
Package copilot provides GitHub Copilot integration.
|
Package copilot provides GitHub Copilot integration. |
|
oauth/hyper
Package hyper provides functions to handle Hyper device flow authentication.
|
Package hyper provides functions to handle Hyper device flow authentication. |
|
semantic
Package semantic provides semantic codebase search using TF-IDF embeddings.
|
Package semantic provides semantic codebase search using TF-IDF embeddings. |
|
shell
Package shell provides cross-platform shell execution capabilities.
|
Package shell provides cross-platform shell execution capabilities. |
|
skills
Package skills implements the Agent Skills open standard.
|
Package skills implements the Agent Skills open standard. |
|
ui/anim
Package anim provides an animated spinner.
|
Package anim provides an animated spinner. |
|
ui/notification
Package notification provides desktop notification support for the UI.
|
Package notification provides desktop notification support for the UI. |
|
ui/util
Package util provides utility functions for UI message handling.
|
Package util provides utility functions for UI message handling. |