meeseeks

Personal software factory. Tasks in TODO.md → agents in cmux tabs.

Requires: bun, cmux, claude.

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> — delivers from <your-id>: <question> to the target agent's tab via cmux 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 a meeseeks:<id> · dev-server terminal pane, started lazily per ui-flagged agent from the agent's cwd.
• browser — URL opened in a meeseeks:<id> · browser cmux 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.