cpmux 0.1.0__tar.gz

cpmux-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: pip install pre-commit
+      - run: pre-commit run --all-files --show-diff-on-failure
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest -q
+
+  package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: pip install build twine
+      - run: python -m build
+      - run: twine check dist/*

cpmux-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,37 @@
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: pip install build twine
+      - run: python -m build
+      - run: twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

cpmux-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+# cpmux runtime state (worktrees, transcripts, run manifests)
+.cpmux/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+
+# OS / editors
+.DS_Store
+.idea/
+.vscode/

cpmux-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,25 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-added-large-files
+        args: ['--maxkb=2500']
+      - id: check-case-conflict
+      - id: check-docstring-first
+      - id: check-merge-conflict
+      - id: check-yaml
+      - id: detect-private-key
+      - id: trailing-whitespace
+      - id: requirements-txt-fixer
+  - repo: https://github.com/PyCQA/isort
+    rev: 5.13.2
+    hooks:
+      - id: isort
+  - repo: https://github.com/psf/black
+    rev: 24.10.0
+    hooks:
+      - id: black
+  - repo: https://github.com/PyCQA/flake8
+    rev: 7.1.1
+    hooks:
+      - id: flake8

cpmux-0.1.0/CHANGELOG.md

@@ -0,0 +1,74 @@
+# Changelog
+
+All notable changes to cpmux are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Pull requests opened by `cpmux up` now carry a title and description authored by the
+  session from the changes it actually made, following the target repository's
+  pull-request template when one exists. If a session produces none, cpmux falls back to
+  the item name and a short summary of the prompt.
+- `cpmux plan --voice` now shows a live transcript while you speak: a fast model streams
+  partial text during recording, and the configured model produces the accurate final
+  transcription when you stop.
+
+### Changed
+
+- `cpmux up` now runs in the background by default; pass `--foreground`/`-f` to stay
+  attached and watch inline.
+- Voice dictation now defaults to the `large-v3-turbo` model (was `base`) and enables
+  VAD filtering, substantially improving transcription accuracy (first use downloads
+  ~1.6 GB, cached afterward; override with `--transcribe-model`).
+- Voice plan synthesis now instructs the model to preserve every dictated detail instead
+  of producing a concise summary, so plans no longer drop tasks or constraints.
+
+### Fixed
+
+- Live views (`up --foreground`, `attach`) no longer corrupt the terminal when arrow
+  keys or other input are pressed: keystroke echo is suppressed while a live view renders.
+
+## [0.1.0]
+
+### Changed
+
+- Renamed the project from `cmux` to `cpmux` (the `cmux` name was taken on PyPI):
+  the command, package, `.cpmux/` state directory, `CPMUX_*` environment
+  variables, and the default `cpmux/{slug}` branch prefix all change accordingly.
+
+### Added
+
+- `cpmux rm --purge` to delete a run's on-disk history so it leaves `cpmux ls`.
+- Preflight validation that each item's `paths` exist in its worktree, failing
+  early with a clear error instead of a late `copilot` failure.
+- `branch_template` documented in the voice-plan schema so a spoken branch scope
+  maps to the branch, not `base`.
+
+### Fixed
+
+- A `--no-pr` item whose agent committed its own work now reports `done`
+  (previously `no changes`).
+- The dashboard follow-up now forwards each item's `env` overrides, matching
+  `cpmux send`.
+
+## [0.0.1]
+
+Initial release.
+
+### Added
+
+- Declarative, guided multiplexer for GitHub Copilot CLI agents: one YAML plan
+  (a shared system prompt plus a list of items) spawns one isolated headless
+  `copilot` session per item, each in its own git worktree and branch.
+- Commands: `init`, `up`, `plan`, `ls`, `attach`, `dash`, `logs`, `search`,
+  `enter`, `send`, `kill`, `down`, `rm`.
+- Interactive `dash` TUI, live `up` and `attach` monitoring, and `plan` for
+  composing a plan from an editor, text, speech (`--voice`), or an audio file.
+- On-device speech-to-text via faster-whisper behind the `voice` extra.
+
+[Unreleased]: https://github.com/gugarosa/cpmux/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/gugarosa/cpmux/compare/v0.0.1...v0.1.0
+[0.0.1]: https://github.com/gugarosa/cpmux/releases/tag/v0.0.1

cpmux-0.1.0/CONVENTIONS.md

@@ -0,0 +1,162 @@
+# cpmux — Conventions
+
+Rules and invariants for adding to or changing cpmux. cpmux adopts the **phitrain conventions**
+(microsoft/aifsdk `.github/rules/` R1–R18 and `phitrain/CONVENTIONS.md`) as its style
+rules. **Code defines behavior; this file lists the applicable rules.**
+
+For user-facing setup and usage see `README.md`.
+
+## Architecture invariants
+
+These invariants keep cpmux composable; do not violate them.
+
+- **One worktree per item.** Every item runs in its own `git worktree` on a unique
+  `cpmux/<slug>` branch off `origin/<base>`. Items never share a working tree.
+- **Agents are edit-only; the orchestrator ships.** Sessions run with `git push`
+  denied (`--deny-tool='shell(git push)'`). The orchestrator, never the agent,
+  commits the diff, pushes the branch, and opens exactly one draft PR per item.
+- **Monitor via JSONL, never PTY.** Session state is derived from
+  `copilot --output-format json` (a JSONL event stream), tee'd to disk. Do not
+  screen-scrape a terminal.
+- **Pre-assigned session ids.** The orchestrator assigns each session's
+  `--session-id` UUID up front, so a session is always addressable for status,
+  resume, and recovery.
+- **cpmux owns only `.cpmux/`.** copilot keeps its own transcripts and resumable
+  session store under `~/.copilot`; reuse it read-only rather than duplicating it.
+- **A run has one owner.** Its pid is recorded in `owner.json`: the foreground `up`
+  process, or the detached daemon. A live owner means the run is managed. A stale
+  owner (present but dead) marks a crash, so non-terminal sessions reconcile to a terminal
+  state instead of remaining "running" indefinitely.
+- **Config precedence is `item > defaults > built-in`.** Resolution happens once in
+  `Plan.resolve()`; downstream code consumes `ResolvedItem`, never re-merges.
+
+## Package structure
+
+Modules are grouped by domain. Shared foundation modules stay at the package root.
+
+```
+cpmux/
+  config.py  events.py  logging.py      foundation: config model, JSONL/status, logging
+  engine/    supervisor session daemon store interact   run lifecycle + state
+  vcs/       git pr                       git worktrees + PR automation
+  voice/     recorder transcriber synthesizer   speech → transcript → cpmux plan
+  ui/        cli dashboard search render  Typer commands, TUI, transcript rendering
+```
+
+- **Layering is one-directional:** `ui` → {`engine`, `voice`} → `vcs` → foundation. A layer
+  may import only the layers below it; foundation imports no subpackage. This keeps `engine`
+  headless without the TUI. Shared code moves to the lowest layer that needs it
+  (status-to-colour lives in `ui/render.py`
+  because only the UI reads it; the JSONL `event_data` unwrap lives in `events.py`
+  because the engine needs it too).
+- **A subpackage must be a cohesive domain** with a few focused modules,
+  not a thin split of one concern. Heavy or optional third-party deps (`sounddevice`,
+  `faster-whisper` behind the `voice` extra) are imported lazily in the function that
+  needs them to keep the core install and `--help` light.
+- **Absolute imports only**, and `__init__.py` stays empty apart from the header —
+  import from the module, not the package.
+- **Tests mirror source 1:1**, so `engine/store.py` is tested by
+  `tests/engine/test_store.py`. Shared fixtures live in `tests/conftest.py`.
+
+## `.cpmux/` layout
+
+Repo-local and gitignored. cpmux stores orchestration bookkeeping here; nothing here is committed.
+
+```
+.cpmux/
+  runs/<run_id>/
+    manifest.json                 resolved run config
+    sessions/<key>/
+      prompt.md                   the exact prompt sent to copilot
+      transcript.jsonl            raw tee of copilot --output-format json
+      session.json                per-session record (status, branch, PR...)
+      copilot-logs/               copilot's own --log-dir
+  worktrees/<run_id>/<key>/       one git worktree per item
+```
+
+## Code style
+
+Adopted from phitrain (rule ids in parentheses).
+
+- Python 3.12+ syntax. Use `X | None`, never `Optional[X]`. Use builtin generics
+  (`dict[str, Any]`, `list[str]`); import only `Any`, `Literal`, `Annotated`, … from
+  `typing`. ABCs (`Callable`, `Iterable`, …) come from `collections.abc`. (R2)
+- Every `.py` file starts with the two-line copyright/license header.
+- Imports are top-level and absolute (`from cpmux.x import y`). Order: stdlib →
+  third-party → local, blank-separated.
+- Public functions, classes, and their `__init__` carry Google-style docstrings
+  (single-sentence summary; one-line `Args:`/`Returns:`/`Raises:` entries). A regular
+  class keeps a one-line class summary and documents its constructor `Args:` on
+  `__init__`. Private helpers (`_name`) and framework-dispatched overrides (Textual
+  `compose`/`on_<event>`/lifecycle hooks) carry none. No semicolons or
+  `defaults to <X>` tails in entries. (R3, R13)
+- A docstring keeps one blank line before its closing `"""`, and one blank line
+  after the closing `"""` before the first statement or field.
+- Data classes (Pydantic models and `@dataclass`, which have no explicit `__init__`)
+  document every field in an `Attributes:` section, one line per field
+  (`name: what it holds.`).
+- Logging uses `get_logger(__name__)` from `cpmux.logging`; **never `print()` in
+  library code** (the CLI presentation layer uses Rich and `typer.echo`). Diagnostic
+  `logger.warning`/`logger.error` use a backticked offender and trailing period:
+  `` f"`name=value` <verb-phrase>." ``; `logger.info`/`logger.debug` stay plain. (R14)
+- Raised error messages use `` f"`<name>` <verb-phrase>[, but got <value>]." `` with a
+  trailing period and `is None`/`is True` prose. (R1)
+- Validation uses `if/raise` with a specific exception, never `assert`. Bare `except:`
+  is forbidden.
+- Comments explain **why**, not **what**: default to none, one-liner preference,
+  3-line hard cap, no banner/section separators, no trailing period. (R8)
+- Insert a single blank line at each phase transition in function bodies ≥ 12 LOC. (R11)
+- Inline first; extract a helper/constant/parameter only on a second call-site. (R16)
+- Double quotes for strings. Readable prose stays within 120 characters. (R9)
+
+**Deliberate divergence: config uses Pydantic v2, not `@dataclass`.** phitrain models
+config with `@dataclass` + `__post_init__` because it uses OmegaConf. cpmux's declarative
+YAML needs string→item coercion, discriminated unions,
+`${ENV}` interpolation, and precise validation errors, all idiomatic in Pydantic v2.
+The config models in `config.py` and on-disk records in `engine/store.py` are therefore
+Pydantic `BaseModel`s. Everything else follows phitrain.
+
+## CLI conventions (`ui/cli.py`)
+
+- One `command()` function per verb, aggregated on the Typer `app`.
+- Multi-word options use `--kebab-case` (e.g. `--dry-run`, `--transcribe-model`,
+  `--no-pr`); single-letter shortcuts are unique within a command.
+- Validate inputs with `if/raise <SpecificError>`; surface operational failures with
+  `logger.error(...)` followed by `raise typer.Exit(1)`, with no hand-rolled `"Error:"`
+  prefix, no `typer.echo(..., err=True)`.
+- Presentation (status tables, transcripts) uses Rich; raw machine output uses
+  `typer.echo`. Each `command()` carries a single-sentence docstring for `--help`.
+- Short-lived subprocesses use `subprocess.run(..., capture_output=True, text=True,
+  check=False)`; streaming/long-running children use `asyncio` subprocesses.
+
+## Tests
+
+- Tests mirror the source layout: `tests/<subpackage>/test_<module>.py`, with foundation
+  modules tested at the `tests/` root and shared fixtures in `tests/conftest.py`.
+- Test functions are named `test_<function_or_class_name>_<behavior>`: lead with the exact
+  function, method, or class under test (snake_cased, any leading underscore dropped), then
+  the behavior — e.g. `test_resolve_base_falls_back_to_head`,
+  `test_run_paths_resolve_under_run_dir`. They are plain functions with no docstrings or type
+  hints.
+- Asserts are bare `assert <expr>`, with no failure-message strings; the test name carries
+  the intent. (R15)
+
+## Tooling
+
+black + isort (`profile = black`) + flake8, all at line-length 120, wired through
+`.pre-commit-config.yaml`.
+
+```bash
+isort cpmux tests && black cpmux tests && flake8 cpmux tests
+pytest
+```
+
+## Status and roadmap
+
+- **Current:** foreground and detached (`--detach`) runs; `ls`/`attach` live monitor; an
+  interactive Textual `dash` (session list + live transcript + `/` search + `e` to drop into a
+  native `copilot --resume`); `enter`/`send` interaction; cross-session `search` (with `--fts`
+  over copilot's own index); `logs --follow`; `down`/`kill`/`rm`; per-item dev-server ports
+  (`port_base`); `depends_on` ordering; voice/text/audio plan composition; crash reconciliation
+  via the run owner.
+- **Remaining:** ACP transport for live permission prompts; optional remote `/delegate` mode.

cpmux-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gustavo de Rosa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cpmux-0.1.0/PKG-INFO

@@ -0,0 +1,248 @@
+Metadata-Version: 2.4
+Name: cpmux
+Version: 0.1.0
+Summary: Multiplexer for GitHub Copilot CLI agents
+Project-URL: Homepage, https://github.com/gugarosa/cpmux
+Project-URL: Repository, https://github.com/gugarosa/cpmux
+Author: Gustavo de Rosa
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,cli,copilot,multiplexer,orchestration,tmux,worktree
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Requires-Dist: click>=8.0
+Requires-Dist: pydantic>=2.5
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: textual>=0.80
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: voice
+Requires-Dist: faster-whisper>=1.0; extra == 'voice'
+Requires-Dist: sounddevice>=0.4; extra == 'voice'
+Description-Content-Type: text/markdown
+
+# cpmux
+
+**A declarative multiplexer for GitHub Copilot CLI agents: "tmuxinator for `copilot` sessions."**
+
+Write one YAML file with a shared system prompt and a task list. cpmux starts one headless
+`copilot` session per task, each in its own git worktree and branch, and opens a draft PR.
+Monitor and steer all sessions.
+
+## Install
+
+Requires macOS or Linux, Python ≥ 3.12, and the [`copilot`](https://docs.github.com/copilot/how-tos/copilot-cli),
+`git`, and `gh` CLIs on your `PATH`.
+
+```bash
+pip install git+https://github.com/gugarosa/cpmux
+```
+
+Or from source, for development:
+
+```bash
+git clone https://github.com/gugarosa/cpmux
+cd cpmux
+pip install -e .
+```
+
+## Quickstart
+
+From the root of the GitHub repository you want to change, create `cpmux.yml` (or run
+`cpmux init` for a starter):
+
+```yaml
+system: |
+  Make the smallest change that fully addresses the task.
+  Follow the repository's conventions and add or update tests.
+
+items:
+  - Fix the broken install link in the README
+  - name: pagination-regression
+    prompt: Add a regression test for the pagination helper.
+```
+
+Preview the plan, start the sessions in the background, and watch the run:
+
+```bash
+cpmux up --dry-run         # preview the resolved plan
+cpmux up --yes             # start the run in the background
+cpmux attach               # watch it (Ctrl-C stops watching, not the run)
+```
+
+By default, `cpmux up` starts the run in the background and opens one draft PR per item.
+Pass `--foreground` to stay attached and watch inline (Ctrl-C then stops the run).
+
+Each PR's title and description are written by the session itself from the changes it made,
+following the target repository's pull-request template when one exists. If a session
+doesn't produce one, cpmux falls back to the item name and prompt.
+
+## The cpmux file
+
+A file has a shared `system` prompt, run-wide `defaults`, and `items`. Each item is either a
+prompt string or a mapping:
+
+```yaml
+system: |
+  Make the smallest change that fully fixes the issue, follow the surrounding
+  conventions, and add or update a test.
+
+defaults:
+  model: gpt-5.5           # any `copilot --model` id
+  effort: medium           # none | minimal | low | medium | high | xhigh | max
+  permissions: edit        # readonly | edit | full (yolo)
+  base: main               # branch to fork from and open PRs against
+  remote: origin           # git remote to push branches and open PRs on
+  branch_template: cpmux/{slug}  # each item's branch name; {slug} or {id}, e.g. gderosa/{slug}
+  concurrency: 6           # max sessions running at once (1–64)
+  deps: symlink            # seed a worktree's node_modules: symlink | copy | install | skip
+  port_base: 3000          # give each item a unique port (3000, 3001, …) via $PORT
+  port_env: PORT           # rename the port variable (default $PORT)
+  pr:
+    draft: true
+    labels: [cpmux]
+
+items:
+  - Fix the flaky login test              # bare string → key is the slug "fix-the-flaky-login-test"
+  - Paginate the notifications list
+
+  - name: dark-mode-contrast              # mapping → key is the slug of `name`
+    prompt: Fix the dark-mode contrast on secondary buttons; it fails WCAG AA.
+    model: claude-opus-4.8
+    effort: high
+    paths: [src/components/buttons]
+    labels: [a11y]
+    depends_on: [fix-the-flaky-login-test]
+```
+
+Item mappings accept `prompt`, `name`, `id`, `model`, `effort`, `permissions`, `base`,
+`branch`, `labels`, `draft`, `paths`, `depends_on`, `env`, and `include_system`.
+
+The `pr` block also accepts `title_template` and `body_template` — the fallback title and body
+used when a session writes no `.cpmux-pr.md`; both expand `{name}`, `{slug}`, and `{prompt}`,
+while `branch_template` expands `{slug}` and `{id}`. `permissions` may be a bare preset or a
+mapping that extends one —
+`{preset: edit, allow: [...], deny: [...], add_dir: [...], allow_url: [...]}` — adding
+`copilot` tool and network rules. Only `full`/`yolo` let the agent run `git push` itself; the
+other presets keep push denied so cpmux owns delivery. An optional top-level `version` selects
+the schema (currently only `1`).
+
+An item's **key** is its `id` when set, otherwise a slug of its `name` or `prompt`. Pass keys
+to `enter`, `send`, `logs`, and `kill`; `cpmux ls` and `--dry-run` print them. Any string field
+expands `${VAR}` and `${VAR:-default}` from the environment. Set `include_system: false` to
+omit the shared prompt for an item.
+
+Set `port_base` when items run dev servers: each item gets `port_base + index` in its
+environment (as `$PORT`, or `port_env` to rename it), so parallel servers do not collide. An
+item's own `env` takes precedence, and `env` values reach the session's subprocess.
+
+## Commands
+
+Run-scoped commands accept `--run <id>` and default to the latest run.
+
+| Group | Command | What it does |
+|---|---|---|
+| **Create** | `cpmux init [FILE]` | Write a starter plan (defaults to `cpmux.yml`). Flag: `--force/-f`. |
+| | `cpmux plan [FILE]` | Compose a plan in your editor, or from text, speech, or audio. Flags: `--text`, `--voice`, `--audio` (mutually exclusive), `--transcribe-model`, `--model`, `--force/-f`, `--up`, `--pr/--no-pr`, `--detach/--foreground/-d`, `--yes/-y`. |
+| **Launch** | `cpmux up [FILE]` | Spawn one session per item (defaults to `cpmux.yml`). Flags: `--dry-run`, `--detach/--foreground/-d/-f` (background by default), `--concurrency/-j`, `--pr/--no-pr`, `--deps`, `--strip-github-token/--no-strip-github-token`, `--yes/-y`. |
+| **Monitor** | `cpmux ls` | Snapshot each item's status, elapsed time, and activity. |
+| | `cpmux attach` | Live, read-only monitor; reconnects to a background run (Ctrl-C to detach). |
+| | `cpmux dash` | Interactive TUI: session list, live transcript, search. |
+| | `cpmux logs KEY` | Print a transcript; `--follow/-f` to stream, `--raw` for the JSONL. |
+| | `cpmux search QUERY` | Search across transcripts; `--all` for every run, `--regex`, `--fts` to rank via Copilot's index. |
+| **Steer** | `cpmux enter KEY` | Drop into an interactive copilot session, resumed in place. |
+| | `cpmux send KEY "…"` | Append a follow-up turn and print the reply. |
+| | `cpmux kill KEY` | Stop one running session. Flag: `--yes/-y`. |
+| **Teardown** | `cpmux down` | Stop a run's background daemon and any live sessions. Flag: `--yes/-y`. |
+| | `cpmux rm` | Remove the run's git worktrees. Flags: `--yes/-y`, `--force/-f` (delete uncommitted work), `--purge` (also delete run history). |
+
+## Composing a plan
+
+Compose a cpmux file in your editor by default, or from text, speech, or audio:
+
+```bash
+cpmux plan issues.yml                    # compose in $EDITOR → cpmux file
+cpmux plan issues.yml --text "fix the flaky login test and paginate the notifications"
+cpmux plan issues.yml --voice            # record from the mic (Enter to stop) instead
+cpmux plan issues.yml --audio memo.wav   # transcribe an existing recording instead
+cpmux plan issues.yml --up               # generate and launch it
+```
+
+`cpmux plan` opens your `$EDITOR` to describe the work (or takes `--text`), then asks `copilot`
+to produce a validated cpmux file. Add `--up` to launch it. With `--voice` or `--audio`,
+[faster-whisper](https://github.com/SYSTRAN/faster-whisper) transcribes speech on-device.
+Audio stays local. `--voice` shows a live transcript as you speak (a fast model streams
+partials while recording; your chosen model produces the accurate final text on stop).
+
+The `cpmux[voice]` extra installs `sounddevice` and `faster-whisper`. `--text` and the editor
+need neither:
+
+```bash
+pip install "cpmux[voice] @ git+https://github.com/gugarosa/cpmux"
+brew install portaudio     # macOS only: sounddevice needs PortAudio
+```
+
+The default transcription model is `large-v3-turbo` (near-`large-v3` accuracy, much faster
+decoding). It downloads on first use (~1.6 GB) and is cached. Pick a lighter one with
+`--transcribe-model` (for example, `small`, `distil-large-v3`, or `base`); larger models are
+more accurate but slower on CPU.
+
+## How it works
+
+- **One item, one session.** Each task becomes a headless `copilot -p` run with a
+  pre-assigned `--session-id`.
+- **Separate worktrees.** Each session runs in its own `git worktree` on a `cpmux/<slug>`
+  branch off `origin/<base>`.
+- **cpmux owns delivery.** Sessions run with `git push` denied. cpmux commits each worktree and
+  opens one draft PR per item. With `--no-pr`, it commits locally and stops.
+- **JSONL monitoring.** cpmux reads copilot's `--output-format json` event stream and writes it
+  to disk. Runs continue after detach and can be reattached. Crashed sessions resolve to a
+  terminal state.
+
+```
+issues.yaml ──cpmux up──►  session  fix-login-test    → worktree ─ branch ─ draft PR
+   system:  …             session  paginate-list     → worktree ─ branch ─ draft PR
+   items:   … ───────────►session  dark-mode-contrast→ worktree ─ branch ─ draft PR
+                          session  …                    (parallel · isolated)
+                                    │
+                monitor and steer: cpmux attach · dash · ls · logs · search
+```
+
+## What a run leaves on disk
+
+cpmux writes under a gitignored `.cpmux/`:
+
+```
+.cpmux/
+  runs/<run_id>/
+    manifest.json               resolved run config
+    sessions/<key>/
+      prompt.md                 the exact prompt sent (system + item)
+      transcript.jsonl          raw tee of copilot --output-format json
+      session.json              per-session record (status, branch, PR url, …)
+      copilot-logs/             copilot's own --log-dir
+  worktrees/<run_id>/<key>/     one git worktree per item
+```
+
+## Examples
+
+See [`examples/minimal.yaml`](examples/minimal.yaml) and a twelve-issue frontend run
+in [`examples/frontend.yaml`](examples/frontend.yaml).
+
+## Development
+
+```bash
+pip install -e .
+pytest
+```
+
+Conventions, architecture invariants, and roadmap live in [`CONVENTIONS.md`](CONVENTIONS.md).