GHOST — your AI coding buddy in the terminal

GHOST is a friendly AI assistant that lives in your terminal. You talk to it in plain English, and it helps you understand, search, and improve the code in your current project. Think of it as a pair-programmer you can chat with while you work.

No need to be a power user. If you can type a question, you can use GHOST.

What can it do?

• Answer questions about your code — "What does this project do?", "Where is the login logic?".
• Read, search, and summarize files in the folder you're working in.
• Run safe shell commands and git checks for you, after asking for permission when something looks risky.
• Write and edit files when you ask it to — and it shows you what it plans to do first.
• Switch between AI providers (OpenAI, OpenRouter, Google Gemini, Anthropic, or a local Ollama install) — you pick what works for you.
• Remember your preferences across a session so follow-up questions feel natural.

GHOST only works inside the folder you open it in, so it won't go poking around the rest of your computer unless you specifically allow it.

Install

You need Node.js 18 or newer installed first.

npm install -g ghost-ai-cli

That gives you a ghost command you can run anywhere.

Developing locally instead? Clone the repo, run npm install, then npm link so the ghost command points at your copy.

Quick start

1. Open a terminal in any project folder:

   cd my-project

2. Start GHOST:

   ghost

3. Type a task, for example:

   You ❯ explain what this project is for

4. Keep chatting. When you're done, type /exit (or press Ctrl+C).

That's it — no complicated setup required to start talking to it.

Connecting an AI provider

GHOST needs an AI backend to do the thinking. You can use a cloud service (OpenAI, OpenRouter, Google Gemini, or Anthropic) with an API key, or run Ollama on your own machine for free with no key.

Pick a provider

ghost provider

This shows the providers GHOST supports. To choose one and save its key:

ghost provider set openai

GHOST will ask for your API key. Your key is stored only on your computer and is never printed back to the screen or sent anywhere except to the provider you chose. If you ever need to change it:

ghost provider key openai

Choose a model

ghost model set gpt-4o

(Use a model name your provider supports. With Ollama, GHOST can list the models you already have installed.)

Check everything is healthy

ghost doctor

This runs a few quick checks (Node version, provider, key, model) and tells you if anything needs fixing.

Not sure which provider to use? ghost provider set ollama is the easiest start if you have Ollama installed locally — no sign-up, no key.

Everyday commands

| Command | What it does | | --- | --- | | ghost | Start an interactive chat session. | | ghost chat | Same as ghost — open the chat. | | ghost run "do something" | Run a single task and show the result. | | ghost provider | List providers and manage your selection/key. | | ghost model | Show or change the active model. | | ghost config | View your current settings. | | ghost doctor | Diagnose setup and connection problems. | | ghost theme | Change the color theme. | | ghost share | Export your last task as a shareable card. | | ghost completion | Print shell completion setup for bash/zsh. |

Inside a chat, these shorthand commands are handy:

• /help — list chat commands
• /clear — clear the screen
• /model — show the current model
• /provider — show the current provider
• /theme — change the color theme
• /share — export the last task
• /exit or /quit — leave the chat

Safety: you stay in control

GHOST is built to ask before it does anything risky. Before deleting files, overwriting something, or running a command that could affect your system, it will show you what it wants to do and wait for a yes/no.

• Type y to allow, anything else to skip.
• Prefer hands-off? Run with autonomous mode for routine work, but understand that protected operations still prompt you.
• Want a dry run? Use ghost plan "..." to have GHOST outline a plan without making changes.

Your keys and settings live only on your machine. GHOST never prints your API key in normal output.

Tips for beginners

• Be specific. "Add a function that formats a date as YYYY-MM-DD" works better than "fix the code".
• Stay in the project folder. GHOST focuses on the directory you launched it from.
• Iterate. If the first answer isn't right, just say "now also handle the case where the input is empty" — it remembers the conversation.
• Use ghost doctor whenever something feels off; it usually points straight at the fix.
• Stuck? Type /help inside a chat for the available shortcuts.

Uninstall

npm uninstall -g ghost-ai-cli

License

MIT — free to use, modify, and share.