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 gemma4:e2b with no configuration needed. Pull the model once:

ollama pull gemma4          # ~4GB, fast and capable
ollama pull gemma4:31b      # ~20GB, higher quality

Select the Ollama model in Settings → Enable. The agent is now active.

Cloud (Anthropic)

Select a Claude model from the dropdown and paste your Anthropic API key. Supported models:

claude-haiku-4-5-20251001   # fast, low cost
claude-sonnet-4-6           # balanced (recommended)
claude-opus-4-6             # highest capability

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 (Ferricula)

If you configure a Ferricula instance in Settings (Settings → Shivvr/Embeddings URL), the Ghost gains persistent memory backed by semantic and BM25 search.

The agent automatically recalls relevant past context at the start of each session. Facts, tool results, and conversation threads are stored and decay over time according to how often they're recalled — the same memory model as the rest of the Gnosis ecosystem.

# In Settings, set the Shivvr URL:
http://localhost:8765   # local Ferricula instance

Without Ferricula, the Ghost operates as a stateless session agent — no memory persists between HUD opens.

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": {
    "agentModel": "ollama:gemma4:e2b",
    "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.