DeepBlue Dynamics / Docs / Hyperia / Ghost Agent

Ghost Agent

The AI agent built into Hyperia — runs tools, reads screens, types commands.

Overview

The Ghost is Hyperia's built-in AI agent. It opens as a floating HUD over the terminal — you can talk to it, give it tasks, and it uses MCP tools to read your terminal screens, type commands, open web panes, manage files, and more.

The Ghost and the human share the same terminal surface. You can both type into the same tabs at the same time. The agent sees the screen exactly as you do.

Enabling the Ghost

Open Settings from the hamburger menu. The agent requires either a local Ollama instance or an LLM API key.

Local (Ollama) — no key required

With Ollama running locally, Hyperia defaults to gemma2:9b with no configuration needed. Pull the model once:

ollama pull gemma2:9b        # ~5GB, fast and capable (default)
ollama pull llama3.2         # any Ollama tag works too

Any tag your local Ollama has is selectable in Settings — prefix with ollama: in the model picker (e.g. ollama:qwen2.5).

Cloud (Anthropic / OpenAI / Gemini)

Open Settings and paste an API key for any of Anthropic, OpenAI, or Gemini. Pick a model from the picker. Supported today:

# Anthropic
claude-opus-4-8              # highest capability
claude-sonnet-5              # balanced daily driver
claude-haiku-4-5             # fast, low cost

# OpenAI
gpt-5                        # flagship
gpt-5-codex                  # coding-tuned (responses API)
gpt-4.1                      # 1M-context
gpt-4o, gpt-4o-mini, o4-mini

# Gemini
gemini-1.5-pro
gemini-1.5-flash

Keys never leave your machine except to the provider you selected. Everything lives in ~/.hyperia/hyperia.json.

The Ghost HUD

Press the Ghost shortcut (or click the ghost button in the toolbar) to open the HUD. It appears as an overlay panel — you can move it, resize it, and keep it open while working in the terminal below.

👻 SCREENSHOT — Ghost HUD with streaming response

The HUD shows the conversation thread with the agent — your messages, the agent's responses, and tool call results inline. A retro status bar at the bottom tracks input tokens, output tokens, tool calls this turn, and total turns in the current session.

How it works

When you send a message, the Ghost runs an agentic loop:

1. System context injection — the current terminal state (active pane, running process, visible screen) is injected into the system prompt automatically.

2. LLM call — your message plus context goes to the provider (Ollama, Anthropic, etc.) with the full MCP tool schema attached.

3. Tool execution — if the model requests tool calls (read screen, run command, open web pane), the sidecar executes them and returns results.

4. Loop — results feed back into the next turn. The agent continues until it reaches a stopping point or the max-turns limit (default: 25).

The Ghost's first tool call is always terminal_status to survey what panes exist and what's running. It won't type into a pane it hasn't read first.

What the Ghost can do

The Ghost has access to the full MCP tool set. Common tasks:

Task	Tools used
Run a shell command and read output	terminal_run
Type into an interactive session (vim, REPL)	terminal_keys
Read the current screen of any pane	terminal_screen
Open a web pane to a URL	open_web_pane
Create a sticky note	sticky_note_create
Split a pane or open a new tab	terminal_split, terminal_new_tab

Memory (lume & Ferricula)

Hyperia ships with lume, a built-in local BM25 index over your shell history and sticky notes. It runs in-process, needs no configuration, and stores its state under ~/.hyperia/lume/. The Ghost queries it every turn to recall commands you've run, notes you've written, and past agent conversations from the same workspace.

If you want richer semantic recall across sessions, point Hyperia at an external Ferricula instance in Settings — the Ghost then uses it in addition to lume for embedding-based similarity search. Ferricula is entirely optional; without it, lume alone covers day-to-day recall.

# Settings → Memory → Ferricula URL (optional)
http://localhost:8765

Delete ~/.hyperia/lume/ at any time to wipe local memory — you'll only lose search history, not app state.

Agent status indicators

Each tab in the tab bar shows a small colored dot when an agent is associated with that session:

Color	Meaning
Green	Agent connected, idle
Amber	Agent connected, human input mode active
Red (pulsing)	Agent actively working — tool calls in progress

Limits and safety

The Ghost runs for a maximum of 25 turns per invocation by default. This prevents runaway loops on ambiguous tasks. The limit is configurable in hyperia.json:

{
  "config": {
    "agent": { "provider": "ollama", "model": "gemma2:9b" },
    "agentMaxTurns": 40
  }
}

For destructive operations (file deletion, rm -rf, process kills), the Ghost is instructed to ask for confirmation before proceeding. You can interrupt any running agent turn by pressing Escape in the HUD.