Ghost in Shell documentation
Everything you need to install, configure and get the most out of Ghost in Shell Terminal, version 0.2.2.
Install
- Download the .dmg for your chip. Apple menu, About This Mac: "Chip: Apple M…" is Apple Silicon (arm64), "Processor: Intel…" is Intel (x64).
- Open the .dmg and drag Ghost in Shell Terminal into Applications.
- Eject the disk image and launch from Applications.
"Ghost in Shell Terminal can't be opened"
The beta is not notarized, so macOS blocks the first launch. Either right-click the app in Applications and choose Open, then confirm, or run once:
xattr -dr com.apple.quarantine "/Applications/Ghost in Shell Terminal.app"Updating
Quit the app, open the new .dmg, drag to Applications and choose Replace (not Keep Both). Eject old disk images afterwards; an app inside a mounted image keeps showing up in Spotlight.
Models and keys
Open Settings. Providers are listed side by side:
- OpenAI: GPT-5.5, GPT-5.4, GPT-5.4 mini, GPT-5.4 nano, GPT-5 mini, GPT-5 nano. Paste an API key.
- Claude: Opus, Sonnet, Haiku. Paste an Anthropic API key.
- Local: models from Ollama, browsed, installed and run from inside Settings. Free and private. See the Ollama guide.
- Custom: any model id the provider accepts.
Keys are stored on this Mac only. Recent models are kept for quick switching.
Keyboard shortcuts
| Keys | Action |
|---|---|
| Cmd K | Describe a command in plain English; it streams into your prompt |
| Cmd E | Files panel: git-aware tree, search, editor. Dock left, right or bottom, or pop out |
| Cmd J | Agents panel: every AI coding agent across all windows |
| Cmd T | New tab |
| Cmd N | New window |
| Cmd S | Save in the editor |
| Cmd + / - | Font size of the pane you are in, terminal or files panel |
| Drag a tab | Reorder, tear off into a window, or drop onto another window |
| Drag a file from Finder | Its path is typed at the prompt |
Asking at the prompt
- A runnable line goes to the shell untouched.
- A question is answered inline under
ghost >. - A task comes back as a staged command; press Enter to run or edit first.
- A leading space forces the shell. A leading
?forces the AI. - The assistant stays out of tabs where an agent (claude, codex, gemini, aider, goose, copilot) is running, and never takes over while a full-screen app is on screen.
Each AI behavior can be switched off in Settings, and its system prompt opened, edited, given house rules or reset.
Agents panel
States are needs you (blocked on a permission prompt or question), working, finished and inactive. Blocked agents jump to the top and the panel raises itself. Click a row to jump to that tab. When idle the panel collapses to a rail of state orbs with hover cards; a toolbar button and an unpin switch control whether it stays in front. Full walkthrough: running multiple Claude Code sessions.
Files panel
A directory tree with live git status and the current branch, a search box with Folders / Files / In files scope, and a syntax-highlighted editor with line numbers and five code themes. A "Follow terminal" switch keeps it on the shell's current directory. Each tab keeps its own view.
Color profiles
Ghost (phosphor green on black with CRT scanlines), Homebrew, Basic, Pro, Novel, Ocean, Man Page, Grass, Red Sands and Solid Colors. The titlebar and the agents panel take the colors of the active profile.
Privacy
Local-first. Nothing leaves your Mac until you ask a question, and then only your directory, recent commands and a slice of output travel with it, to the provider you chose. With a local Ollama model nothing leaves at all. There is no account, no telemetry service to sign into, and keys live on this Mac.
Requirements
macOS 13 or later, Apple Silicon or Intel. Built with Electron, React, xterm.js and node-pty.
Support and contributing
Questions: contact@ghostinshell.co. To contribute, write to contributor@ghostinshell.co; contributors are named in the co-builder list and get early access to new features.
Frequently asked questions
Why does macOS say the app can't be opened?
The beta is unsigned. Right-click the app and choose Open, or remove the quarantine flag with xattr as shown above. It is only needed once.
Where are my API keys stored?
On this Mac only, in the app's local settings. They are sent directly to the provider you chose when you ask a question.
Can I change the AI's system prompt?
Yes. Each behavior's prompt is visible in Settings and can be edited, given house rules or reset to the default.