Skip to content
Back to search

hyperdo

MarketplaceWorks with Claude CodeGitHub

Minimal parallel agent orchestration for Claude Code. One lead plans the work as threads in PLAN.md; background workers build them side by side, coordinated by file locks and a shared log. Markdown-only state, no dependencies.

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/grplyler--hyperdo/badge.svg)](/listings/grplyler--hyperdo)

HTML

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

Install

Install instructions from the README

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

Needs the [`claude` CLI](https://claude.com/claude-code) and bash.

git clone https://github.com/grplyler/hyperdo.git
cd hyperdo && ./install.sh

Restart Claude Code, then run `/hyper:init` and `/hyper:plan` in any project.

That's the whole install. There is no step 3, no account, no "book a demo" and nothing to upgrade at 2am.

Support tracker

| Tool | Status | How it installs | Notes | | --- | --- | --- | --- | | Claude Code | ✅ Supported | Plugin: `/hyper:*` commands | Where Hyperdo is built and used every day. | | Codex CLI | ❌ Not supported | — | Too bad. | | Anything else | ❌ Not yet | — | The whole thing is Markdown, so a port is mostly a copy. PRs welcome. |

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.

.claude-plugin/marketplace.json · Manifest · 1 lines
  1. {"name":"hyperdo","owner":{"name":"local"},"plugins":[{"name":"hyper","source":"./plugins/hyper","description":"Lightweight parallel Claude agents, plain Markdown, state in files you can edit: /hyper:init, /hyper:plan, /hyper:add, /hyper:do, /hyper:config, /hyper:status, /hyper:clean"}]}
README.md · README · 317 lines
  1. <div align="center">
  2. <img src="assets/mascot.svg" width="160" alt="Hyperdo mascot: a small round orange bird sprinting while juggling five checkboxes in one clean arc, four already ticked">
  3. # Hyperdo
  4. ### Do five things at once. Understand none of them.
  5. **Minimal parallel agent orchestration for Claude Code. One lead plans the work as threads in PLAN.md; background workers build them side by side, coordinated by file locks and a shared log. Markdown-only state, no dependencies.**
  6. ![Claude Code plugin](https://img.shields.io/badge/Claude_Code-plugin-D97757?style=flat-square) [![License: MIT](https://img.shields.io/badge/License-MIT-blue?style=flat-square)](LICENSE)
  7. **[→ The extremely serious website](https://grplyler.github.io/hyperdo/)**
  8. *Revolutionary. Disruptive. Fits in a Markdown file. We checked.*
  9. **Why?** Cause I wanted to build something way cooler and needed this to do so.
  10. </div>
  11. > **NEW:** Hyperdo now supports being installed. (It always did. We needed an announcement.)
  12. > [!NOTE]
  13. > This README is silly on purpose. The jokes are labelled; the commands, install steps, tables and anything in a code block are real and checked against the source.
  14. Hyperdo is small on purpose. The whole plugin is 7 Markdown skill files plus one `WORKER.md` protocol, about 230 lines together, installed by a 7-line shell script. No runtime, no daemon, no server, no database: it needs only the `claude` CLI and bash. All state is plain files in your repo (`PLAN.md` and `.hyper/`) that you can read and edit by hand, and `./uninstall.sh` removes everything it installed.
  15. | 7 | ~230 | 0 | 0 |
  16. | :---: | :---: | :---: | :---: |
  17. | Markdown skill files, plus one `WORKER.md` | lines, all of it together | runtimes, daemons, servers or databases | merge conflicts, by design\* |
  18. | *It is a short read. Read it.* | *Your last PR was longer.* | *Just the `claude` CLI and bash.* | *\*By design. Your design may vary.* |
  19. You describe a goal. Hyperdo splits it into parallel **threads**, each owning a disjoint set of files, and launches background Claude agents to build them.
  20. - **No merge conflicts by design.** Every thread declares the files it `owns:`. Touching anything else needs a lock first. *Translation: a polite sign on the bathroom door.*
  21. - **Agents talk to each other.** Workers post to an append-only log, ask for contract changes, and release files when something urgent comes in. *Translation: a group chat where everyone has read the instructions.*
  22. - **You stay in control.** Change worker limits, testing rigor or model while it runs. Edit `PLAN.md` by hand whenever you like. *Translation: the database is a text file. Yes, really.*
  23. ## Install
  24. Needs the [`claude` CLI](https://claude.com/claude-code) and bash.
  25. ```bash
  26. git clone https://github.com/grplyler/hyperdo.git
  27. cd hyperdo && ./install.sh
  28. ```
  29. Restart Claude Code, then run `/hyper:init` and `/hyper:plan` in any project.
  30. That's the whole install. There is no step 3, no account, no "book a demo" and nothing to upgrade at 2am.
  31. ### Support tracker
  32. | Tool | Status | How it installs | Notes |
  33. | --- | --- | --- | --- |
  34. | Claude Code | ✅ Supported | Plugin: `/hyper:*` commands | Where Hyperdo is built and used every day. |
  35. | Codex CLI | ❌ Not supported | — | Too bad. |
  36. | Anything else | ❌ Not yet | — | The whole thing is Markdown, so a port is mostly a copy. PRs welcome. |
  37. ## How you'd expect it to work
  38. Seven commands. You will use two.
  39. ```text
  40. /hyper:init # set up this repo: CLAUDE.md + .hyper/
  41. /hyper:plan 4 "add OAuth login with tests" # write PLAN.md, run up to 4 workers until done
  42. /hyper:add -p 10 "fix flaky session test" # add one thread to the plan; urgent starts now
  43. /hyper:do "rename foo to bar" # one worker, right now, no plan
  44. /hyper:status # show progress; changes nothing unless asked
  45. /hyper:config rigor=slow # change a setting; running work picks it up
  46. /hyper:clean # delete hyper state, after showing the list
  47. ```
  48. ## What it looks like
  49. The plan the lead writes (abridged):
  50. ```markdown
  51. # PLAN: add OAuth login
  52. ## Contracts
  53. POST /auth/callback -> { token: string }; session type lives in src/auth/types.ts
  54. ## Threads
  55. ### T1 provider-client · p:5 · m:sonnet · owns: src/auth/provider/** · deps: — · status: doing:T1
  56. - [x] read existing HTTP client conventions
  57. - [ ] implement authorize/token exchange
  58. - [ ] check: npm run typecheck
  59. ### T2 login-ui · p:5 · m:sonnet · owns: src/ui/login/** · deps: — · status: doing:T2
  60. - [ ] build login button + callback page
  61. - [ ] check: npm test -- login
  62. ```
  63. While workers run, `.hyper/log.md` is their shared chat (five terminals, zero of them yours):
  64. ```text
  65. [lead] ADD T3 p:10: fix flaky session test
  66. [T1 14:02] NEED T1→all: add `expiresAt` to Session in contracts
  67. [lead] URGENT T3
  68. [T2] DONE: src/ui/login/**
  69. ```
  70. ## When to use it
  71. Good fit: a feature or refactor that splits into lanes touching different files (API plus UI plus tests, a rename across packages, a docs pass alongside code).
  72. Poor fit: a single tangled change where every step depends on the last. One agent does that better.
  73. Also a poor fit: wanting to understand what is happening at all times. See the charts.
  74. ## How it works
  75. ```mermaid
  76. flowchart TD
  77. U([You]) -->|"/hyper:plan 4 'goal'"| L[Lead agent]
  78. L -->|writes| P[(PLAN.md<br/>contracts + threads)]
  79. L -->|dispatches by priority| W1[Worker T1]
  80. L --> W2[Worker T2]
  81. L --> W3[Worker T3]
  82. W1 & W2 & W3 -->|read + tick steps| P
  83. W1 & W2 & W3 -->|mkdir lock before editing| K[(.hyper/locks/)]
  84. W1 & W2 & W3 <-->|append / tail| G[(.hyper/log.md)]
  85. C[(.hyper/config)] -.->|re-read every dispatch| L
  86. U -->|"/hyper:add, /hyper:config"| L
  87. W1 & W2 & W3 -->|DONE| L
  88. L -->|"next ready thread, then a final cheap check"| U
  89. ```
  90. - **Lead.** Skims the repo, writes `PLAN.md`, then loops: take ready threads (`todo`, deps done) by priority, launch up to `max_workers` background agents, launch the next as soon as one finishes. At the end it runs one whole-project check and reports done/total. It keeps its turns tiny and never does worker work.
  91. - **Workers.** Each is told only: *you are hyper worker T<k>, follow `WORKER.md`, your thread is in `PLAN.md`.*
  92. - **Contracts.** Shared interfaces go in a `## Contracts` section (or a T0 thread) so lanes never block on each other. A worker that needs a change posts `NEED` and stops that part; the lead decides.
  93. - **Locks are `mkdir`.** `mkdir .hyper/locks/<path>` is atomic and fails if someone else holds it. No daemon.
  94. - **Model per thread.** Opus for architecture and hard debugging, Sonnet for normal work, Haiku for mechanical edits. Override per command with `--model`.
  95. The worker protocol, in short:
  96. 1. Read `PLAN.md` (Contracts and own thread) and tail the log.
  97. 2. Claim the thread (`status: doing:T<k>`); lock any file outside `owns:`.
  98. 3. Build to the Contracts; need a change? Post `NEED T<k>→all: ...` and stop that part.
  99. 4. Append `[T<k> HH:MM] msg` to the log; answer `NEED`/`ASK` lines.
  100. 5. Tick steps and run checks per rigor. Checks are silent on success; full output goes to `.hyper/logs/T<k>-<check>.log`.
  101. 6. Finish: release locks, `status: done` (or `blocked:<why>`), log `[T<k>] DONE: <files>`, reply to the lead in at most 3 lines.
  102. ### Phases
  103. Automatic, and only for long plans (more than four threads across several dependency levels): the lead groups threads into milestones, each with a gate. You never assign them.
  104. ```markdown
  105. ## Phase 2 api
  106. gate: npm test -- api
  107. ```
  108. When a phase's last thread finishes, the lead runs the gate once and logs `[lead] PHASE 2 DONE` (or `PHASE 2 FAIL <log>` plus a fix thread). Only threads that depend on that phase wait for its gate; everything else keeps running. `/hyper:status` collapses done phases to one line. Add `· hold` to a phase heading to keep its threads from starting. Small plans stay flat.
  109. Thread format: `### T<k> <name> · p:<1-10> · m:<model> · owns: <globs> · deps: <ids or —> · status: <todo | doing:<worker> | done | blocked:<why>>`, plus optional `shares:` for files owned elsewhere.
  110. ## Commands
  111. | Command | What it does | Vibe |
  112. | --- | --- | --- |
  113. | `/hyper:init [--defaults]` | Like `/init`, hyper-aware: writes or refreshes `CLAUDE.md`, creates `.hyper/`, asks for config (or takes defaults), then offers to run `/hyper:plan`. | Sets the table. |
  114. | `/hyper:plan <N> "<goal>"` | Splits the goal into threads in `PLAN.md` and runs up to `N` workers until all are done. No args with an existing `PLAN.md` resumes. A new goal appends; it never overwrites. | The big red button. |
  115. | `/hyper:add [-p N] [--model <alias>] [--split [--force]] "<task>"` | Adds a thread with priority `N` (1-10, default 5) and starts a worker now if deps are done and a slot is free (or `N` >= 9). Priority 10 also logs `[lead] URGENT` so other workers release files it needs. | "Also, one more thing." |
  116. | `/hyper:do [--model <alias>] [--split [--force]] ["<task>"]` | With a task: one fire-and-forget worker outside `PLAN.md` (queued if `max_do` is reached). With no args: drives all ready threads in `PLAN.md`. | Rename foo to bar. Go. |
  117. | `/hyper:config [key=value ...]` | Sets limits, rigor, model, dev mode and the Code Mode record via a question UI, or directly (`rigor=slow max_workers=6`). Applies live. | Knobs. |
  118. | `/hyper:status` | Done/total, each thread's status and step progress, held locks, last 10 log lines, failing checks with log paths. Can reset a stuck `doing` thread on request. | Refresh, but legal. |
  119. | `/hyper:clean [--keep-plan]` | Deletes `.hyper/` and, unless `--keep-plan`, `PLAN.md`, after listing everything and asking. Refuses while workers look alive. Never touches `CLAUDE.md` or source. | Fresh start energy. |
  120. **`--split`** (on `add` and `do`) lets the lead judge whether the task is 2+ independent parts with disjoint files and runs one thread or worker per part. If it is not, it logs `[lead] NOSPLIT <why>` and runs one. `--split --force` always splits into 2+ parts along the best seam; `--force` alone implies it.
  121. **`--model`** aliases (precedence: `--model` > thread's `m:` tag > config `model` > automatic routing):
  122. | Alias | Model |
  123. | --- | --- |
  124. | `s55`, `sonnet` | Sonnet 5.5 |
  125. | `o55`, `opus` | Opus 5.5 |
  126. | `f52`, `fable` | Fable 5.2 |
  127. | `h55`, `haiku` | Haiku 5.5 |
  128. `/hyper:do` also still accepts the legacy `--opus`, `--sonnet` and `--haiku`.
  129. ## Configuration
  130. `.hyper/config` is one line of `key=value` pairs. Default: `max_workers=3 max_do=2 rigor=fast model=auto dev_mode=solo code_mode=off`.
  131. | Key | Values | Default | Meaning |
  132. | --- | --- | --- | --- |
  133. | `max_workers` | 1-20 | 3 | Concurrent plan workers |
  134. | `max_do` | 0-10 | 2 | Concurrent `/hyper:do` workers (0 disables) |
  135. | `rigor` | `fast` \| `medium` \| `slow` | `fast` | `fast`: the thread's own `check:` only. `medium`: plus tests for core logic. `slow`: tests on every change plus a self-review of the diff. |
  136. | `model` | `auto` \| `opus` \| `sonnet` \| `haiku` | `auto` | Worker model; `auto` routes by task |
  137. | `dev_mode` | `solo` \| `pro` \| `prod` | `solo` | How workers use git (below) |
  138. | `code_mode` | `on` \| `off` | `off` | Records whether Claude Code's experimental [Code Mode](https://code.claude.com/docs/en/code-mode.md) is on (see below) |
  139. Lowering limits never kills running workers; it only stops new launches.
  140. | `dev_mode` | Git workflow |
  141. | --- | --- |
  142. | `solo` | Shared tree, small commits on main, `git pull --rebase` and `git push` often, no PRs. Choosing it is your standing approval for those pushes. |
  143. | `pro` | Branch per thread, conventional commits, affected tests, PR via `gh`; the lead merges after checks pass. Never pushes to main. |
  144. | `prod` | `pro` plus rigor=slow, a worktree per thread, fresh-context review, CI green, no force-push, a CHANGELOG entry, and your approval before merge or deploy. |
  145. **Code Mode.** Toggling `code_mode` in `/hyper:init` or `/hyper:config` edits `env.CLAUDE_CODE_EXPERIMENTAL_CODE_MODE` in `~/.claude/settings.json`, always after confirmation, and needs a claude restart. It is experimental, interactive-terminal only (not `-p`, VS Code, Desktop or cloud), needs claude >= 2.1.323, and project settings are ignored for it. See the [docs](https://code.claude.com/docs/en/code-mode.md).
  146. **Auto mode and plan mode.** In auto mode, no confirmation questions: defaults are picked and logged as `[lead] DEFAULT <choice>`, but destructive or outward-facing actions (force-push, deploy, deleting data) still need your OK, and `/hyper:clean` always confirms. In plan mode, `/hyper:plan` researches read-only and shows the threads via ExitPlanMode; nothing is written and no worker starts until you approve. The other commands describe what they would do and exit plan mode before writing.
  147. ## Pricing
  148. Pick a plan. They all cost $0. The three plans are the three real `dev_mode` settings above.
  149. | Solo | Pro (most popular\*) | Prod |
  150. | :---: | :---: | :---: |
  151. | **$0** / forever | **$0** / forever | **$0** / forever |
  152. | *For people who push to main and sleep fine.* | *\*Popularity not measured.* | *For people who read the runbook.* |
  153. Your Claude usage is billed by Claude as usual. Hyperdo is MIT-licensed and adds no network calls of its own.
  154. ## Charts, because every README needs them
  155. All made up, none of them a benchmark. Vibes are not units.
  156. ```mermaid
  157. pie showData title Where the afternoon went (%)
  158. "Watching the workers work" : 34
  159. "Reading the log like a group chat" : 23
  160. "Naming the threads" : 15
  161. "Telling a coworker about it" : 12
  162. "Re-running /hyper:status just in case" : 11
  163. "Actual coding" : 5
  164. ```
  165. ```mermaid
  166. %%{init: {"themeVariables": {"xyChart": {"plotColorPalette": "#D97757, #7b5ea7"}}}}%%
  167. xychart-beta
  168. title "PLAN.md checkboxes ticked (the last 1% is where the project lives now)"
  169. x-axis "Hours since this-should-take-ten-minutes" [0, 1, 2, 3, 4, 5, 6, 7, 8]
  170. y-axis "Ticked (%)" 0 --> 100
  171. line [0, 1, 3, 9, 28, 66, 91, 99, 99]
  172. ```
  173. ```mermaid
  174. %%{init: {"themeVariables": {"xyChart": {"plotColorPalette": "#D97757, #7b5ea7"}}}}%%
  175. xychart-beta
  176. title "Confidence (up) vs. understanding (down), in vibes"
  177. x-axis "Hours into the session" [0, 1, 2, 3, 4, 5, 6, 7, 8]
  178. y-axis "Vibes" 0 --> 100
  179. line [20, 34, 55, 72, 84, 91, 96, 99, 100]
  180. line [90, 80, 60, 44, 31, 21, 13, 8, 5]
  181. ```
  182. ## People are saying things
  183. > "I literally made this in like 30 mins so I could build something way cooler. But it Fu**ing works and I love that for me (and you I guess)."
  184. >
  185. > **The creator of Hyperdo** · the one real quote in this section
  186. > "I pressed Enter once and now there are five of me. I have never been more efficient or more tired."
  187. >
  188. > **A senior engineer, mass-produced** · Blorbo Labs, which does not exist
  189. > "Please stop merging at 4:55 on a Friday. Love, me."
  190. >
  191. > **Your future self** · reviewing the diff, via time machine
  192. > "Quack. (Translation: the locks are just `mkdir`. That is the whole trick.)"
  193. >
  194. > **A rubber duck** · unprompted
  195. > "At first I read every log line. Now I read the DONE lines. Soon I will read the headline of the DONE lines."
  196. >
  197. > **A vibe coder in transition** · fictional, like the rest of this section
  198. ## FAQ
  199. Questions, some answered. The first eight are real.
  200. **Why do the commands say `hyper`?** The plugin is named `hyper`; the repo and marketplace are `hyperdo`. Commands are namespaced by plugin.
  201. **Do I need git worktrees?** No. Isolation comes from disjoint file ownership and `mkdir` locks in one working tree. (`prod` mode does use a worktree per thread.)
  202. **A worker died and its thread is stuck on `doing`.** Run `/hyper:status` and tell it the worker is gone; it resets the thread to `todo` and removes the locks.
  203. **Can I edit `PLAN.md` by hand?** Yes. It is the source of truth and the lead and workers re-read it.
  204. **Does it test my code?** As much as `rigor` says. By default each thread runs only its own `check:`, and the lead runs one cheap whole-project check at the end. Passing checks print nothing; on failure you get the exit code, the first few error lines and a log path. Rerun with `-v`/`--verbose` or read `.hyper/logs/` for more.
  205. **What does it send where?** Hyperdo adds no network calls of its own. The agents talk to Claude as usual, and in `solo` mode workers `git push` to your `origin`. The installer only runs `claude plugin` commands against this directory.
  206. **Do I have to manage phases?** No. They are automatic and optional: the lead adds them only to long plans and files new threads into the right one.
  207. **How do I remove it?** `./uninstall.sh` removes `~/.claude/hyperdo`, the plugin and the marketplace. Per-project state stays; run `/hyper:clean` in each project for that.
  208. **Will it replace me?** *(joke)* No. Someone has to press Enter, and someone has to be blamed.
  209. **Is everything really 99% done?** *(joke)* Yes. This is normal.
  210. **Is this a real product?** *(real answer to a joke question)* The tool is real and the install steps work. The charts, the fake testimonials and Blorbo Labs are not.
  211. ## Contributing
  212. The whole system is Markdown plus two short shell scripts, so changes are easy to review.
  213. - Commands live in `plugins/hyper/skills/<name>/SKILL.md` (frontmatter `name` and `description`, then the instructions).
  214. - The worker protocol is `WORKER.md`; `install.sh` copies it to `~/.claude/hyperdo/`. Re-run `./install.sh` after changing it.
  215. - The command list is mirrored in `.claude-plugin/marketplace.json` and the `install.sh` echo line; update all three when adding a command.
  216. - Keep it minimal: fewer words in a skill, and no new moving parts without a strong reason.
  217. ## License
  218. MIT — see [LICENSE](LICENSE).
  219. ## Disclaimers
  220. **Plainly:** every chart, testimonial and company name in this README is made up, except the creator's quote, which is real. The commands, install steps and the facts about how Hyperdo works are real. No performance claim here is a measurement, and there are no real user numbers because we have not invented any.
  221. **Also plainly:** Literally zero seriousness was used in the creation of this tool, and I had the Flu... So... use at your own discretion.

Ratings and comments

Sign in to rate this skill.

Sign in

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