{"id":51329064,"url":"https://github.com/tnunamak/waspflow","last_synced_at":"2026-07-01T21:04:42.561Z","repository":{"id":365150137,"uuid":"1270612231","full_name":"tnunamak/waspflow","owner":"tnunamak","description":"Live orchestration for Claude and Codex coding agents in tmux","archived":false,"fork":false,"pushed_at":"2026-06-16T04:36:25.000Z","size":297,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-16T05:25:38.503Z","etag":null,"topics":["agent-orchestration","claude-code","codex","tmux"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tnunamak.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-06-15T22:14:17.000Z","updated_at":"2026-06-16T04:36:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tnunamak/waspflow","commit_stats":null,"previous_names":["tnunamak/waspflow"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/tnunamak/waspflow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tnunamak%2Fwaspflow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tnunamak%2Fwaspflow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tnunamak%2Fwaspflow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tnunamak%2Fwaspflow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tnunamak","download_url":"https://codeload.github.com/tnunamak/waspflow/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tnunamak%2Fwaspflow/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35022657,"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-07-01T02:00:05.325Z","response_time":130,"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":["agent-orchestration","claude-code","codex","tmux"],"created_at":"2026-07-01T21:04:41.830Z","updated_at":"2026-07-01T21:04:42.542Z","avatar_url":"https://github.com/tnunamak.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# waspflow\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/waspflow-hero.webp\" alt=\"waspflow agent workflow control room\" width=\"100%\"\u003e\n\u003c/p\u003e\n\nGive your main agent a live workflow for managing worker agents.\n\nWaspflow is an agent-operable control loop for Claude Code and Codex workers:\nspawn a worker, watch its live stream, steer it with another instruction,\npreserve the transcript and diff, and reap the lane deliberately. Humans can use\nthe same CLI directly; the deeper point is that an orchestrating agent gets a\nsmall, durable tool surface instead of fire-and-forget subprocesses and loose\nnotes.\n\nUse it when you want to:\n\n- let a main agent delegate work without losing control of the worker;\n- watch what a coding agent is doing before it finishes;\n- correct a worker mid-run;\n- run multiple workers in isolated git worktrees;\n- require a report, transcript, and diff instead of \"done, trust me\";\n- recover worker state after your main agent or terminal loses context.\n\n## First Run\n\n```bash\ngit clone https://github.com/tnunamak/waspflow ~/code/waspflow\n~/code/waspflow/install.sh\nwaspflow doctor\nwaspflow demo --provider codex\nwaspflow demo --provider codex --run\n```\n\nUse `--provider claude` if Claude Code is the agent CLI you have installed.\n\nYou need `tmux`, `jq`, `git`, `curl`, `uuidgen`, and at least one agent CLI:\n`codex` or `claude`. If something is missing, `waspflow doctor` tells you what\nto install. See [docs/prerequisites.md](docs/prerequisites.md) for links.\n\n## The Loop\n\nA lane is one worker and its saved state: prompt, terminal transcript, session,\nworking directory, git diff, optional report, and final result.\n\n```bash\n# Start a worker from any project directory.\nwaspflow spawn --provider codex --lane fixbug -- \\\n  \"Find and fix the off-by-one in src/pager.ts\"\n\n# Wait until the worker finishes its current turn.\nwaspflow wait fixbug\n\n# Read the tail of its pane.\nwaspflow peek fixbug\n\n# Give it another instruction in the same session.\nwaspflow revise fixbug -- \"Add a regression test too.\"\nwaspflow wait fixbug\n\n# Close the pane and finalize the lane state.\nwaspflow reap fixbug\n```\n\n`reap` is cleanup, not data loss. The lane record stays under\n`$WASPFLOW_HOME` so you can inspect what happened later.\n\n## Why Not Just Run Codex Or Claude Directly?\n\nDirect CLI sessions are great for one focused conversation. Waspflow adds a\nsmall workflow layer when a human or orchestrating agent needs workers to be\nobservable, steerable, resumable, and reviewable.\n\n| Need | Direct `codex` / `claude` | `waspflow` |\n|---|---|---|\n| Start a normal coding session | Yes | Yes |\n| Give a main agent stable worker-agent verbs | Shell out and hope | `spawn`, `wait`, `peek`, `revise`, `reap` |\n| Watch another agent while you keep working | Manual tmux setup | Built in |\n| Send a correction after launch | Same terminal only | `waspflow revise \u003clane\u003e` |\n| Run several workers without file collisions | Manual worktrees | `--isolate` |\n| Keep prompt, transcript, diff, and result together | Manual bookkeeping | Automatic lane artifacts |\n| Require a written report | Prompt convention | `--report` checked on `reap` |\n| Recover after your main agent loses context | Manual reconstruction | `waspflow list/status/peek` |\n\n## Isolated Worktrees\n\nUse `--isolate` when several workers may edit the same repo:\n\n```bash\nwaspflow spawn --provider claude --lane api --isolate -- \"Refactor the API client\"\nwaspflow spawn --provider codex  --lane ui  --isolate -- \"Tighten the settings page\"\n```\n\nEach lane gets a git worktree on branch `waspflow/\u003clane\u003e`. `reap` removes that\nworktree only if it is clean. Use `--keep-worktree` to keep it, or `--force` to\ndiscard it deliberately.\n\n## Require a Report\n\nPass `--report` when the worker must leave a written result:\n\n```bash\nwaspflow spawn --provider codex --lane audit --report findings.md -- \\\n  \"Audit auth.ts and write findings.md\"\nwaspflow wait audit\nwaspflow reap audit\n```\n\nOn `reap`, waspflow checks that the report exists and is substantial. If it is\nmissing, waspflow runs one recovery pass by resuming the session and asking the\nworker to reconstruct the report from the transcript and diff. If the report is\nstill missing, `reap` fails. You get the deliverable or a hard failure, not a\nfalse green.\n\n## Check the Project Before Launching More Workers\n\n`waspflow check` summarizes the project state that matters for agent work:\n\n- current git branch, dirty state, and upstream delta;\n- other git worktrees;\n- live, exited, or failed lanes for this project;\n- optional project rules from `.waspflow/config.json`.\n\n```bash\nwaspflow check\nwaspflow check --explain\nwaspflow check --no-fail\n```\n\nUse `--explain` when you want next steps for the risks it found.\n\n## For Larger Repos\n\nWaspflow works with no project config. If your repo has local rules, generate a\nsmall config instead of writing wrapper scripts:\n\n```bash\nwaspflow init --profile serious-repo\nwaspflow check --explain\n```\n\nProfiles are composable:\n\n```bash\nwaspflow init --profile serious-repo --profile openspec\nwaspflow init --profile serious-repo --profile live-stack-mutex\n```\n\nThe project supplies the facts: which files are blockers, which command checks\nmatter, which mutex file protects a live system. Waspflow supplies the common\nmachinery. See [docs/project-checks.md](docs/project-checks.md) for the full\nconfig shape.\n\n## Commands\n\n| Command | What it does |\n|---|---|\n| `spawn --provider \u003cclaude\\|codex\u003e --lane \u003cname\u003e [opts] -- \u003ctask\u003e` | Start a worker |\n| `demo --provider \u003cclaude\\|codex\u003e [--run]` | Show or run a safe first demo |\n| `wait \u003clane\u003e` | Wait until a worker finishes its current turn |\n| `peek \u003clane\u003e` | Show the tail of the worker pane or transcript |\n| `revise \u003clane\u003e -- \u003cmessage\u003e` | Send another instruction to the same session |\n| `reap \u003clane\u003e` | Close the pane, verify outputs, and finalize state |\n| `list` | List lanes |\n| `status \u003clane\u003e` | Show one lane's JSON state |\n| `attach \u003clane\u003e` | Attach your terminal to the worker pane |\n| `check [--explain]` | Check git/worktree/lane/project state |\n| `init --profile \u003cname\u003e` | Write `.waspflow/config.json` from reusable profiles |\n| `doctor` | Check local prerequisites and agent CLIs |\n\nUseful `spawn` options:\n\n- `--isolate` creates a git worktree for the lane.\n- `--report \u003cpath\u003e` requires a written deliverable before `reap` succeeds.\n- `--model \u003cid\u003e` selects a provider model.\n- `--effort \u003clow|medium|high|xhigh|max\u003e` passes reasoning effort where supported.\n- `--cwd \u003cdir\u003e` starts the worker in another directory.\n- `--arg \u003cflag\u003e` passes an extra flag to the underlying agent CLI.\n\n## What Waspflow Saves\n\nEvery lane writes to `$WASPFLOW_HOME/lanes/\u003clane\u003e/`:\n\n- `prompt.txt`\n- `transcript.log`\n- `state.json`\n- `git-status-before.txt`\n- `git-status-after.txt`\n- `git-diff.txt`\n\nGit captures are skipped, not errored, when the lane is not inside a git repo.\n\n## How `wait` Knows a Worker Is Done\n\nWaspflow does not scrape prompt glyphs. It reads each provider's session log:\n\n- Claude Code: idle when the last assistant event has `stop_reason: \"end_turn\"`.\n- Codex: idle when the latest rollout event is `task_complete`.\n\nIf the pane has exited, `revise` resumes the saved session headlessly:\n\n- Claude: `claude --resume \u003csession-id\u003e --print \"\u003cmessage\u003e\"`\n- Codex: `codex exec resume \u003csession-id\u003e \"\u003cmessage\u003e\" -o \u003cfile\u003e`\n\n## Environment\n\n| Var | Default | Purpose |\n|---|---|---|\n| `WASPFLOW_HOME` | `~/.local/state/waspflow` | Lane state and transcripts |\n| `WASPFLOW_TMUX_SESSION` | `waspflow` | tmux session that holds worker windows |\n| `WASPFLOW_CODEX_BACKEND_HEALTH_URL` | empty | Optional health check URL for proxy-routed Codex setups |\n| `CLAUDE_PROJECTS_DIR` | `~/.claude/projects` | Claude session logs |\n| `CODEX_SESSIONS_DIR` | `~/.codex/sessions` | Codex session logs |\n\n## Architecture\n\nWaspflow is shell around tmux plus provider adapters:\n\n- `bin/waspflow` routes CLI commands.\n- `lib/core.sh` owns lane state, tmux helpers, and provider dispatch.\n- `lib/providers/claude.sh` and `lib/providers/codex.sh` adapt each CLI.\n- `lib/worktree.sh` handles git worktree isolation.\n- `lib/project.sh` implements `init` and `check`.\n- `skill/SKILL.md` teaches an orchestrating agent how to use the CLI.\n\nAdding another provider means adding `lib/providers/\u003cname\u003e.sh` with the provider\ncontract functions.\n\n## Verify\n\n```bash\nscripts/verify.sh\n```\n\nThe verify script checks shell syntax, config initialization, policy profiles,\nmutex/blocker detection, `check --explain`, successful-reaped-lane filtering,\nand demo preview output without calling a model.\n\n## License\n\nApache-2.0. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftnunamak%2Fwaspflow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftnunamak%2Fwaspflow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftnunamak%2Fwaspflow/lists"}