ralphglasses

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

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

• Orchestrate multiple LLM providers (Claude, Gemini, Codex) with unified session management
• Project provider-neutral fleet roles into native Codex, Claude, and Gemini agent surfaces
• 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:

// 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)

• .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.
• .gemini/commands/ remains a compatibility shortcut surface, not the canonical reusable-role source.
• 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

• 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/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