Skip to content
Back to search

fleet

SkillWorks with Claude CodeGitHub

Run a fleet of interactive Claude Code workers as windows of one tmux session (Claude Code skill + CLI)

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/abellagonzalo--fleet/badge.svg)](/listings/abellagonzalo--fleet)

HTML

<a href="/listings/abellagonzalo--fleet"><img src="/api/listings/abellagonzalo--fleet/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Symlink the CLI and the two skills:

ln -s <this checkout>/scripts/fleet ~/.local/bin/fleet ln -s <this checkout>/skills/fleet-orchestrator ~/.claude/skills/fleet-orchestrator ln -s <this checkout>/skills/fleet-worker ~/.claude/skills/fleet-worker

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 126 lines
  1. # fleet
  2. Run several interactive Claude Code sessions side by side, each in its own git worktree, as
  3. windows of one tmux session, with one more Claude Code acting as the **orchestrator** that keeps
  4. track of them for you.
  5. Every worker is a normal Claude Code TUI. You can attach to any window and drive it yourself at
  6. any time. The orchestrator tells you which workers need you, relays your prompts and their replies,
  7. and hands every permission dialog and question back to you. It never decides anything on its own.
  8. ```
  9. tmux session "fleet"
  10. ├── 0: orch orchestrator (/fleet-orchestrator)
  11. ├── 1: PROJ-123 ⋯ worker in <repo>/PROJ-123, busy
  12. ├── 2: fix-dates ⚠ worker in <repo>/fix-dates, waiting on a permission dialog
  13. └── 3: docs-cleanup ✓ worker in <repo>/docs-cleanup, finished a turn
  14. ```
  15. ## Requirements
  16. - macOS (notifications go through `osascript`), tmux, and Claude Code (`claude`) on PATH.
  17. - Python 3.9+, standard library only. It runs under macOS's `/usr/bin/python3` and needs no install step.
  18. - [worktrunk](https://github.com/max-sixty/worktrunk) (`wt`) to create and remove worktrees. You
  19. only need it for worktree workers; `--no-worktree` workers run without it.
  20. - Repos laid out as `<repo>/main` (the main checkout), with each worktree as a sibling:
  21. `<repo>/<branch>`.
  22. ## Install
  23. Symlink the CLI and the two skills:
  24. ln -s <this checkout>/scripts/fleet ~/.local/bin/fleet
  25. ln -s <this checkout>/skills/fleet-orchestrator ~/.claude/skills/fleet-orchestrator
  26. ln -s <this checkout>/skills/fleet-worker ~/.claude/skills/fleet-worker
  27. ## Quick start
  28. fleet up # tmux session "fleet", orchestrator in window 0, attaches you
  29. Then talk to the orchestrator in plain language, for example "start a worker on ~/github/acme/api
  30. for PROJ-123 and have it fix the date parsing bug". It runs the `fleet` commands for you. You can
  31. also run them yourself from any shell:
  32. fleet new ~/github/acme/api PROJ-123 --prompt-stdin <<'EOF'
  33. Fix the date parsing bug described in PROJ-123.
  34. EOF
  35. fleet status # state, age and last reply of every worker
  36. fleet wait PROJ-123 # block until it finishes or needs you
  37. fleet last PROJ-123 # its last reply
  38. fleet rm PROJ-123 # close the window, remove the worktree if clean; the branch stays
  39. `fleet help` lists every command and flag.
  40. ## How it works
  41. **Sessions and workers.** `fleet up [name]` creates the tmux session `fleet` (or `fleet-<name>`)
  42. and starts the orchestrator in window 0 with `/fleet-orchestrator`. `fleet new <repo> <branch>`
  43. opens a window named `<branch>` in the worktree `<repo>/<branch>`. If that worktree or branch
  44. already exists, fleet reuses it. Otherwise it fetches origin and branches from the default branch.
  45. The worktree is made with `wt`, and its post-start hooks run before claude starts, so `new` can
  46. take a minute. Workers start with `/fleet-worker` and reply `Ready: ...` when they are up. You
  47. address workers by window name, which is also their branch.
  48. **State.** `fleet new` wires `scripts/fleet-hook` into every worker through `claude --settings`.
  49. The hook records each worker's state under `~/.local/state/fleet` (override it with
  50. `FLEET_STATE_DIR`) and marks the window tab:
  51. | state | meaning | tab |
  52. |-----------|-----------------------------------------------------------------|-----|
  53. | `busy` | working on a turn | ⋯ |
  54. | `blocked` | a permission dialog or question is waiting for you (plus a macOS notification) | ⚠ |
  55. | `done` | finished a turn | ✓ |
  56. | `idle` | fresh, or the turn was interrupted | |
  57. | `exited` | claude quit; the window holds a shell | |
  58. Hooks miss a few changes, such as interrupts and cancelled dialogs. `status` and `wait` correct
  59. for that by reading the screen.
  60. **Hand-offs.** The worker skill makes every reply open with a headline that fits in `fleet status`:
  61. `Done: ...`, `Need input: ...` or `Failed: ...`. A `done` worker whose reply says `Need input:` is
  62. waiting on you just as much as a `blocked` one.
  63. **Sending prompts safely.** Panes are shared with you, so `fleet send` types like a human, checks
  64. that the text landed, and then presses Enter. It refuses if the prompt box holds text you typed,
  65. if a dialog is open, or if claude has exited. Long prompts go through `--prompt-stdin` or
  66. `--prompt-file`: the worker is told "Read <file> and do what it says.", so newlines, quotes and
  67. length all survive. `fleet broadcast` sends one prompt to many workers, and `send --now` interrupts
  68. a running turn.
  69. ## Repository layout
  70. - `skills/fleet-orchestrator/SKILL.md`: how the orchestrator uses fleet, including what it may do
  71. without asking you.
  72. - `skills/fleet-worker/SKILL.md`: what every worker loads as its first prompt (worktree rules,
  73. hand-off format).
  74. - `scripts/fleet`: the CLI. `scripts/fleet-hook`: the Claude Code hook. It prints nothing and
  75. always exits 0, so it can never block Claude.
  76. - `scripts/fleetlib/`: the code.
  77. - `cli.py`: the commands.
  78. - `screen.py`: reads Claude Code's TUI from tmux captures.
  79. - `state.py`: the state files and the reconcile and wait rules.
  80. - `system.py`: the only place that runs tmux, git or wt.
  81. - `hook.py`: the hook.
  82. ## Development
  83. ### Tests
  84. python3 -m unittest discover -s tests
  85. `tests/fixtures/` holds captures of real Claude Code screens: `*.ansi` from
  86. `tmux capture-pane -e -p` and `*.txt` from `tmux capture-pane -p`. When Claude Code's UI changes,
  87. capture the new screen from a throwaway worker and add it there.
  88. ### Live checks
  89. Never test against the fleet you are working in. Use a session and state dir of your own:
  90. export FLEET_SESSION=fleet-test FLEET_STATE_DIR=/tmp/fleet-test/state
  91. tmux new-session -d -s fleet-test -n orch && tmux set -p -t =fleet-test:orch @fleet_role orch
  92. scripts/fleet new --no-worktree /tmp/somewhere w1 -- --model haiku
  93. ...
  94. tmux kill-session -t =fleet-test
  95. Never run `scripts/fleet-hook` by hand from inside a fleet worker unless `FLEET_STATE_DIR` points
  96. to a scratch dir. Otherwise it writes into that worker's live state file.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.