warpforge CLAUDE.md

Project: Warpforge

Workspace orchestrator with TUI and desktop interfaces. Manages multiple dev projects: isolated services with auto-resolved ports, embedded agent terminals (Codex, Claude), instant context switching.

Architecture

Core (Rust):

• Language: Rust
• Async runtime: Tokio
• Daemon: Background process that manages services, agents, and project state
• PTY: portable-pty — real TTY for spawned agents
• Terminal emulation: vt100 crate — parses ANSI into screen buffer
• CLI: clap derive API
• Config: .warpforge/workspace.yaml per project (serde_yaml; legacy root-level .warpforge.yaml / .wf.yaml / .workspace.yaml still load), registry in ~/.warpforge/projects.json
• Port isolation: each project gets 100-port range (4000+), ${svc.port} interpolation in env vars
• Daemon IPC: WebSocket JSON-RPC (port 61814)

TUI (Rust):

• Framework: Ratatui + Crossterm
• Binary: cargo build --release → target/release/warpforge
• Key crates: ratatui 0.29, crossterm 0.28 (event-stream), vt100 0.15

Desktop (TypeScript + Tauri):

• Framework: Tauri v2 (Rust shell + WebView)
• Frontend: React 18 + TypeScript + Vite
• UI: Tailwind CSS + Radix UI primitives + shadcn/ui components
• State: Zustand (persisted to localStorage)
• Terminal: CodeMirror for editor (interactive terminal not yet implemented)
• Package manager: Bun
• Linting: oxlint + oxfmt
• Tests: Vitest + React Testing Library

Key crates (Rust): tokio, clap 4, serde, anyhow, portable-pty 0.8, vt100 0.15, ratatui 0.29, crossterm 0.28

Source layout (src/)

main.rs          — CLI entry (clap), subcommands: add, remove, list, ui
app.rs           — TUI event loop (tokio::select), AppState, InputMode (Navigate/Terminal), key handling
agent.rs         — AgentManager: PTY spawn via portable-pty, vt100 parser, input/output channels
service.rs       — ServiceManager: sh -c spawn, stdout/stderr log capture, process-group kill, port allocation
config.rs        — workspace config parsing + auto-detect (package.json scripts, docker-compose)
workflow_config.rs — .warpforge/workflows/*.yaml templates: schema, validation, prompt rendering
registry.rs      — ~/.warpforge/projects.json CRUD
ports.rs         — Port range allocation (4000+), ${svc.port} env interpolation
tui/
  mod.rs         — render dispatch (Dashboard vs Project screen)
  dashboard.rs   — Project list with service/agent status, j/k nav, Enter to open
  project.rs     — Split layout: sidebar (services + agents) + right pane (terminal or logs)
  terminal.rs    — TerminalPane widget: vt100 Screen → ratatui Buffer (cell-by-cell, colors, cursor)