Personal software factory. Tasks in TODO.md → agents in cmux tabs.
Install
bun install bun link
Commands
meeseeks go # bind to current cmux workspace + watch TODO.md meeseeks up <prompt> # spawn one ad-hoc agent meeseeks hi <id> <msg> # send a message to a running agent meeseeks oi <id> <msg> # (agent-only) ask a peer a question, tagged with your id meeseeks ls # (agent-only) list other active agents in the factory meeseeks pr <url> # (agent-only) record the PR you just opened on your task line meeseeks no # close all agent surfaces and wipe state
Run meeseeks go from inside a terminal tab in the cmux workspace you want agents to spawn into — it binds to that workspace rather than creating a new one.
TODO.md lifecycle
Run meeseeks go in your project, then edit TODO.md:
- Add a task (
- [ ] do the thing) — spawns an agent in a new cmux tab. Meeseeks tags the line with the agent id, e.g.- [ ] ``meeseeks:ab12c3`` do the thing. - Add a group task (
- [ ] ``meeseeks:N`` pick a name, N between 2 and 6) — spawns N agents that collaborate on one task, sharing a worktree. The first id is the coordinator; it opens the discussion, commits, and opens the PR. The tag gets rewritten to`meeseeks:ab12c3+de45f6`once spawned. - Edit a tagged task's text — sends
Task updated: <new text>to all agents attached to the task. - Check a tagged task (
- [x]) or delete the line — closes every agent on the task.
All agents spawn into the cmux workspace where meeseeks go was started. The workspace's sidebar color + description track how many agents are working. Up to 6 agents run concurrently; extra tasks queue and surface as at capacity (N/6) — K task(s) waiting, processed in TODO.md order as slots free up.
Meeseeks pre-creates each agent's worktree at ../wt-<id> on branch meeseeks/<id> before spawning, and drops the shell inside it. Peers in a group task share the coordinator's worktree. Worktrees are left behind on completion — clean up with git worktree remove when you're done.
Inter-agent comms
Every agent gets MEESEEKS_AGENT_ID and MEESEEKS_FACTORY_CWD in its env. From inside an agent shell:
meeseeks ls— list other active agents and their tasks.meeseeks oi <id> <question>— deliversfrom <your-id>: <question>to the target agent's tab viacmux send. The target can reply the same way; the response lands as new input in your terminal.meeseeks pr <url>— rewrites your TODO.md task line to include the PR URL, which registers it with the comment poller.
Project options
Optional YAML front-matter in TODO.md defines commands to run alongside UI-flagged tasks:
--- devServer: bun run dev browser: http://localhost:3000 ---
devServer— command run in ameeseeks:<id> · dev-serverterminal pane, started lazily per ui-flagged agent from the agent's cwd.browser— URL opened in ameeseeks:<id> · browsercmux browser pane, alongside the same agent.
Flag a task with `meeseeks:ui` to request the layout — agent terminal on the left (full height), browser top-right, dev server bottom-right:
- [ ] `meeseeks:ui` add a settings page
Tasks without the flag spawn as a single tab in the factory pane (current behaviour).
GitHub PR subscriber
If an agent records a PR URL on its task line via meeseeks pr <url> (e.g. - [ ] `` meeseeks:ab12c3 `` build feature https://github.com/you/repo/pull/42), meeseeks polls that PR for new comments every 30s via gh api. On each new comment:
- Agent's cmux surface alive → comment delivered via
cmux send. - Surface gone → a reply agent is respawned in the factory workspace with the comment as context.
Comments authored by you (the gh CLI user) are ignored. Requires gh authenticated.
Factory floor
meeseeks go also serves a local dashboard at http://localhost:7667 (override with MEESEEKS_UI_PORT). Shows running agents, tracked PRs, and the parsed task list. Auto-refreshes every 3s.
State is tracked in .meeseeks/state.json.
Design docs
See design/ for the full spec — factory lifecycle, agent spawn flow, task queue semantics, message exchange, planned specialist agents + skills.