ralphglasses

Command-and-control TUI for parallel multi-LLM agent fleets.

Engineering context: Solves the problem of managing parallel AI agent sessions across providers without losing cost visibility or prompt quality. Draws on multi-cloud infrastructure patterns — the same fleet management, circuit breaking, and cost enforcement that production platforms need.

Orchestrates Claude Code, Gemini CLI, OpenAI Codex CLI, and experimental Google Antigravity handoffs from a single k9s-style interface. Built with Charmbracelet (BubbleTea + Lip Gloss).

• Orchestrate multiple LLM providers (Claude, Gemini, Codex, Antigravity) with capability-aware session management
• Project provider-neutral fleet roles into native Codex, Claude, and Gemini agent surfaces
• Generate repo-native Antigravity and Gemini workflow surfaces from the canonical Ralph workflow catalog
• Discover ralph-enabled repos across your workspace (--scan-path)
• Monitor live status: loop iteration, circuit breaker state, per-provider costs, model selection
• Control ralph loops, headless sessions, and Codex planner/worker loops from TUI or MCP tools
• Track costs across all providers in a unified cost ledger
• Stream logs in real-time with reactive file watching (fsnotify)
• Configure .ralphrc settings per repo from an in-TUI editor

go install github.com/hairglasses-studio/ralphglasses@latest

Or build from source:

git clone https://github.com/hairglasses-studio/ralphglasses.git
cd ralphglasses

# Bootstrap local tooling if needed
./scripts/bootstrap-toolchain.sh

# Build
./scripts/dev/go.sh build ./...

# Launch TUI
./scripts/dev/go.sh run . --scan-path ~/hairglasses-studio

Repo-local Codex MCP discovery is already wired in via .codex/config.toml and .mcp.json. Other MCP clients can register the same ./scripts/dev/run-mcp.sh --scan-path ~/hairglasses-studio entrypoint manually if needed.

Launch sessions against any supported provider:

Antigravity is launch-only from Ralph. It opens a new Antigravity agent window rooted at the repo and relies on checked-in .agents/rules/, .agents/workflows/, .agents/skills/, .mcp.json, and the generated .gemini/extensions/ralphglasses-workspace/ bundle instead of participating in Ralph's streaming session runtime, teams, loops, or failover.

// Launch a Gemini session
{ "tool": "ralphglasses_session_launch", "arguments": {
    "repo": "my-project", "prompt": "Refactor the API layer", "provider": "gemini"
}}

// Create a multi-provider team (Codex leads, delegates to Gemini/Claude workers)
{ "tool": "ralphglasses_team_create", "arguments": {
    "repo": "my-project", "name": "refactor-team", "provider": "codex",
    "tasks": "Rewrite auth middleware\nAdd integration tests\nUpdate API docs"
}}

// List only Gemini sessions
{ "tool": "ralphglasses_session_list", "arguments": { "provider": "gemini" }}

OPENAI_API_KEY=sk-...           # Codex CLI
GOOGLE_API_KEY=AIza...          # Gemini CLI
ANTHROPIC_API_KEY=sk-ant-...    # Claude Code (optional if using OAuth)

Prompt-enhancement and embedding helpers can optionally use a local Ollama-compatible endpoint:

Local prompt-improver evals can now be regression-tested from the repo root with:

~/hairglasses-studio/dotfiles/scripts/hg-promptfoo.sh . eval -c promptfoo/promptfooconfig.yaml

That promptfoo suite is intentionally fast and deterministic. The provider-specific improvement paths stay covered by the Go tests in internal/enhancer and cmd/prompt-improver.

When you want those prompt-improver evals or CLI runs to emit traces to an OTLP collector or Langfuse, export either the standard OTLP env vars or the Langfuse-native trio before running ralphglasses or go run ./cmd/prompt-improver:

# Generic OTLP/HTTP or OTLP/gRPC
OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318
OTEL_EXPORTER_OTLP_HEADERS=authorization=Bearer demo-token

# Or Langfuse-native OTLP/HTTP derivation
LANGFUSE_HOST=https://cloud.langfuse.com
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...

• .agents/skills/ is canonical for provider-neutral workflows.
• .agents/roles/*.json is canonical for reusable fleet roles.
• .codex/agents/*.toml, .claude/agents/*.md, and .gemini/agents/*.md are native projections of that shared role catalog.
• .agents/workflows/ and .agents/rules/ are the repo-native Antigravity/Gemini command surfaces generated from the live Ralph workflow catalog and repo guidance.
• .gemini/commands/ralph/*.toml is the generated local command mirror for Gemini and Antigravity.
• .gemini/extensions/ralphglasses-workspace/ is a thin generated extension bundle that wraps the repo-local MCP server, commands, and AGENTS.md.
• Gemini parity is native-first: local .gemini/agents/*.md subagents, remote A2A agents, skills, and extensions all participate in the shared fleet model.

Cross-platform Unix TUI that manages multi-session, multi-provider LLM loops from any terminal.

Ubuntu 24.04-based, boots into i3 + ralphglasses TUI. Supports 7-monitor, dual-NVIDIA-GPU setups.

See ROADMAP.md for the full plan.

222 MCP tools for programmatic control across all providers:

main.go → cmd/root.go (Cobra CLI)
├── internal/discovery/    Scan for .ralph/ repos
├── internal/model/        Status, progress, config parsers
├── internal/process/      Process management, file watcher, log tailing
├── internal/session/      Multi-provider LLM session management
│   ├── providers.go       Per-provider cmd builders + event normalizers
│   ├── runner.go          Session lifecycle (launch, stream, terminate)
│   ├── manager.go         Session/team registry
│   ├── budget.go          Per-provider cost tracking + enforcement
│   └── types.go           Provider enum, Session, LaunchOptions, TeamConfig
├── internal/mcpserver/    MCP tool handlers (222 tools: 218 grouped + 4 management, stdio)
├── internal/roadmap/      Roadmap parsing, analysis, research, export
├── internal/repofiles/    Ralph config scaffolding and optimization
├── internal/tui/          BubbleTea app, keymap, commands, filter
│   ├── styles/            Lip Gloss theme (k9s-inspired)
│   ├── components/        Table, breadcrumb, status bar, notifications
│   └── views/             Overview, repo detail, log stream, config editor, help
├── distro/                Thin client build system
│   ├── hardware/          Hardware manifests (PCI IDs, modules)
│   ├── scripts/           Build and detection scripts
│   ├── systemd/           Systemd service units
│   └── pxe/               PXE network boot docs
├── docs/                  Research & reference docs
└── scripts/               Shell helpers (marathon.sh)

• Claude Code: Overview | CLI Reference | SDK
• Anthropic API: API Reference | Tool Use
• Gemini: API Overview | Models | Gemini CLI
• OpenAI: API Reference | Codex CLI | Models

• MCP (Model Context Protocol): Specification | Go SDK (mcp-go)
• Charmbracelet: Bubble Tea | Lip Gloss | Bubbles

• Autobuild Planning: docs/autobuild-patch-queue.json / docs/autobuild-cycle-improvement-notes.md / docs/autobuild-execution-ledger.json
• ROADMAP.md — Full development roadmap
• docs/CODEX-REFERENCE.md — Codex-first runtime notes, pinned docs, Claude cache guardrails
• docs/CODEX-PARITY-STATUS.md — Codex parity closeout state and future-session rules
• docs/PROVIDER-SETUP.md — provider setup plus Antigravity launch-only constraints
• docs/PROVIDER-PARITY-OBJECTIVES.md — provider capability matrix and Antigravity parity boundaries
• docs/CLI-PARITY.md — CLI-to-MCP and skill-backed parity matrix
• docs/RESEARCH.md — Agent OS & sandboxing research
• docs/MULTI-SESSION.md — Multi-session tool comparison
• CLAUDE.md — Claude Code project instructions
• GEMINI.md — Gemini CLI project instructions
• AGENTS.md — Codex CLI project instructions
• CONTRIBUTING.md — Multi-provider contribution guide
• docs/issue-ledger.json — Current repo issue ledger