MetaTerm

An AR-style overlay that explains what your terminals are doing.

MetaTerm is a transparent, click-through window that floats above your real terminal windows. For each one, it pins a small floating badge that tells you — in natural language — what that session is actually doing right now. It's not a dashboard. It's not a terminal. It's a lens.

The interpretation comes from Claude. Specifically, MetaTerm shells out to claude -p programmatically to turn raw process and output state into a single sentence like "Vite rebuilding · 2 warnings" or "Claude Code editing files" or "idle · last build ok".

 ┌─ Ghostty: frontend ──────────────────────────┐
 │  frontend  Vite rebuilding · 2 warnings ●    │
 │                                              │
 │  $ pnpm dev                                  │
 │  ...                                         │
 └──────────────────────────────────────────────┘

 ┌─ Ghostty: api ───────────────────────────────┐
 │  api  Jest · 3 tests failing ●               │
 │                                              │
 │  $ pnpm test --watch                         │
 │  ...                                         │
 └──────────────────────────────────────────────┘

What it is

• A single fullscreen transparent overlay window (Tauri + macOS CoreGraphics). Mouse events fall through — it never steals focus.
• A process/session model built from ps, tty foreground resolution, Ghostty window enumeration, and an optional zsh hook that streams command-lifecycle events into a local socket.
• A Claude-powered interpreter that, every few seconds, takes the current command + recent output + cwd of each session and returns a structured JSON verdict: oneLiner, status, confidence, detail.
• A local HTTP API on 127.0.0.1:7878 that the overlay (and any other harness) polls for the latest interpretations.

How the AI layer works

MetaTerm never has its own LLM client. It invokes your existing claude CLI the same way you would:

claude -p --model haiku --output-format json \
  --no-session-persistence --tools "" \
  --setting-sources "" \
  --append-system-prompt "<metaterm interpreter prompt>" \
  <<< "<session snapshot>"

On every interpretation tick it:

1. Snapshots each session — current foreground command, up to 4 KiB of ANSI-stripped recent output, cwd, elapsed ms, last exit code.
2. Hashes the snapshot. If the hash matches the last one we interpreted for that session, reuse the cached answer (no new call).
3. Rate-limits per session (≥ 4s between calls) and caps total concurrency (default 2 parallel claude -p children) so a laptop with a dozen terminals doesn't blow up token usage.
4. Pipes the snapshot to claude -p and parses the JSON envelope's result field into an Interpretation.

If ANTHROPIC_API_KEY is set, MetaTerm adds --bare + CLAUDE_CODE_SIMPLE=1 for a minimal context window and lower per-call cost. Otherwise it uses the OAuth-authenticated claude you already use for interactive work.

Typical haiku call: ~$0.002, ~3-5s latency.

What the overlay shows

Each badge has:

• A status-coloured rail and pulsing dot:
  • green = running, amber = stuck, red = failing, blue = waiting, grey = idle, neutral = unknown.
• A project chip (leaf of repo root or cwd).
• A one-liner (the AI verdict, ≤ 60 chars).
• Thinking dots while Claude is interpreting.
• An optional detail line (≤ 140 chars) when confidence ≥ 0.5.

Windows are paired to sessions by matching the Ghostty window title to the session's project name / cwd leaf. Unmatched windows get assigned round-robin from any leftover sessions.

Quick start

pnpm install

# Optional but recommended — gives the interpreter richer signal about
# command lifecycles (exit codes, durations).
pnpm install:zsh
pnpm ingest &

# Start the interpreter / API server.
pnpm dev:api

# Start the AR overlay (Tauri).
pnpm dev:desktop

Open a fresh Ghostty window after installing the zsh hook. MetaTerm picks up new sessions automatically.

Env

Variable	Meaning
METATERM_API_PORT	Port for the local API (default 7878)
METATERM_MODEL	Claude alias for interpretation (haiku, sonnet; default haiku)
METATERM_DEBUG	When set, attach raw Claude responses to each interpretation
ANTHROPIC_API_KEY	If set, MetaTerm runs claude -p in --bare mode for cheaper/faster calls

API

Loopback, unauthenticated. The desktop overlay is one of potentially many clients.

Method	Returns
GET /sessions	All tracked sessions + latest interpretation per session
GET /sessions/:id	Deep view for one session, including recent commands
POST /sessions/:id/interpret	Force a fresh interpretation now
POST /buffer {sessionId, chunk}	Append raw terminal output to a session's ring buffer

Privacy / cost

• All session data, output buffers, and interpretations stay on your machine. MetaTerm writes nothing to disk.
• The only outbound traffic is whatever claude -p itself makes (to Anthropic's API). MetaTerm doesn't add its own telemetry.
• Output buffers are ANSI-stripped and capped to 4 KiB per call before being handed to Claude. The system prompt explicitly tells the model to drop anything that looks like a secret, token, or home-dir path.
• Expect roughly $0.002 × (sessions × changes-per-minute) at default settings. A quiet mostly-idle laptop lands in the low cents per hour.

Status

macOS-only MVP (Ghostty + CoreGraphics window enumeration). Linux/Windows paths exist in the code but are inert. See architecture.md and docs/implementation-plan.md for the roadmap.

Non-goals

• replacing tmux
• becoming a shell
• exporting metrics / logs
• cloud-first team product

License

MIT.