{"id":48737554,"url":"https://github.com/promptromp/bouquet","last_synced_at":"2026-05-01T02:01:11.973Z","repository":{"id":345963177,"uuid":"1185773031","full_name":"promptromp/bouquet","owner":"promptromp","description":"bouquet is an orchestration layer for multi-agent coding.","archived":false,"fork":false,"pushed_at":"2026-04-30T22:15:42.000Z","size":1716,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-30T22:21:47.968Z","etag":null,"topics":["agentic-coding","agentic-engineering","claude-code","llm","tui"],"latest_commit_sha":null,"homepage":"https://promptromp.github.io/bouquet/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/promptromp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","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-03-18T23:39:47.000Z","updated_at":"2026-04-30T22:15:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/promptromp/bouquet","commit_stats":null,"previous_names":["promptromp/bouquet"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/promptromp/bouquet","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/promptromp%2Fbouquet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/promptromp%2Fbouquet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/promptromp%2Fbouquet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/promptromp%2Fbouquet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/promptromp","download_url":"https://codeload.github.com/promptromp/bouquet/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/promptromp%2Fbouquet/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32482460,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"online","status_checked_at":"2026-05-01T02:00:05.856Z","response_time":64,"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":["agentic-coding","agentic-engineering","claude-code","llm","tui"],"created_at":"2026-04-12T05:36:45.892Z","updated_at":"2026-05-01T02:01:11.965Z","avatar_url":"https://github.com/promptromp.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/logo.png\" alt=\"bouquet logo\" width=\"320\"\u003e\n\u003c/p\u003e\n\n# bouquet\n\n[![CI](https://github.com/promptromp/bouquet/actions/workflows/ci.yml/badge.svg)](https://github.com/promptromp/bouquet/actions/workflows/ci.yml)\n\n\u003e **Warning — Alpha Software**\n\u003e Bouquet is under active development. APIs, config format, and CLI behavior may change without notice. Use at your own risk.\n\nAn orchestration layer for **multi-agent coding** — multiplexing coding agents across git worktrees with isolated services, all in one tmux session.\n\n```bash\ncd my-project\nbouquet start              # TUI launches, create worktrees, agents spin up\n```\n\n### Key Features\n\n| | Feature | Details |\n|---|---|---|\n| 🌿 | **Git worktree isolation** | Each feature branch gets its own worktree, venv, and node_modules — no cross-contamination |\n| 🖥️ | **Multi-pane services** | Run API servers, workers, frontends alongside the agent with automatic port offsetting per worktree |\n| 🤖 | **Agent orchestration** | TUI in tmux window 0 to create, switch, and manage worktree-backed agent windows |\n| 📋 | **Task queue** | Define a backlog of tasks that get automatically delegated to worktrees — agents pick up work without manual intervention |\n| 🔧 | **Rich configuration** | Expressive `.bouquet.toml` with template expressions (`{{ 8000 + BOUQUET_WORKTREE_INDEX }}`), per-worktree variables, agent profiles, and multi-service layouts |\n| ⚡ | **Fast bootstrap** | CoW-clones `.venv`/`node_modules` (APFS), copies `.env` files, runs `uv sync`/`pnpm install` |\n| 🔌 | **Agent-agnostic** | Named profiles let you mix Claude, Aider, Codex, or any CLI agent — even different agents per worktree |\n\n---\n\n## Requirements\n\n- Python 3.14+\n- [tmux](https://github.com/tmux/tmux) (`brew install tmux`)\n- [GitHub CLI](https://cli.github.com/) (optional, `brew install gh` — enables PR links in TUI and GitHub Issues task backend)\n- [direnv](https://direnv.net/) (optional, `brew install direnv`)\n- Language package managers as needed (`uv`, `pnpm`)\n\n## Installation\n\n```bash\n# Run without installing\nuvx pybouquet --help\n\n# Or install via pip\npip install pybouquet\n\n# Or from source (development)\ngit clone https://github.com/promptromp/bouquet.git\ncd bouquet\nuv sync\n```\n\n---\n\n## Quick Start\n\n### 1. Initialize\n\n```bash\ncd /path/to/your/repo\nbouquet init\n```\n\nCreates a `.bouquet.toml` template. Edit it to configure your project.\n\n### 2. Start a session\n\n```bash\nbouquet start\n```\n\nThis will:\n1. Create a tmux session (`bouquet-\u003cproject-name\u003e`)\n2. Launch the orchestrator TUI in window 0\n3. Adopt any existing git worktrees\n4. Attach you to the session\n\nYou can also pass arguments explicitly:\n\n```bash\nbouquet start my-project --repo /path/to/repo --config /path/to/.bouquet.toml\n```\n\n### 3. Use the TUI\n\n| Key | Action |\n|---|---|\n| `N` | Create a new worktree (opens branch dialog with optional agent profile selector) |\n| `S` / `Enter` | Switch to the selected worktree's window |\n| `D` | Delete the selected worktree and its window |\n| `a` | Toggle auto-accept for selected worktree (auto-sends \"y\" at permission prompts) |\n| `A` | Toggle autopilot mode (auto-schedules tasks by dependency order) |\n| `P` | Send a prompt to selected or all agent terminal(s) via tmux send-keys |\n| `T` | Request a status summary from all agents (captures responses) |\n| `C` | Create a new task in the task queue |\n| `X` | Pick up the highlighted task (creates worktree and sends task to agent) |\n| `M` | Complete the highlighted task (optionally remove the associated worktree) |\n| `Backspace` | Delete the highlighted task from the queue |\n| `R` | Refresh the worktree list and task queue |\n| `Q` | Quit (with confirmation — kills the session) |\n\nWhen you create a worktree, bouquet will:\n- Create a git worktree with a new branch\n- Bootstrap the environment (copy `.env` files, CoW-clone `.venv`/`node_modules`)\n- Open a new tmux window with service panes (if configured)\n- Launch the agent (e.g. `claude`) in pane 0\n\nSwitch back to the orchestrator: `Ctrl-b 0`.\n\n### 4. Stop\n\n```bash\nbouquet stop\n```\n\nCleans up all managed worktrees, resets any in-progress tasks back to open, kills the tmux session, and removes state.\n\n---\n\n## Services\n\nRun dev servers alongside the agent in each worktree window. Define them in `.bouquet.toml`:\n\n```toml\n[[services]]\nname = \"api\"\ncommand = \"uv run uvicorn app.main:app --reload --port {{ 8000 + BOUQUET_WORKTREE_INDEX }}\"\n\n[[services]]\nname = \"frontend\"\ncommand = \"npm run dev -- --port {{ 3000 + BOUQUET_WORKTREE_INDEX }}\"\n\n[tmux]\nlayout = \"main-vertical\"\n```\n\nEach worktree gets a unique index (1, 2, 3, ...) so services bind to different ports automatically.\n\n### Template Variables\n\n| Variable | Type | Example |\n|---|---|---|\n| `BOUQUET_WORKTREE_INDEX` | int | `1`, `2`, `3` |\n| `BOUQUET_WORKTREE_BRANCH` | str | `feature/auth` |\n| `BOUQUET_WORKTREE_PATH` | str | `/path/to/.bouquet-worktrees/feature-auth` |\n| `BOUQUET_PROJECT_NAME` | str | `my-project` |\n\nArithmetic supported: `{{ 8000 + BOUQUET_WORKTREE_INDEX }}` → `8001`.\n\nThe same template variables are also available in `[bootstrap]` `setup_commands`, `post_deps_commands`, and `teardown_commands` — both as `{{ … }}` placeholders and as plain shell env vars (`$BOUQUET_WORKTREE_INDEX`, etc.) — so setup/teardown scripts can provision and reclaim per-worktree resources (databases, queues, …) without external coordination.\n\nNo services defined = single pane with just the agent (backward compatible).\n\n### Bootstrap hooks: `setup_commands` vs `post_deps_commands` vs `teardown_commands`\n\nThe three `[bootstrap]` hook lists run at different points in the worktree lifecycle:\n\n| Hook | When | On failure | Typical use |\n|---|---|---|---|\n| `setup_commands` | **Before** `python_deps_command` / `node_deps_command` | **Loud** — raises `SetupCommandsError`, worktree → `ERROR` | private-registry auth (CodeArtifact tokens), provisioning per-worktree DBs / queues |\n| `post_deps_commands` | **After** deps install, before `direnv_allow` (so `.venv` / `node_modules` exist) | **Loud** — same as setup_commands | `uv run migrate upgrade head`, asset compilation, anything that needs the project's tooling |\n| `teardown_commands` | **Before** tmux window kill + git worktree removal (so the on-disk checkout is still reachable) | **Best-effort** — failures logged, cleanup proceeds | reclaiming external per-worktree resources at remove time (drop DBs, delete queues) |\n\n`setup_commands` and `post_deps_commands` also have **env-capture**: any `export FOO=bar` lines in the user's commands are captured and propagated into both subsequent install commands and the tmux session, so service panes inherit them.\n\nSee [docs/configuration.md](docs/configuration.md#bootstrap) for the full reference.\n\n---\n\n## Agent Profiles\n\nNamed agent configurations so you can switch between Claude, Aider, Codex, etc. per worktree:\n\n```toml\n[agent]\ncommand = \"claude\"\ndefault_profile = \"claude\"\n\n[[agent.profiles]]\nname = \"claude\"\ncommand = \"claude\"\n\n[[agent.profiles]]\nname = \"aider\"\ncommand = \"aider\"\nargs = [\"--model\", \"claude-sonnet-4-20250514\"]\n```\n\nWhen profiles are defined, the TUI's new-worktree dialog shows a profile selector. If no profiles are defined, the top-level `command`/`args` are used (backward compatible).\n\n---\n\n## Activity Detection\n\nBouquet polls each agent's tmux pane every 2 seconds to infer real-time status:\n\n| Status | Meaning |\n|---|---|\n| **● running** (green) | Agent output is actively changing |\n| **◆ waiting** (yellow) | Agent output stopped and a permission prompt was detected |\n| **○ idle** (dim) | Agent output hasn't changed for several polls |\n\nThis replaces the static \"active\" status with live feedback. The TUI table updates automatically.\n\n---\n\n## Task Queue\n\nDefine a backlog of tasks that agents pick up automatically. Two backends are supported:\n\n### Local (SQLite) — default\n\nTasks are stored in `~/.local/state/bouquet/\u003cproject\u003e.tasks.db`. No external dependencies.\n\n```toml\n[task_queue]\nbackend = \"local\"\nauto_branch_prefix = \"task/\"\n```\n\n### GitHub Issues\n\nUses your repo's GitHub Issues as the task source. Requires `gh` CLI authenticated.\n\n```toml\n[task_queue]\nbackend = \"github\"\nlabel_filter = \"bouquet\"     # only issues with this label appear as tasks\nauto_branch_prefix = \"task/\"\n```\n\n**Status mapping:** OPEN = open issue, IN_PROGRESS = open issue + `in-progress` label, DONE = closed issue.\n\n### Task workflow\n\n1. **Create** (`c`) — opens a dialog to create a task with an optional parent dependency\n2. **Pick up** (`x`) — creates a worktree from the task, marks it in-progress, and sends the task description to the agent\n3. **Complete** (`m`) — marks the task as done, optionally removes the associated worktree\n4. **Reconciliation** — on startup, tasks stuck as in-progress (from a crash or quit) are automatically reset to open if their worktree no longer exists\n\n### Task Dependencies\n\nTasks can declare a parent dependency, forming a DAG. A task with an unsatisfied dependency shows as **blocked** in the queue and cannot be picked up until its parent is done. Cycles are rejected at creation time.\n\n### Autopilot\n\nPress `A` to toggle autopilot mode. When active, bouquet automatically:\n\n- Picks up tasks whose dependencies are satisfied (or have none)\n- Runs up to `max_autopilot_concurrency` tasks in parallel (default 3)\n- Enables auto-accept on all autopilot-created worktrees\n- Auto-completes tasks when their agent goes idle (~10 seconds)\n- Cascades: completing a parent unblocks its children for the next scheduling cycle\n\n```toml\n[task_queue]\nmax_autopilot_concurrency = 3    # max parallel worktrees\nautopilot_auto_complete = true   # auto-complete IDLE tasks\n```\n\n---\n\n### Pane Layout\n\nWith `layout = \"main-vertical\"` and two services:\n\n```\n┌──────────────────┬────────────┐\n│                  │   api      │\n│   agent (claude) ├────────────┤\n│                  │  frontend  │\n└──────────────────┴────────────┘\n```\n\n---\n\n## Logs \u0026 Troubleshooting\n\nBouquet writes a rotating log file to `~/.local/state/bouquet/\u003cproject\u003e.log` (5 MB × 3 backups). `bouquet start` prints the path to stderr on launch.\n\nWhen a worktree creation fails — most often because a `setup_commands` or `post_deps_commands` step exited non-zero — the TUI shows a terse toast (`Error creating worktree: …`) but the captured stdout and stderr from your bash commands land in the log file, along with the phase name (`setup_commands` vs `post_deps_commands`), cwd, and exit code. Tail it to debug:\n\n```sh\ntail -f ~/.local/state/bouquet/\u003cproject\u003e.log\n```\n\nThe `SetupCommandsError` raised on failure includes the log file path in its message, so the toast will point you there directly.\n\n`teardown_commands` failures are best-effort and don't block worktree removal — they log a `WARNING`-level line in the same log file, so check there if a worktree was removed but external resources weren't reclaimed.\n\nPass `--log-level=DEBUG` to `bouquet start` for more verbose output (e.g. each rendered `setup_commands` / `post_deps_commands` / `teardown_commands` line):\n\n```sh\nbouquet start --log-level=DEBUG\n```\n\n---\n\n## Architecture\n\n```\nThe Conceptual Stack\n┌─────────────────────────────────────────┐\n│         Orchestration Layer             │  ← TUI, agent coordination, task queue\n├─────────────────────────────────────────┤\n│         Session / Mux Layer             │  ← tmux sessions, windows, panes\n├─────────────────────────────────────────┤\n│         Isolation Layer                 │  ← git worktrees + env isolation\n├─────────────────────────────────────────┤\n│         Environment Layer               │  ← venv/node_modules/env vars\n└─────────────────────────────────────────┘\n```\n\n---\n\n## Related Projects\n\nBouquet draws inspiration from and complements several tools in the multi-agent coding space:\n\n- **[claude-squad](https://github.com/smtg-ai/claude-squad)** — A Go-based TUI for managing multiple Claude Code instances in parallel. Claude-squad focuses on running agents side-by-side with a clean terminal UI. Bouquet goes further with declarative multi-service layouts (API servers, frontends, workers per worktree), a rich template-based configuration language with per-worktree variable expansion, and a task queue for automatic work delegation across agents.\n\n- **[ruflo](https://github.com/ruvnet/ruflo)** — A Rust-based agentic workflow orchestrator with a focus on DAG-based task execution and CI/CD integration. Ruflo takes a pipeline-oriented approach to agent coordination, while bouquet is designed around the developer's local workflow — git worktrees, tmux sessions, and interactive TUI management with live activity detection.\n\n- **[Claude Code Agent Teams](https://code.claude.com/docs/en/agent-teams)** — Anthropic's experimental built-in feature for coordinating multiple Claude Code agents. Agent Teams operates within the Claude Code runtime itself. Bouquet is agent-agnostic (works with Claude, Aider, Codex, or any CLI tool), provides full control over environment isolation, service orchestration, and configuration through `.bouquet.toml`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpromptromp%2Fbouquet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpromptromp%2Fbouquet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpromptromp%2Fbouquet/lists"}