Hyperia™

A terminal emulator built for agents and humans.

Hyperia is an agent-native terminal emulator. Forked from Hyper and extended with a Rust sidecar, it turns the terminal into a first-class platform for AI orchestration. Agents connect over the Model Context Protocol (MCP) and operate terminal sessions as peers — opening tabs, splitting panes, running commands, reading screens, and reporting status — while the human stays in control at all times.

Built by Deep Blue Dynamics.

---

Highlights

• Agent-native MCP server — 56 tools exposed over streamable HTTP. Any MCP-capable client (Claude Code, OpenAI Codex, Google Antigravity, and others) can drive the terminal: open tabs, split panes, run commands, read screens, manage sticky notes, and inspect telemetry.
• Ghost agent — A built-in assistant with streaming chat, tool use, and persistent memory. It is aware of what is open, what is running, and what it has done before.
• Local memory & search — A built-in BM25 index over your shell history and sticky notes, so an agent can search what you actually ran and wrote — not just the visible screen. An optional external memory service (Ferricula) can be attached for cross-session recall.
• Agent status lights — An agent can flag its tab as connected, working, or idle (via the agent_status tool), so you can see at a glance which tabs it's driving. It's a signal the agent raises, not auto-detection.
• Stickys™ — Floating, named, color-coded notes that persist across restarts and are fully controllable from any agent.
• Shell profiles — PowerShell, CMD, WSL, Git Bash, or any custom shell, surfaced in the new-pane chooser.
• Sidecar architecture — A dedicated Rust process (hyperia-sidecar) provides the HTTP, WebSocket, and MCP surfaces, decoupled from Electron for speed and reliability.
• Telemetry dashboard — Per-pane metrics at http://localhost:9800/dashboard.

---

Quick start

git clone https://github.com/DeepBlueDynamics/hyperia.git
cd hyperia
yarn install

cd sidecar && cargo build && cd ..

yarn start

See docs/getting-started.md for prerequisites and full build instructions. Prebuilt, signed installers for Windows and macOS are available on the Releases page.

---

Connect an agent (MCP over HTTP)

While Hyperia is running, the sidecar exposes its MCP server over streamable HTTP:

http://localhost:9800/mcp

No API key or local binary path is required — point any MCP client at that URL. (The port is 9800 by default; override it with HYPERIA_PORT.) The examples below assume Hyperia is running on the same machine as the client.

Claude Code

Register the server with the CLI:

claude mcp add --transport http hyperia http://localhost:9800/mcp

Add --scope user to make it available across all projects. To configure it per-project instead, commit a .mcp.json at the repository root:

{
  "mcpServers": {
    "hyperia": {
      "type": "http",
      "url": "http://localhost:9800/mcp"
    }
  }
}

Verify with claude mcp list or /mcp inside a session.

OpenAI Codex

Add the server to ~/.codex/config.toml:

[mcp_servers.hyperia]
url = "http://localhost:9800/mcp"

Codex discovers the tools on its next launch. Confirm with codex mcp list.

Google Antigravity

Open the MCP settings (Settings → MCP → Add Server), or edit Antigravity's MCP configuration file directly:

{
  "mcpServers": {
    "hyperia": {
      "serverUrl": "http://localhost:9800/mcp"
    }
  }
}

Reload the MCP servers from the settings panel; Hyperia's tools then appear in the agent's tool list.

Other clients

Any client that supports the MCP streamable-HTTP transport works the same way — register the URL http://localhost:9800/mcp. The full tool catalog is documented in docs/mcp-tools.md.

---

Documentation

Document	Description
Getting Started	Install, build, and first launch
MCP Tools	Complete tool reference
Ghost Agent	Built-in assistant — models, memory, behavior
Configuration	Config file reference and keyboard shortcuts
Memory & Search	Local search (lume) + optional external recall (Ferricula)
Architecture	Codebase structure and component overview
Building	Release builds — Windows (Azure Trusted Signing) and macOS
Apple Signing	macOS code signing and notarization

---

Architecture

Electron (UI + PTY sessions)
    │
    │── WebSocket bridge ──▶ hyperia-sidecar (Rust, :9800)
                                  │
                                  ├── HTTP API (terminal, agent, notes, telemetry)
                                  ├── MCP server (streamable HTTP at /mcp, 56 tools)
                                  ├── Ghost agent (streaming, tool loop)
                                  ├── lume — local BM25 over shell logs + notes
                                  │     └── ~/.hyperia/lume/
                                  ├── Ferricula client (optional external memory service)
                                  └── Telemetry + dashboard

---

License

MIT — see LICENSE.

Based on Hyper by Vercel.