[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-74873":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":8,"language":10,"languages":8,"totalLinesOfCode":8,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":16,"stars7d":17,"stars30d":18,"stars90d":15,"forks30d":15,"starsTrendScore":19,"compositeScore":20,"rankGlobal":8,"rankLanguage":8,"license":21,"archived":22,"fork":22,"defaultBranch":23,"hasWiki":24,"hasPages":22,"topics":25,"createdAt":8,"pushedAt":8,"updatedAt":26,"readmeContent":27,"aiSummary":28,"trendingCount":15,"starSnapshotCount":15,"syncStatus":29,"lastSyncTime":30,"discoverSource":31},74873,"ralph-tui","subsy\u002Fralph-tui","subsy",null,"https:\u002F\u002Fralph-tui.com","TypeScript",2358,234,14,32,0,4,10,58,12,29.11,"MIT License",false,"main",true,[],"2026-06-12 02:03:29","# Ralph TUI\n\n[![npm version](https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fv\u002Fralph-tui.svg)](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002Fralph-tui)\n[![CI](https:\u002F\u002Fgithub.com\u002Fsubsy\u002Fralph-tui\u002Factions\u002Fworkflows\u002Fci.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002Fsubsy\u002Fralph-tui\u002Factions\u002Fworkflows\u002Fci.yml)\n[![codecov](https:\u002F\u002Fcodecov.io\u002Fgh\u002Fsubsy\u002Fralph-tui\u002Fgraph\u002Fbadge.svg)](https:\u002F\u002Fcodecov.io\u002Fgh\u002Fsubsy\u002Fralph-tui)\n[![License: MIT](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-blue.svg)](https:\u002F\u002Fopensource.org\u002Flicenses\u002FMIT)\n[![Built with Bun](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FBuilt%20with-Bun-f9f1e1.svg)](https:\u002F\u002Fbun.sh)\n\n**AI Agent Loop Orchestrator** - A terminal UI for orchestrating AI coding agents to work through task lists autonomously.\n\nRalph TUI connects your AI coding assistant (Claude Code, OpenCode, Factory Droid, Cursor CLI, Gemini CLI, Codex, Kiro CLI) to your task tracker and runs them in an autonomous loop, completing tasks one-by-one with intelligent selection, error handling, and full visibility.\n\n![Ralph TUI Screenshot](docs\u002Fimages\u002Fralph-tui.png)\n\n## Quick Start\n\n```bash\n# Install\nbun install -g ralph-tui\n\n# Setup your project\ncd your-project\nralph-tui setup\n\n# Create a PRD with AI assistance\nralph-tui create-prd --chat\n\n# Run Ralph!\nralph-tui run --prd .\u002Fprd.json\n```\n\nThat's it! Ralph will work through your tasks autonomously.\n\n## Documentation\n\n**[ralph-tui.com](https:\u002F\u002Fralph-tui.com)** - Full documentation, guides, and examples.\n\n### Quick Links\n\n- **[Quick Start Guide](https:\u002F\u002Fralph-tui.com\u002Fdocs\u002Fgetting-started\u002Fquick-start)** - Get running in 2 minutes\n- **[Installation](https:\u002F\u002Fralph-tui.com\u002Fdocs\u002Fgetting-started\u002Finstallation)** - All installation options\n- **[CLI Reference](https:\u002F\u002Fralph-tui.com\u002Fdocs\u002Fcli\u002Foverview)** - Complete command reference\n- **[Configuration](https:\u002F\u002Fralph-tui.com\u002Fdocs\u002Fconfiguration\u002Foverview)** - Customize Ralph for your workflow\n- **[Troubleshooting](https:\u002F\u002Fralph-tui.com\u002Fdocs\u002Ftroubleshooting\u002Fcommon-issues)** - Common issues and solutions\n\n## How It Works\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│                                                                 │\n│   ┌──────────────┐     ┌──────────────┐     ┌──────────────┐   │\n│   │  1. SELECT   │────▶│  2. BUILD    │────▶│  3. EXECUTE  │   │\n│   │    TASK      │     │    PROMPT    │     │    AGENT     │   │\n│   └──────────────┘     └──────────────┘     └──────────────┘   │\n│          ▲                                         │            │\n│          │                                         ▼            │\n│   ┌──────────────┐                         ┌──────────────┐    │\n│   │  5. NEXT     │◀────────────────────────│  4. DETECT   │    │\n│   │    TASK      │                         │  COMPLETION  │    │\n│   └──────────────┘                         └──────────────┘    │\n│                                                                 │\n└─────────────────────────────────────────────────────────────────┘\n```\n\nRalph selects the highest-priority task, builds a prompt, executes your AI agent, detects completion, and repeats until all tasks are done.\n\n## Features\n\n- **Task Trackers**: prd.json (simple), Beads (git-backed with dependencies)\n- **AI Agents**: Claude Code, OpenCode, Factory Droid, Cursor CLI, Gemini CLI, Codex, Kiro CLI\n- **Session Persistence**: Pause anytime, resume later, survive crashes\n- **Real-time TUI**: Watch agent output, control execution with keyboard shortcuts\n- **Subagent Tracing**: See nested agent calls in real-time\n- **Cross-iteration Context**: Automatic progress tracking between tasks\n- **Flexible Skills**: Use PRD\u002Ftask skills directly in your agent or via the TUI\n- **Remote Instances**: Monitor and control ralph-tui running on multiple machines from a single TUI\n\n## CLI Commands\n\n| Command | Description |\n|---------|-------------|\n| `ralph-tui` | Launch the interactive TUI |\n| `ralph-tui run [options]` | Start Ralph execution |\n| `ralph-tui resume` | Resume an interrupted session |\n| `ralph-tui status` | Check session status |\n| `ralph-tui logs` | View iteration output logs |\n| `ralph-tui setup` | Run interactive project setup |\n| `ralph-tui create-prd` | Create a new PRD interactively |\n| `ralph-tui convert` | Convert PRD to tracker format |\n| `ralph-tui config show` | Display merged configuration |\n| `ralph-tui template show` | Display current prompt template |\n| `ralph-tui plugins agents` | List available agent plugins |\n| `ralph-tui plugins trackers` | List available tracker plugins |\n| `ralph-tui run --listen` | Run with remote listener enabled |\n| `ralph-tui remote \u003Ccmd>` | Manage remote server connections |\n\n### Common Options\n\n```bash\n# Run with a PRD file\nralph-tui run --prd .\u002Fprd.json\n\n# Run with a Beads epic\nralph-tui run --epic my-epic-id\n\n# Run one parallel session across multiple Beads epics\nralph-tui run --parallel --epic ui-epic --epic backend-epic\nralph-tui run --parallel --epics ui-epic,backend-epic\n\n# Override agent or model\nralph-tui run --agent claude --model sonnet\nralph-tui run --agent opencode --model anthropic\u002Fclaude-3-5-sonnet\n\n# Limit iterations\nralph-tui run --iterations 5\n\n# Run headless (no TUI)\nralph-tui run --headless\n\n# Run agent in isolated sandbox (bwrap on Linux, sandbox-exec on macOS)\n# Requires bwrap to be installed and on PATH (Linux) or uses built-in sandbox-exec (macOS)\nralph-tui run --sandbox\n\n# Use a bundled color theme by name\nralph-tui run --theme dracula\n```\n\n### Create PRD Options\n\n```bash\n# Create a PRD with AI assistance (default chat mode)\nralph-tui create-prd\nralph-tui prime  # Alias\n\n# Use a custom PRD skill from skills_dir\nralph-tui create-prd --prd-skill my-custom-skill\n\n# Override agent\nralph-tui create-prd --agent claude\n\n# Output to custom directory\nralph-tui create-prd --output .\u002Fdocs\n```\n\n### TUI Keyboard Shortcuts\n\n| Key | Action |\n|-----|--------|\n| `s` | Start execution |\n| `p` | Pause\u002FResume |\n| `d` | Toggle dashboard |\n| `g` | Cycle scope filter in multi-epic sessions |\n| `G` | Reset scope filter to All |\n| `T` | Toggle subagent tree panel (Shift+T) |\n| `t` | Cycle subagent detail level |\n| `o` | Cycle right panel views |\n| `a` | Open agent\u002Fmodel picker (local tab only) |\n| `,` | Open settings (local tab only) |\n| `C` | Open read-only config viewer (Shift+C, works on local and remote tabs) |\n| `q` | Quit |\n| `?` | Show help |\n| `1-9` | Switch to tab 1-9 (remote instances) |\n| `[` \u002F `]` | Previous\u002FNext tab |\n| `A` | Add new remote instance |\n| `e` | Edit current remote (when viewing remote tab) |\n| `x` | Delete current remote (when viewing remote tab) |\n\n**Multi-epic sessions:** Repeated `--epic` and comma-separated `--epics` create one Ralph session across all selected hierarchy-tracker epics. Ralph uses one scheduler, one repo lock, one session branch, one merge queue, and task-scoped worktrees. The TUI scope filter (`g`\u002F`G`) is only a local view filter over that session.\n\n**Dashboard (`d` key):** Toggle a status panel showing:\n- Current execution status and active task\n- Agent name and model (e.g., `claude-code`, `anthropic\u002Fclaude-sonnet`)\n- Tracker source (e.g., `prd`, `beads`)\n- Git branch with dirty indicator (repo:branch*)\n- Sandbox status (🔒 enabled, 🔓 disabled) with mode\n- Auto-commit setting (✓ auto, ✗ manual)\n- Remote connection info (when viewing remote tabs)\n\nSee the [full CLI reference](https:\u002F\u002Fralph-tui.com\u002Fdocs\u002Fcli\u002Foverview) for all options.\n\n### Custom Themes\n\nRalph TUI supports custom color themes via the `--theme` option:\n\n```bash\n# Use a bundled theme by name\nralph-tui run --theme dracula\n\n# Or use a custom theme file\nralph-tui run --theme .\u002Fmy-custom-theme.json\n```\n\n![Custom Theme Example](docs\u002Fimages\u002Ftheme-example.png)\n\nBundled themes: `bright`, `catppuccin`, `dracula`, `high-contrast`, `solarized-light`\n\nSee the [Themes documentation](https:\u002F\u002Fralph-tui.com\u002Fdocs\u002Fconfiguration\u002Fthemes) for the full theme schema and creating custom themes.\n\n### Using Skills Directly in Your Agent\n\nInstall ralph-tui skills to your agent using [add-skill](https:\u002F\u002Fgithub.com\u002Fvercel-labs\u002Fadd-skill):\n\n```bash\n# Install all skills to all detected agents globally\nbunx add-skill subsy\u002Fralph-tui --all\n\n# Install to a specific agent\nbunx add-skill subsy\u002Fralph-tui -a claude-code -g -y\nbunx add-skill subsy\u002Fralph-tui -a kiro-cli -g -y\n\n# Or use the ralph-tui wrapper (maps agent IDs automatically)\nralph-tui skills install\nralph-tui skills install --agent claude\nralph-tui skills install --agent kiro\n# If symlinked installs are problematic, copy files instead:\nralph-tui skills install --copy\n```\n\nUse these slash commands in your agent:\n\n```bash\n\u002Fralph-tui-prd           # Create a PRD interactively\n\u002Fralph-tui-create-json   # Convert PRD to prd.json\n\u002Fralph-tui-create-beads  # Convert PRD to Beads issues\n```\n\nThis lets you create PRDs while referencing source files (`@filename`) and using your full conversation context—then use `ralph-tui run` for autonomous execution.\n\n### Custom Skills Directory\n\nYou can configure a custom `skills_dir` in your config file to use custom PRD skills:\n\n```bash\n# In .ralph-tui\u002Fconfig.toml or ~\u002F.config\u002Fralph-tui\u002Fconfig.toml\nskills_dir = \"\u002Fpath\u002Fto\u002Fmy-skills\"\n\n# Then use custom skills\nralph-tui create-prd --prd-skill my-custom-skill\n```\n\nSkills must be folders inside `skills_dir` containing a `SKILL.md` file.\n\n## Remote Instance Management\n\nControl multiple ralph-tui instances running on different machines (VPS servers, CI\u002FCD environments, development boxes) from a single TUI.\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│  LOCAL [1]│ ● prod [2]│ ◐ staging [3]│ ○ dev [4]│      +       │\n├─────────────────────────────────────────────────────────────────┤\n│                                                                 │\n│   Your local TUI can connect to and control remote instances    │\n│                                                                 │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n### Quick Start: Remote Control\n\n**On the remote machine (server):**\n```bash\n# Start ralph with remote listener enabled\nralph-tui run --listen --prd .\u002Fprd.json\n\n# First run generates a secure token - save it!\n# ═══════════════════════════════════════════════════════════════\n#                    Remote Listener Enabled\n# ═══════════════════════════════════════════════════════════════\n#   Port: 7890\n#   New server token generated:\n#   OGQwNTcxMjM0NTY3ODkwYWJjZGVmMDEyMzQ1Njc4OQ\n#   ⚠️  Save this token securely - it won't be shown again!\n# ═══════════════════════════════════════════════════════════════\n```\n\n**On your local machine (client):**\n```bash\n# Add the remote server\nralph-tui remote add prod server.example.com:7890 --token OGQwNTcxMjM0NTY3...\n\n# Test the connection\nralph-tui remote test prod\n\n# Launch TUI - you'll see tabs for local + remote instances\nralph-tui\n```\n\n### Remote Listener Commands\n\n**Recommended: Use `run --listen`** (runs engine with remote access):\n```bash\n# Start with remote listener on default port (7890)\nralph-tui run --listen --prd .\u002Fprd.json\n\n# Start with custom port\nralph-tui run --listen --listen-port 8080 --epic my-epic\n```\n\n**Token management:**\n```bash\n# Rotate authentication token (invalidates old token immediately)\nralph-tui run --listen --rotate-token --prd .\u002Fprd.json\n\n# View remote listener options\nralph-tui run --help\n```\n\n### Remote Configuration Commands\n\n```bash\n# Add a remote server\nralph-tui remote add \u003Calias> \u003Chost:port> --token \u003Ctoken>\n\n# List all remotes with connection status\nralph-tui remote list\n\n# Test connectivity to a specific remote\nralph-tui remote test \u003Calias>\n\n# Remove a remote\nralph-tui remote remove \u003Calias>\n\n# Push config to a remote (propagate your local settings)\nralph-tui remote push-config \u003Calias>\nralph-tui remote push-config --all  # Push to all remotes\n```\n\n### Push Configuration to Remotes\n\nWhen managing multiple ralph-tui instances, you typically want them all to use the same configuration. The `push-config` command lets you propagate your local config to remote instances:\n\n```bash\n# Push config to a specific remote\nralph-tui remote push-config prod\n\n# Preview what would be pushed (without applying)\nralph-tui remote push-config prod --preview\n\n# Push to all configured remotes\nralph-tui remote push-config --all\n\n# Force overwrite existing config without confirmation\nralph-tui remote push-config prod --force\n\n# Push specific scope (global or project config)\nralph-tui remote push-config prod --scope global\nralph-tui remote push-config prod --scope project\n```\n\n**How it works:**\n1. Reads your local config (`~\u002F.config\u002Fralph-tui\u002Fconfig.toml` or `.ralph-tui\u002Fconfig.toml`)\n2. Connects to the remote instance\n3. Checks what config exists on the remote\n4. Creates a backup if overwriting (e.g., `config.toml.backup.2026-01-19T12-30-00-000Z`)\n5. Writes the new config\n6. Triggers auto-migration to install skills\u002Ftemplates\n\n**Scope selection:**\n- `--scope global`: Push to `~\u002F.config\u002Fralph-tui\u002Fconfig.toml` on remote\n- `--scope project`: Push to `.ralph-tui\u002Fconfig.toml` in remote's working directory\n- Without `--scope`: Auto-detects based on what exists locally and remotely\n\n### Security Model\n\nRalph uses a two-tier token system for secure remote access:\n\n| Token Type | Lifetime | Purpose |\n|------------|----------|---------|\n| Server Token | 90 days | Initial authentication, stored on disk |\n| Connection Token | 24 hours | Session authentication, auto-refreshed |\n\n**Security features:**\n- Without a token configured, the listener binds only to localhost (127.0.0.1)\n- With a token configured, the listener binds to all interfaces (0.0.0.0)\n- All connections require authentication\n- All remote actions are logged to `~\u002F.config\u002Fralph-tui\u002Faudit.log`\n- Tokens are shown only once at generation time\n\n### Connection Resilience\n\nRemote connections automatically handle network interruptions:\n\n- **Auto-reconnect**: Exponential backoff from 1s to 30s (max 10 retries)\n- **Silent retries**: First 3 retries are silent, then toast notifications appear\n- **Status indicators**: `●` connected, `◐` connecting, `⟳` reconnecting, `○` disconnected\n- **Metrics display**: Latency (ms) and connection duration shown in tab bar\n\n### Tab Navigation\n\nWhen connected to remote instances, a tab bar appears at the top of the TUI:\n\n| Key | Action |\n|-----|--------|\n| `1-9` | Jump directly to tab 1-9 |\n| `[` | Previous tab |\n| `]` | Next tab |\n| `Ctrl+Tab` | Next tab |\n| `Ctrl+Shift+Tab` | Previous tab |\n\nThe first tab is always \"Local\" (your current machine). Remote tabs show the alias you configured with connection status.\n\n### Managing Remotes from the TUI\n\nYou can add, edit, and delete remote servers directly from the TUI without leaving the interface:\n\n**Add Remote (`A` key):**\nOpens a form dialog to configure a new remote:\n- **Alias**: A short name for the remote (e.g., \"prod\", \"dev-server\")\n- **Host**: The server address (e.g., \"192.168.1.100\", \"server.example.com\")\n- **Port**: The listener port (default: 7890)\n- **Token**: The server token (displayed on the remote when you start with `--listen`)\n\nUse `Tab`\u002F`Shift+Tab` to move between fields, `Enter` to save, `Esc` to cancel.\n\n**Edit Remote (`e` key):**\nWhen viewing a remote tab, press `e` to edit its configuration. The form pre-fills with current values. You can change any field, including the alias.\n\n**Delete Remote (`x` key):**\nWhen viewing a remote tab, press `x` to delete it. A confirmation dialog shows the remote details before deletion.\n\n### Full Remote Control\n\nWhen connected to a remote instance, you have full control:\n\n- **View**: Agent output, logs, progress, task list\n- **Control**: Pause, resume, cancel execution\n- **Modify**: Add\u002Fremove iterations, refresh tasks\n- **Start**: Begin new task execution\n\nAll operations work identically to local control with \u003C100ms perceived latency.\n\n### Configuration Files\n\n| File | Purpose |\n|------|---------|\n| `~\u002F.config\u002Fralph-tui\u002Fremote.json` | Server token storage |\n| `~\u002F.config\u002Fralph-tui\u002Fremotes.toml` | Remote server configurations |\n| `~\u002F.config\u002Fralph-tui\u002Faudit.log` | Audit log of all remote actions |\n| `~\u002F.config\u002Fralph-tui\u002Flisten.pid` | Daemon PID file |\n\n## Contributing\n\n### Development Setup\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fsubsy\u002Fralph-tui.git\ncd ralph-tui\nbun install\nbun run dev\n```\n\n### Build & Test\n\n```bash\nbun run build       # Build the project\nbun run typecheck   # Type check (no emit)\nbun run lint        # Run linter\nbun run lint:fix    # Auto-fix lint issues\n```\n\n### Testing\n\n```bash\nbun test            # Run all tests\nbun test --watch    # Run tests in watch mode\nbun test --coverage # Run tests with coverage\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md#testing) for detailed testing documentation including:\n- Test file naming conventions\n- Using factories and mocks\n- Writing new tests\n- Coverage requirements\n\n### Pull Request Requirements\n\nPRs must meet these requirements before being merged:\n- **>50% test coverage** on new\u002Fchanged lines (enforced by Codecov)\n- **Documentation updates** for any new or changed features\n- All CI checks passing (typecheck, lint, tests)\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md#pull-request-guidelines) for full PR guidelines.\n\n### Project Structure\n\n```\nralph-tui\u002F\n├── src\u002F\n│   ├── cli.tsx           # CLI entry point\n│   ├── commands\u002F         # CLI commands (run, resume, status, logs, listen, remote, etc.)\n│   ├── config\u002F           # Configuration loading and validation (Zod schemas)\n│   ├── engine\u002F           # Execution engine (iteration loop, events)\n│   ├── interruption\u002F     # Signal handling and graceful shutdown\n│   ├── logs\u002F             # Iteration log persistence\n│   ├── plugins\u002F\n│   │   ├── agents\u002F       # Agent plugins (claude, opencode)\n│   │   │   └── tracing\u002F  # Subagent tracing parser\n│   │   └── trackers\u002F     # Tracker plugins (beads, beads-bv, json)\n│   ├── remote\u002F           # Remote instance management\n│   │   ├── server.ts     # WebSocket server for remote control\n│   │   ├── client.ts     # WebSocket client with auto-reconnect\n│   │   ├── token.ts      # Two-tier token management\n│   │   ├── config.ts     # Remote server configuration (TOML)\n│   │   ├── audit.ts      # JSONL audit logging\n│   │   └── types.ts      # Type definitions\n│   ├── session\u002F          # Session persistence and lock management\n│   ├── setup\u002F            # Interactive setup wizard\n│   ├── templates\u002F        # Handlebars prompt templates\n│   ├── chat\u002F             # AI chat mode for PRD creation\n│   ├── prd\u002F              # PRD generation and parsing\n│   └── tui\u002F              # Terminal UI components (OpenTUI\u002FReact)\n│       └── components\u002F   # React components (TabBar, Toast, etc.)\n├── skills\u002F               # Bundled skills for PRD\u002Ftask creation\n│   ├── ralph-tui-prd\u002F\n│   ├── ralph-tui-create-json\u002F\n│   └── ralph-tui-create-beads\u002F\n├── website\u002F              # Documentation website (Next.js)\n└── docs\u002F                 # Images and static assets\n```\n\n### Key Technologies\n\n- [Bun](https:\u002F\u002Fbun.sh) - JavaScript runtime\n- [OpenTUI](https:\u002F\u002Fgithub.com\u002Fsst\u002Fopentui) - Terminal UI framework\n- [Handlebars](https:\u002F\u002Fhandlebarsjs.com) - Prompt templating\n\nSee [CLAUDE.md](CLAUDE.md) for detailed development guidelines.\n\n## Credits\n\nThanks to Geoffrey Huntley for the [original Ralph Wiggum loop concept](https:\u002F\u002Fghuntley.com\u002Fralph\u002F).\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n","Ralph TUI 是一个用于在终端中编排AI编码代理以自主完成任务列表的工具。它能够连接你的AI编码助手（如Claude Code、OpenCode等）到任务跟踪器，并在一个自主循环中运行它们，智能选择任务、处理错误并提供全程可见性。项目采用TypeScript编写，支持通过Bun进行安装和运行。适用于需要自动化代码生成或修改的场景，例如软件开发中的功能实现、Bug修复等任务，特别适合于希望提高开发效率和质量的团队和个人开发者使用。",2,"2026-06-11 03:51:12","high_star"]