{"id":47922286,"url":"https://github.com/sahil87/run-kit","last_synced_at":"2026-06-14T03:01:33.621Z","repository":{"id":348719696,"uuid":"1170681249","full_name":"sahil87/run-kit","owner":"sahil87","description":"Web-based tmux orchestration dashboard for long-running AI agent tasks","archived":false,"fork":false,"pushed_at":"2026-06-08T10:33:51.000Z","size":15182,"stargazers_count":47,"open_issues_count":1,"forks_count":10,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-08T12:20:03.162Z","etag":null,"topics":["agents","claude-code","cli","dashboard","developer-tools","fab-kit","mobile","orchestration","terminal","tmux","web-ui","worktrees"],"latest_commit_sha":null,"homepage":"https://shll.ai/run-kit","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sahil87.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-02T11:52:31.000Z","updated_at":"2026-06-08T10:33:53.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/sahil87/run-kit","commit_stats":null,"previous_names":["sahil87/run-kit"],"tags_count":96,"template":false,"template_full_name":null,"purl":"pkg:github/sahil87/run-kit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sahil87%2Frun-kit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sahil87%2Frun-kit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sahil87%2Frun-kit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sahil87%2Frun-kit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sahil87","download_url":"https://codeload.github.com/sahil87/run-kit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sahil87%2Frun-kit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34307685,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-14T02:00:07.365Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","claude-code","cli","dashboard","developer-tools","fab-kit","mobile","orchestration","terminal","tmux","web-ui","worktrees"],"created_at":"2026-04-04T06:16:46.023Z","updated_at":"2026-06-14T03:01:33.615Z","avatar_url":"https://github.com/sahil87.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# \u003cimg src=\"https://raw.githubusercontent.com/sahil87/run-kit/main/assets/logo.svg\" alt=\"run-kit logo\" width=\"32\" height=\"32\"\u003e run-kit\n\n\u003e Part of [@sahil87's open source toolkit](https://shll.ai) — see all projects there.\n\n[![Latest release](https://img.shields.io/github/v/release/sahil87/run-kit)](https://github.com/sahil87/run-kit/releases) [![Downloads](https://img.shields.io/github/downloads/sahil87/run-kit/total)](https://github.com/sahil87/run-kit/releases) [![Stars](https://img.shields.io/github/stars/sahil87/run-kit?style=social)](https://github.com/sahil87/run-kit/stargazers)\n\n`rk riff` spawns AI coding agents in parallel [git worktrees](https://github.com/sahil87/wt). The browser dashboard lets you watch them all — from your desk or your phone.\n\n## Why run-kit?\n\n- **One command per parallel agent** — `rk riff` creates a worktree, opens a tmux window in it, and launches Claude Code. `rk riff -N 3` spawns three workspaces in parallel; failures roll back cleanly.\n- **Browser dashboard for tmux** — every tmux session and pane shows up in a sidebar. Click a pane for a live terminal in the browser; open the same dashboard on your phone over Tailscale.\n- **Mobile-first, keyboard-first** — `Cmd+K` command palette is the primary discovery surface. Touch targets are tuned for mobile so you can drive an agent session from your phone while away from your desk.\n- **No database, no daemon magic** — state is derived from tmux and the filesystem. Agent sessions survive `rk` restarts because the daemon never touches them.\n- **The dashboard layer over [`fab-kit`](https://github.com/sahil87/fab-kit) and [`wt`](https://github.com/sahil87/wt)** — `rk riff --skill /fab-fff` launches a full fab-kit pipeline in an isolated worktree. Use rk when you have more parallel changes than you can watch in a single terminal.\n\n## Screenshots\n\n\u003cimg alt=\"Desktop — terminal session with sidebar (servers, sessions, panes) and host stats\" src=\"https://github.com/user-attachments/assets/fbbe6171-e265-424a-b3fa-1a3194de3a09\" /\u003e\n\n\u003cp\u003e\n  \u003cimg width=\"32%\" alt=\"Mobile menu — drawer with servers, sessions, and panes\" src=\"https://github.com/user-attachments/assets/1326355e-6031-4620-9ce9-355b82bf8313\" /\u003e\n  \u003cimg width=\"32%\" alt=\"Mobile dashboard — session and window overview\" src=\"https://github.com/user-attachments/assets/35645b54-d6d4-463f-8dc3-9d44e4c76dd5\" /\u003e\n  \u003cimg width=\"32%\" alt=\"Mobile terminal session\" src=\"https://github.com/user-attachments/assets/f07a0166-7674-41fe-8376-ef34fd2a1afb\" /\u003e\n\u003c/p\u003e\n\n## The mental model\n\nrk is two independent halves that compose:\n\n```\nrk riff              rk serve\n  ▼                    ▼\nspawns agent        runs the\nworkspaces ─────►   browser dashboard\n(tmux + worktree)   (watches tmux)\n```\n\nYou can run either alone. Run `rk riff` in any tmux session without ever starting `rk serve` — you get the spawning behavior, no dashboard. Run `rk serve` and never call `rk riff` — you get a tmux browser dashboard for sessions you spawn manually. The two are designed to compose, not depend on each other.\n\n## Quick start\n\nFrom a clean install to a working dashboard with one agent running:\n\n```bash\nbrew install sahil87/tap/rk     # install\nrk serve -d                     # start the dashboard daemon on :3000\nopen http://localhost:3000      # open the dashboard in your browser\n\n# in any tmux session:\nrk riff --skill /fab-discuss    # spawn an agent workspace\n```\n\nThe new workspace appears in the dashboard's sidebar; click into it to drive the agent from the browser.\n\nTo upgrade later, run `rk update` — pulls the latest version via Homebrew and restarts the daemon so the new binary takes effect immediately.\n\nSee the [install \u0026 access guide](docs/site/install.md) for prerequisites, `rk doctor`, development setup, and driving rk from your phone over Tailscale HTTPS.\n\n## `rk riff` — the spawner\n\nThe headline command. One invocation gives you a git worktree, a tmux window inside it, and one or more Claude Code panes ready to go.\n\n**Pane array model.** `--skill` and `--cmd` are repeatable. Each occurrence adds one pane; argv order (left to right) becomes pane order. Bare `--skill` opens a blank Claude session; bare `--cmd` drops into `$SHELL`.\n\n**Layouts.** `auto` (default), `tiled`, `even-horizontal`, `even-vertical`, `main-horizontal`, `main-vertical`. Set with `--layout`.\n\n**Presets.** Common pane/layout combos go in `fab/project/config.yaml` under `riff.presets.\u003cname\u003e`. Invoke as `rk riff \u003cname\u003e` or `rk riff --preset \u003cname\u003e`.\n\n**Parallel.** `-N \u003cN\u003e` spawns N workspaces in parallel; failures roll back successful ones before exiting.\n\n**wt passthrough.** Flags after `--` go to `wt create` verbatim (e.g. `--base`, `--reuse`, `--worktree-name`).\n\nExamples:\n\n```bash\nrk riff                                              # 1 pane, default skill (/fab-discuss)\nrk riff --skill /fab-fff                             # 1 pane, specific slash-command\nrk riff --skill /fab-fff --cmd \"just dev\"            # 2 panes (agent + dev server)\nrk riff --skill /a --cmd x --cmd y --layout main-vertical\nrk riff ship                                         # invoke the 'ship' preset\nrk riff ship -N 3                                    # 3 parallel ship workspaces\nrk riff -- --worktree-name pacing-canyon             # name the worktree\n```\n\n**Prerequisites:** must be inside a tmux session, [`wt`](https://github.com/sahil87/wt) on `PATH`, and the launcher (default `claude --dangerously-skip-permissions`) available. Override the launcher per-project via `agent.spawn_command` in `fab/project/config.yaml`.\n\nSee the [riff guide](docs/site/workflows.md) for the full reference.\n\n## `rk serve` — the dashboard daemon\n\nStart the HTTP server. Configurable via `RK_HOST` (default `127.0.0.1`) and `RK_PORT` (default `3000`).\n\n```bash\nrk serve                                # foreground on 127.0.0.1:3000\nRK_HOST=0.0.0.0 RK_PORT=8080 rk serve   # bind all interfaces, port 8080\nrk serve -d                             # background daemon in a tmux session\nrk serve --restart                      # idempotent restart\nrk serve --stop                         # graceful shutdown\n```\n\nThe daemon runs in its own dedicated tmux server (`rk-daemon`), completely separate from your agent sessions. Restart the daemon and your agents keep running — the dashboard reconnects automatically.\n\n## Boards — watch many panes at once\n\nA **board** is a named, cross-server pane dashboard. Pin any tmux window from any server into a board, and the board renders all pinned panes side-by-side in a horizontally-scrollable layout — perfect for watching three parallel agent sessions, or comparing a `just dev` server's output against the agent that's editing it.\n\nThree ways to pin a window to a board:\n\n1. **Sidebar pin icon** — every window row in the sidebar has a pin icon. Click it to open a popover listing existing boards (click to pin/unpin), plus a \"Pin to new board…\" input that creates a new board on first pin.\n2. **Command palette (`Cmd+K`)** — `Board: Pin Current Window`, `Board: Unpin Current Window`, `Board: Switch to \u003cname\u003e`, `Board: Leave Board View`.\n3. **Board pane header** — each pinned pane shows an unpin button in its header for one-click removal.\n\nInside a board:\n\n- **`Cmd+]` / `Cmd+[`** cycles pane focus to the next / previous pane (wraps).\n- **Click a pane** to focus it; keystrokes route to that pane's terminal.\n- **Drag the pane edge** to resize (desktop only; widths persist per-board in `localStorage`).\n- **On mobile**, panes render as a single-pane swipe carousel.\n\nPin state lives in tmux (via the `@rk_board` window option) so it follows the window, not the browser — open the same board URL on your phone and you see the same panes. Pane widths are intentionally local to each device.\n\n## Drive it from your phone (HTTPS over Tailscale)\n\nSome browser features (clipboard, secure context) require HTTPS. Accessing rk from another machine on your tailnet also requires HTTPS:\n\n1. Enable HTTPS at [DNS \u003e HTTPS Certificates](https://login.tailscale.com/admin/dns).\n2. Run `tailscale serve --bg http://localhost:3000`.\n3. Open `https://\u003cmachine\u003e.\u003ctailnet\u003e.ts.net` on your phone or another laptop.\n\nFor a stable custom hostname or public access via Funnel, see the [Tailscale guide](docs/site/install.md).\n\n## Shell completion\n\n`rk shell-init \u003cshell\u003e` emits eval-safe tab-completion for your shell. Add this line to your rc file:\n\n```sh\neval \"$(rk shell-init zsh)\"   # in ~/.zshrc\neval \"$(rk shell-init bash)\"  # in ~/.bashrc\n```\n\nSupports `zsh`, `bash`, `fish`, and `powershell`. Completion-only — rk has no shell function wrapper; every subcommand is reached via `rk \u003csubcommand\u003e`.\n\n\u003e 💡 Have other sahil87 tools? [`shll shell-install`](https://github.com/sahil87/shll#shll-shell-install--wire-the-rc-file-recommended) handles all of their shell integrations and autocompletions at once.\n\n## Command reference\n\n| Command | What it does |\n|---------|--------------|\n| `rk riff` | Create a worktree + tmux window + Claude Code pane(s). |\n| `rk serve` | Start the HTTP server (foreground or daemon). |\n| `rk status` | Show a tmux session summary. |\n| `rk context` | Print agent-optimized environment info (server URL, ports, etc.) — designed to be read by AI agents inside an rk-spawned workspace. |\n| `rk doctor` | Check runtime dependencies. Run this first when something breaks. |\n| `rk init-conf` | Scaffold default `tmux.conf` and `tmux.d/` drop-in directory to `~/.rk/`. Optional. |\n| `rk update` | Upgrade via Homebrew and restart the daemon. |\n| `rk completion` | Generate shell completion scripts (or use `rk shell-init` for eval-safe output). |\n| `rk help` | Help about any command. |\n\nRun `rk \u003ccommand\u003e --help` for full flag details, or see the [full command reference](https://shll.ai/tools/run-kit/commands/) for every command and flag.\n\n## Troubleshooting\n\n- **`rk riff` fails with \"not in a tmux session\"** — riff requires `$TMUX` to be set. Start tmux first (`tmux new -s work`), then run `rk riff` inside it.\n- **`rk riff` fails with \"wt not found\"** — install `wt` via `brew install sahil87/tap/wt`, or via the toolkit meta-formula `brew install sahil87/tap/all`.\n- **Anything else broken** — run `rk doctor`. It checks tmux, `wt`, the launcher binary, port availability, and prints per-dependency status.\n\n## Architecture\n\nrk's daemon runs in a dedicated tmux server (`rk-daemon`), separate from agent sessions (`runkit`). Restarts use kill-and-restart (no polling loop or signal files), are idempotent (`--restart` works whether or not a daemon is running), and never touch agent tmux sessions — agents survive daemon restarts unaffected.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsahil87%2Frun-kit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsahil87%2Frun-kit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsahil87%2Frun-kit/lists"}