@compozy/cli 0.1.11 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +150 -130
  2. package/package.json +19 -19
package/README.md CHANGED
@@ -86,7 +86,7 @@ compozy ext enable cy-idea-factory
86
86
  compozy setup
87
87
  ```
88
88
 
89
- Execution runtimes are separate from skill installation. To run `compozy exec`, `compozy start`, or `compozy fix-reviews`, install an ACP-capable runtime or adapter on `PATH` for the `--ide` you choose:
89
+ Execution runtimes are separate from skill installation. To run `compozy exec`, `compozy tasks run`, or `compozy reviews fix`, install an ACP-capable runtime or adapter on `PATH` for the `--ide` you choose:
90
90
 
91
91
  | Runtime | `--ide` flag | Expected ACP command |
92
92
  | ------------------ | -------------- | -------------------------------- |
@@ -99,19 +99,27 @@ Execution runtimes are separate from skill installation. To run `compozy exec`,
99
99
  | pi ACP | `pi` | `pi-acp` |
100
100
  | Gemini CLI | `gemini` | `gemini --acp` |
101
101
 
102
- When the direct ACP command is not installed, Compozy can also fall back to supported launchers such as `npx @zed-industries/codex-acp` when the launcher is available locally.
102
+ When the direct ACP command is not installed, Compozy can also fall back to supported launchers such as `npx @zed-industries/codex-acp` when the launcher is available locally. Codex defaults to `gpt-5.5`; using that model with a local `codex-acp` binary requires `@zed-industries/codex-acp >= 0.12.0`. Update with `npm install -g @zed-industries/codex-acp@latest`, or explicitly choose a model supported by your installed adapter.
103
103
 
104
104
  ## 🔄 How It Works
105
105
 
106
106
  <div align="center">
107
- <img src="imgs/how-it-works-flow.png" alt="Compozy workflow from setup to ship with markdown artifacts at each step" width="100%">
107
+ <img src="imgs/how-it-works-flow.png" alt="Compozy daemon-first workflow showing workspace artifacts, daemon runtime, and persisted run state" width="100%">
108
108
  </div>
109
109
 
110
110
  Workflow artifacts stay in `.compozy/tasks/<name>/`. These are the PRDs, TechSpecs, ADRs, tasks, reviews, and memory files that you read and edit between steps.
111
111
 
112
- `compozy start` and `compozy fix-reviews` write runtime artifacts under `.compozy/runs/<run-id>/`. `compozy exec` is ephemeral by default and only writes resumable artifacts when `--persist` is enabled.
112
+ The daemon owns runtime state under `~/.compozy/`. Daemon-managed task runs, review-fix runs, and persisted exec sessions allocate `~/.compozy/runs/<run-id>/`, while attach and watch clients reconnect through daemon snapshots and streams instead of reading workspace-local run files directly.
113
113
 
114
- Task and review issue files use YAML frontmatter for parseable metadata such as `status`, `title`, `type`, `severity`, and `provider_ref`. Task workflow `_meta.md` files can be refreshed explicitly with `compozy sync`. Fully completed workflows can be moved out of the active task root with `compozy archive`. If you have an older project with XML-tagged artifacts, run `compozy migrate` once before using `start` or `fix-reviews`.
114
+ Task and review issue files use YAML frontmatter for parseable metadata such as `status`, `title`, `type`, `severity`, and `provider_ref`. `compozy sync` now reconciles authored workflow artifacts into the daemon `global.db` catalog and performs one-time cleanup for legacy generated `_meta.md` / `_tasks.md` artifacts when they are encountered. `compozy archive` moves completed workflows only after synced daemon state says they are eligible. If you have an older project with XML-tagged artifacts, run `compozy migrate` once before using daemon-backed workflow commands.
115
+
116
+ ### Daemon Runtime Model
117
+
118
+ - `compozy daemon start|status|stop` manages the home-scoped daemon lifecycle. `daemon start` is idempotent, and task/review/exec commands auto-start the daemon when needed.
119
+ - `compozy workspaces list|show|register|unregister|resolve` exposes the daemon workspace registry. Workspaces are also lazily registered when you run daemon-backed commands inside them.
120
+ - `compozy tasks run <slug>` is the canonical workflow runner. In interactive terminals it attaches to the TUI by default; in non-interactive environments it falls back to streaming. Use `--ui`, `--stream`, `--detach`, or `--attach` to override that behavior.
121
+ - `compozy runs attach <run-id>` restores the interactive TUI for an existing daemon-managed run, while `compozy runs watch <run-id>` streams textual observation from the same snapshot-plus-stream transport.
122
+ - `compozy reviews fetch|list|show|fix` is the canonical review command family.
115
123
 
116
124
  ### Task Schema v2
117
125
 
@@ -120,7 +128,7 @@ Task files now use the v2 frontmatter shape: `status`, `title`, `type`, `complex
120
128
  ```md
121
129
  ---
122
130
  status: pending
123
- title: Add validate-tasks preflight to start
131
+ title: Add task validation preflight to tasks run
124
132
  type: backend
125
133
  complexity: medium
126
134
  dependencies:
@@ -128,21 +136,21 @@ dependencies:
128
136
  ---
129
137
  ```
130
138
 
131
- Validate task files at any time with `compozy validate-tasks --name <feature>`. `compozy start` runs the same preflight automatically; use `--skip-validation` only when tasks were validated elsewhere, or `--force` to continue after validation failures in non-interactive runs.
139
+ Validate task files at any time with `compozy tasks validate --name <feature>`. `compozy tasks run <feature>` runs the same preflight automatically; use `--skip-validation` only when tasks were validated elsewhere, or `--force` to continue after validation failures in non-interactive runs.
132
140
 
133
- ## ⚙️ Workspace Config
141
+ ## ⚙️ Config Files
134
142
 
135
- Compozy can load project defaults from `.compozy/config.toml`.
143
+ Compozy can load global defaults from `~/.compozy/config.toml` and override them per workspace with `.compozy/config.toml`.
136
144
 
137
145
  - The CLI discovers the nearest `.compozy/` directory by walking upward from the current working directory.
138
- - If `.compozy/config.toml` exists, Compozy loads it once at command startup.
139
- - Interactive forms for `compozy start`, `compozy fix-reviews`, and `compozy fetch-reviews` are prefilled from the resolved config.
146
+ - If `~/.compozy/config.toml` exists, Compozy loads it once at command startup.
147
+ - If `.compozy/config.toml` exists in the resolved workspace, it overrides the global config field by field.
140
148
  - Explicit CLI flags always win over config values.
141
149
 
142
150
  Precedence is:
143
151
 
144
152
  ```text
145
- explicit flags > command section > [defaults] > built-in defaults
153
+ explicit flags > workspace command section > workspace [defaults] > global command section > global [defaults] > built-in defaults
146
154
  ```
147
155
 
148
156
  Example:
@@ -150,25 +158,25 @@ Example:
150
158
  ```toml
151
159
  [defaults]
152
160
  ide = "codex"
153
- model = "gpt-5.4"
161
+ model = "gpt-5.5"
154
162
  reasoning_effort = "medium"
155
163
  access_mode = "full"
156
164
  timeout = "10m"
157
165
  tail_lines = 0
158
166
  add_dirs = ["../shared"]
159
167
  auto_commit = false
160
- max_retries = 0
168
+ max_retries = 2
161
169
  retry_backoff_multiplier = 1.5
162
170
 
163
- [start]
171
+ [tasks]
172
+ types = ["frontend", "backend", "docs", "test", "infra", "refactor", "chore", "bugfix"]
173
+
174
+ [tasks.run]
164
175
  include_completed = false
165
176
 
166
177
  [exec]
167
178
  output_format = "text"
168
179
 
169
- [tasks]
170
- types = ["frontend", "backend", "docs", "test", "infra", "refactor", "chore", "bugfix"]
171
-
172
180
  [fix_reviews]
173
181
  concurrent = 2
174
182
  batch_size = 3
@@ -176,23 +184,27 @@ include_resolved = false
176
184
 
177
185
  [fetch_reviews]
178
186
  provider = "coderabbit"
187
+ nitpicks = false
179
188
  ```
180
189
 
181
190
  Supported sections:
182
191
 
183
192
  - `[defaults]` for shared execution defaults such as `ide`, `model`, `reasoning_effort`, `access_mode`, `timeout`, `tail_lines`, `add_dirs`, `auto_commit`, `max_retries`, and `retry_backoff_multiplier`
184
193
  - `[exec]` for `output_format` plus exec-specific runtime overrides such as `ide`, `model`, `reasoning_effort`, `access_mode`, `timeout`, `tail_lines`, `add_dirs`, `max_retries`, and `retry_backoff_multiplier`
185
- - `[start]` for `include_completed`
186
- - `[tasks]` for the allowed task `type` list used by `cy-create-tasks` and `compozy validate-tasks`
194
+ - `[tasks]` for the allowed task `type` list used by `cy-create-tasks` and `compozy tasks validate`
195
+ - `[tasks.run]` for workflow-run defaults used by `compozy tasks run`, such as `include_completed`
187
196
  - `[fix_reviews]` for `concurrent`, `batch_size`, and `include_resolved`
188
- - `[fetch_reviews]` for `provider`
197
+ - `[fetch_reviews]` for `provider` and `nitpicks` (controls CodeRabbit review-body comments; default is enabled when unset)
198
+ - `[sound]` for optional run-completion audio presets or absolute file paths
189
199
 
190
200
  Notes:
191
201
 
192
- - `.compozy/config.toml` is optional. If it is absent, Compozy keeps the current built-in defaults.
202
+ - Both `~/.compozy/config.toml` and `.compozy/config.toml` are optional. If both are absent, Compozy keeps the current built-in defaults.
193
203
  - `.compozy/tasks` remains the fixed workflow root in this version; the config file does not change the workflow root path.
194
204
  - Unknown keys and invalid value types are rejected during config loading.
195
- - `max_retries` applies to execution-stage ACP failures and inactivity timeouts for `compozy exec`, `compozy start`, and `compozy fix-reviews`.
205
+ - Relative `add_dirs` are resolved against the owning config scope: the user home directory for `~/.compozy/config.toml` and the workspace root for `.compozy/config.toml`.
206
+ - `max_retries` applies to execution-stage ACP failures and inactivity timeouts for `compozy exec`, `compozy tasks run`, and `compozy reviews fix`.
207
+ - Built-in CLI defaults retry timed-out or transient ACP failures twice; set `max_retries = 0` or pass `--max-retries 0` to opt out.
196
208
  - `retry_backoff_multiplier` only increases the next attempt timeout; retries restart immediately and do not add a sleep delay.
197
209
 
198
210
  ## Reusable Agents
@@ -222,7 +234,7 @@ compozy exec --agent reviewer "Review the staged changes"
222
234
  Runtime precedence for `compozy exec --agent ...` is:
223
235
 
224
236
  ```text
225
- explicit CLI flags > AGENT.md runtime defaults > .compozy/config.toml > built-in defaults
237
+ explicit CLI flags > AGENT.md runtime defaults > workspace/global config > built-in defaults
226
238
  ```
227
239
 
228
240
  `mcp.json` is only for agent-local MCP servers. The reserved Compozy MCP server is also named `compozy`, but it is injected by the host and must not appear in `mcp.json`. That reserved server exists only to expose host-owned tools such as `run_agent`. Child agent runs receive the reserved `compozy` server plus the child agent's own `mcp.json`; they do not inherit the parent agent's local MCP servers.
@@ -273,7 +285,7 @@ Extensions are discovered from three scopes with workspace > user > bundled prec
273
285
 
274
286
  - [Extension author guide](.compozy/docs/extensibility/index.md)
275
287
  - [Architecture overview](.compozy/docs/extensibility/architecture.md)
276
- - [Hook reference](.compozy/docs/extensibility/hook-reference.md) -- 28 hooks across 6 pipeline phases
288
+ - [Hook reference](.compozy/docs/extensibility/hook-reference.md) -- 32 hooks across 6 pipeline phases
277
289
  - [Host API reference](.compozy/docs/extensibility/host-api-reference.md) -- 11 typed host methods
278
290
  - [Capability reference](.compozy/docs/extensibility/capability-reference.md) -- 19 capability grants
279
291
  - [Trust and enablement](.compozy/docs/extensibility/trust-and-enablement.md)
@@ -303,23 +315,24 @@ Output modes:
303
315
  - `--format text` is headless by default and writes only the final assistant response to stdout
304
316
  - `--format json` streams the lean JSONL contract to stdout and filters ACP metadata that is mostly useful for debugging
305
317
  - `--format raw-json` streams the full raw JSONL event trace to stdout
306
- - when `--persist` is enabled, `.compozy/runs/<run-id>/events.jsonl` always stores the full raw event stream regardless of the selected stdout format
318
+ - when `--persist` is enabled, `~/.compozy/runs/<run-id>/events.jsonl` always stores the full raw event stream regardless of the selected stdout format
307
319
  - operational ACP/runtime logs stay silent by default; use `--verbose` when you want lifecycle logs on stderr
308
320
  - `--tui` opts back into the Bubble Tea interface for interactive inspection
309
- - `--persist` stores a resumable conversation under `.compozy/runs/<run-id>/`
321
+ - `--persist` stores a resumable conversation under `~/.compozy/runs/<run-id>/`
310
322
  - `--run-id` loads a previously persisted ACP session and appends a new turn
311
323
 
312
324
  Persisted `exec` runs use this layout:
313
325
 
314
326
  ```text
315
- .compozy/runs/<run-id>/run.json
316
- .compozy/runs/<run-id>/events.jsonl
317
- .compozy/runs/<run-id>/turns/0001/prompt.md
318
- .compozy/runs/<run-id>/turns/0001/response.txt
319
- .compozy/runs/<run-id>/turns/0001/result.json
327
+ ~/.compozy/runs/<run-id>/run.db
328
+ ~/.compozy/runs/<run-id>/run.json
329
+ ~/.compozy/runs/<run-id>/events.jsonl
330
+ ~/.compozy/runs/<run-id>/turns/0001/prompt.md
331
+ ~/.compozy/runs/<run-id>/turns/0001/response.txt
332
+ ~/.compozy/runs/<run-id>/turns/0001/result.json
320
333
  ```
321
334
 
322
- `compozy exec` uses the same config merge rule as the rest of the CLI: `flags > [exec] > [defaults] > built-in defaults`.
335
+ `compozy exec` uses the same config merge rule as the rest of the CLI: `flags > workspace [exec] > workspace [defaults] > global [exec] > global [defaults] > built-in defaults`.
323
336
 
324
337
  ## 🚀 Quick Start
325
338
 
@@ -332,7 +345,7 @@ compozy setup
332
345
  ```
333
346
 
334
347
  Auto-detects installed agents, copies (or symlinks) core skills into their configuration directories, and installs setup assets shipped by enabled extensions.
335
- `compozy start` and `compozy fix-reviews` now verify that bundled Compozy skills are installed for the selected agent before running. Missing installs block the run, and outdated installs prompt for refresh in interactive terminals.
348
+ `compozy tasks run` and `compozy reviews fix` now verify that bundled Compozy skills are installed for the selected agent before running. Missing installs block the run, and outdated installs prompt for refresh in interactive terminals.
336
349
 
337
350
  ### 2. (Optional) Create an Issue
338
351
 
@@ -375,16 +388,16 @@ Reads your PRD, explores the codebase architecture, asks technical clarification
375
388
  ```
376
389
 
377
390
  Analyzes both documents, explores your codebase for relevant files and patterns, produces individually executable task files with status tracking, context, and acceptance criteria.
378
- Generated task files use task schema v2 (`status`, `title`, `type`, `complexity`, `dependencies`). Validate them any time with `compozy validate-tasks --name user-auth`.
391
+ Generated task files use task schema v2 (`status`, `title`, `type`, `complexity`, `dependencies`). Validate them any time with `compozy tasks validate --name user-auth`.
379
392
 
380
393
  ### 6. Execute tasks
381
394
 
382
395
  ```bash
383
- compozy start --name user-auth --ide claude
396
+ compozy tasks run user-auth --ide claude
384
397
  ```
385
398
 
386
- Each pending task is processed sequentially — the agent reads the spec, implements the code, validates it, and updates the task status. Use `--dry-run` to preview prompts without executing.
387
- `compozy start` validates task metadata before execution. Use `--skip-validation` when validation already ran elsewhere, or `--force` to continue after validation failures in non-interactive environments.
399
+ Each pending task is processed sequentially through the shared daemon — the agent reads the spec, implements the code, validates it, and updates the task status. Use `--dry-run` to preview prompts without executing.
400
+ `compozy tasks run` validates task metadata before execution. Use `--skip-validation` when validation already ran elsewhere, or `--force` to continue after validation failures in non-interactive environments.
388
401
 
389
402
  ### 7. Review
390
403
 
@@ -397,7 +410,7 @@ Each pending task is processed sequentially — the agent reads the spec, implem
397
410
  **Option B** — Fetch from an external provider:
398
411
 
399
412
  ```bash
400
- compozy fetch-reviews --provider coderabbit --pr 42 --name user-auth
413
+ compozy reviews fetch user-auth --provider coderabbit --pr 42
401
414
  ```
402
415
 
403
416
  Both produce the same output: `.compozy/tasks/user-auth/reviews-001/issue_*.md`
@@ -405,7 +418,7 @@ Both produce the same output: `.compozy/tasks/user-auth/reviews-001/issue_*.md`
405
418
  ### 8. Fix review issues
406
419
 
407
420
  ```bash
408
- compozy fix-reviews --name user-auth --ide claude --concurrent 2 --batch-size 3
421
+ compozy reviews fix user-auth --ide claude --concurrent 2 --batch-size 3
409
422
  ```
410
423
 
411
424
  Agents triage each issue as valid or invalid, implement fixes for valid issues, and update statuses. Provider threads are resolved automatically.
@@ -466,11 +479,11 @@ Every task execution automatically bootstraps two markdown files inside `.compoz
466
479
 
467
480
  **No duplication.** Memory files don't copy what's already in the repo, git history, PRD, or task specs. They capture only what would otherwise be lost between runs: the _why_ behind decisions, surprising findings, and context that makes the next agent immediately productive.
468
481
 
469
- The `cy-workflow-memory` skill handles all of this automatically when referenced in task prompts. No manual setup required — just run `compozy start` and agents inherit context from every previous run.
482
+ The `cy-workflow-memory` skill handles all of this automatically when referenced in task prompts. No manual setup required — run `compozy tasks run <workflow>` and agents inherit context from every previous run.
470
483
 
471
484
  ### 🤖 Supported Agents
472
485
 
473
- **Execution** (`compozy exec`, `compozy start`, `compozy fix-reviews`) — ACP-capable runtimes that can run ad hoc prompts and task workflows:
486
+ **Execution** (`compozy exec`, `compozy tasks run`, `compozy reviews fix`) — ACP-capable runtimes that can run ad hoc prompts and daemon-backed workflow tasks:
474
487
 
475
488
  | Agent | `--ide` flag |
476
489
  | -------------- | -------------- |
@@ -529,7 +542,7 @@ compozy migrate [flags]
529
542
  </details>
530
543
 
531
544
  <details>
532
- <summary><code>compozy sync</code> — Refresh task workflow metadata files</summary>
545
+ <summary><code>compozy sync</code> — Reconcile workflow artifacts into daemon state</summary>
533
546
 
534
547
  ```bash
535
548
  compozy sync [flags]
@@ -543,6 +556,95 @@ compozy sync [flags]
543
556
 
544
557
  </details>
545
558
 
559
+ <details>
560
+ <summary><code>compozy daemon</code> — Manage the shared home-scoped daemon</summary>
561
+
562
+ ```bash
563
+ compozy daemon start
564
+ compozy daemon status
565
+ compozy daemon stop [--force]
566
+ ```
567
+
568
+ Use `daemon start` for an explicit bootstrap, `daemon status` for health and transport info, and `daemon stop` for graceful shutdown. Most workflow commands auto-start the daemon for you.
569
+
570
+ </details>
571
+
572
+ <details>
573
+ <summary><code>compozy workspaces</code> — Manage daemon workspace registrations</summary>
574
+
575
+ ```bash
576
+ compozy workspaces list [--format text|json]
577
+ compozy workspaces show <id-or-path> [--format text|json]
578
+ compozy workspaces register <path> [--name display-name] [--format text|json]
579
+ compozy workspaces unregister <id-or-path> [--format text|json]
580
+ compozy workspaces resolve <path> [--format text|json]
581
+ ```
582
+
583
+ The daemon lazily registers workspaces on first use, but the `workspaces` family gives operators explicit control over the registry.
584
+
585
+ </details>
586
+
587
+ <details>
588
+ <summary><code>compozy tasks validate</code> — Validate task metadata before execution</summary>
589
+
590
+ ```bash
591
+ compozy tasks validate [--name my-feature | --tasks-dir .compozy/tasks/my-feature] [--format text|json]
592
+ ```
593
+
594
+ Use `tasks validate` to check every `task_*.md` file in a workflow directory against the v2 task metadata schema before you run `tasks run`.
595
+
596
+ </details>
597
+
598
+ <details>
599
+ <summary><code>compozy tasks run</code> — Start one daemon-backed workflow run</summary>
600
+
601
+ ```bash
602
+ compozy tasks run <slug> [flags]
603
+ ```
604
+
605
+ The CLI resolves workspace defaults locally, validates the task metadata, auto-starts the daemon when needed, and then starts the workflow through the daemon transport.
606
+
607
+ | Flag | Default | Description |
608
+ | --------------------- | ------- | ----------------------------------------------------------------------------------- |
609
+ | `--name` | | Workflow slug (defaults to the positional slug) |
610
+ | `--include-completed` | `false` | Re-run completed tasks |
611
+ | `--skip-validation` | `false` | Skip task metadata preflight; use only when validation already ran elsewhere |
612
+ | `--force` | `false` | Continue after task metadata validation fails in non-interactive mode |
613
+ | `--attach` | `auto` | Attach mode: `auto`, `ui`, `stream`, or `detach` |
614
+ | `--ui` | `false` | Force interactive TUI attach mode |
615
+ | `--stream` | `false` | Force textual stream attach mode |
616
+ | `--detach` | `false` | Start the run without attaching a client |
617
+ | `--task-runtime` | | Per-task runtime override rule (`type=...`, `id=...`, `ide=...`, `model=...`, etc.) |
618
+
619
+ </details>
620
+
621
+ <details>
622
+ <summary><code>compozy reviews</code> — Inspect and remediate review workflows</summary>
623
+
624
+ ```bash
625
+ compozy reviews fetch <slug> [--provider coderabbit --pr 42 --round N]
626
+ compozy reviews list <slug>
627
+ compozy reviews show <slug> [round]
628
+ compozy reviews fix <slug> [flags]
629
+ ```
630
+
631
+ `reviews fetch` imports provider feedback into `.compozy/tasks/<slug>/reviews-NNN/`. `reviews fix` uses the same daemon-backed runtime model as `tasks run`, including `--attach`, `--ui`, `--stream`, and `--detach`.
632
+
633
+ </details>
634
+
635
+ <details>
636
+ <summary><code>compozy runs</code> — Reattach, observe, and clean daemon-managed runs</summary>
637
+
638
+ ```bash
639
+ compozy runs attach <run-id>
640
+ compozy runs watch <run-id>
641
+ compozy runs purge
642
+ ```
643
+
644
+ Use `runs attach` to restore the interactive TUI for an existing run, `runs watch` for textual streaming observation, and `runs purge` to delete terminal run artifacts according to the configured retention policy.
645
+
646
+ </details>
647
+
546
648
  <details>
547
649
  <summary><code>compozy archive</code> — Move fully completed workflows into the archive root</summary>
548
650
 
@@ -565,9 +667,9 @@ compozy archive [flags]
565
667
  compozy exec [prompt] [flags]
566
668
  ```
567
669
 
568
- Provide exactly one prompt source: a positional prompt, `--prompt-file`, or `stdin`. When present, `.compozy/config.toml` can provide exec defaults through `[exec]` and shared runtime defaults through `[defaults]`.
670
+ Provide exactly one prompt source: a positional prompt, `--prompt-file`, or `stdin`. When present, `~/.compozy/config.toml` and `.compozy/config.toml` can provide exec defaults through `[exec]` and shared runtime defaults through `[defaults]`.
569
671
 
570
- `compozy exec` is headless and ephemeral by default. Use `--agent <name>` to execute a reusable agent from `.compozy/agents/` or `~/.compozy/agents/`, `--persist` to create `.compozy/runs/<run-id>/` for resumable sessions, `--run-id` to continue a persisted session, `--format json` for lean JSONL, `--format raw-json` for the full raw event stream, and `--tui` to opt back into the interactive UI.
672
+ `compozy exec` is headless and ephemeral by default. Use `--agent <name>` to execute a reusable agent from `.compozy/agents/` or `~/.compozy/agents/`, `--persist` to create `~/.compozy/runs/<run-id>/` for resumable sessions, `--run-id` to continue a persisted session, `--format json` for lean JSONL, `--format raw-json` for the full raw event stream, and `--tui` to opt back into the interactive UI.
571
673
 
572
674
  | Flag | Default | Description |
573
675
  | ---------------------------- | ----------- | ------------------------------------------------------------------------------------------ |
@@ -579,14 +681,14 @@ Provide exactly one prompt source: a positional prompt, `--prompt-file`, or `std
579
681
  | `--reasoning-effort` | `medium` | `low`, `medium`, `high`, `xhigh` |
580
682
  | `--access-mode` | `full` | `default` or `full` runtime access policy |
581
683
  | `--timeout` | `10m` | Activity timeout per job |
582
- | `--max-retries` | `0` | Retry execution-stage ACP failures or timeouts N times |
684
+ | `--max-retries` | `2` | Retry execution-stage ACP failures or timeouts N times |
583
685
  | `--retry-backoff-multiplier` | `1.5` | Multiplier applied to the next timeout after each retry |
584
686
  | `--tail-lines` | `0` | Maximum log lines retained per job in UI (`0` = full history) |
585
687
  | `--add-dir` | | Additional directories to allow (repeatable; currently `claude` and `codex` only) |
586
688
  | `--auto-commit` | `false` | Include automatic commit instructions when the prompt asks for code changes |
587
689
  | `--verbose` | `false` | Emit operational runtime logs to stderr during exec |
588
690
  | `--tui` | `false` | Open the interactive TUI instead of headless stdout output |
589
- | `--persist` | `false` | Persist exec artifacts under `.compozy/runs/<run-id>/` |
691
+ | `--persist` | `false` | Persist exec artifacts under `~/.compozy/runs/<run-id>/` |
590
692
  | `--run-id` | | Resume a previously persisted exec session by run id |
591
693
  | `--dry-run` | `false` | Preview prompts without executing |
592
694
 
@@ -631,88 +733,6 @@ compozy ext <subcommand> [flags]
631
733
 
632
734
  </details>
633
735
 
634
- <details>
635
- <summary><code>compozy start</code> — Execute PRD task files</summary>
636
-
637
- ```bash
638
- compozy start [flags]
639
- ```
640
-
641
- Running `compozy start` with no flags opens the interactive form automatically.
642
- When present, `.compozy/config.toml` can provide defaults for runtime flags such as
643
- `--ide`, `--model`, `--reasoning-effort`, `--access-mode`, `--timeout`, `--add-dir`, and `--auto-commit`.
644
-
645
- | Flag | Default | Description |
646
- | ---------------------------- | ----------- | ------------------------------------------------------------------------------------------ |
647
- | `--name` | | Workflow name (`.compozy/tasks/<name>`) |
648
- | `--tasks-dir` | | Path to tasks directory |
649
- | `--ide` | `codex` | Runtime: `claude`, `codex`, `copilot`, `cursor-agent`, `droid`, `gemini`, `opencode`, `pi` |
650
- | `--model` | _(per IDE)_ | Model override |
651
- | `--reasoning-effort` | `medium` | `low`, `medium`, `high`, `xhigh` |
652
- | `--access-mode` | `full` | `default` or `full` runtime access policy |
653
- | `--timeout` | `10m` | Activity timeout per job |
654
- | `--max-retries` | `0` | Retry execution-stage ACP failures or timeouts N times |
655
- | `--retry-backoff-multiplier` | `1.5` | Multiplier applied to the next timeout after each retry |
656
- | `--tail-lines` | `0` | Maximum log lines retained per job in UI (`0` = full history) |
657
- | `--add-dir` | | Additional directories to allow (repeatable; currently `claude` and `codex` only) |
658
- | `--auto-commit` | `false` | Auto-commit after each task |
659
- | `--include-completed` | `false` | Re-run completed tasks |
660
- | `--dry-run` | `false` | Preview prompts without executing |
661
-
662
- </details>
663
-
664
- <details>
665
- <summary><code>compozy fetch-reviews</code> — Fetch review comments into a review round</summary>
666
-
667
- ```bash
668
- compozy fetch-reviews [flags]
669
- ```
670
-
671
- Running `compozy fetch-reviews` with no flags opens the interactive form automatically.
672
- When present, `.compozy/config.toml` can provide defaults such as `--provider`.
673
-
674
- | Flag | Default | Description |
675
- | ------------ | ------- | ----------------------------------------- |
676
- | `--provider` | | Review provider (`coderabbit`, etc.) |
677
- | `--pr` | | Pull request number |
678
- | `--name` | | Workflow name |
679
- | `--round` | `0` | Round number (auto-increments if omitted) |
680
-
681
- </details>
682
-
683
- <details>
684
- <summary><code>compozy fix-reviews</code> — Dispatch AI agents to remediate review issues</summary>
685
-
686
- ```bash
687
- compozy fix-reviews [flags]
688
- ```
689
-
690
- Running `compozy fix-reviews` with no flags opens the interactive form automatically.
691
- When present, `.compozy/config.toml` can provide runtime defaults as well as review workflow
692
- defaults such as `--concurrent`, `--batch-size`, and `--include-resolved`.
693
-
694
- | Flag | Default | Description |
695
- | ---------------------------- | ----------- | ------------------------------------------------------------------------------------------ |
696
- | `--name` | | Workflow name |
697
- | `--round` | `0` | Round number (latest if omitted) |
698
- | `--reviews-dir` | | Override review directory path |
699
- | `--ide` | `codex` | Runtime: `claude`, `codex`, `copilot`, `cursor-agent`, `droid`, `gemini`, `opencode`, `pi` |
700
- | `--model` | _(per IDE)_ | Model override |
701
- | `--batch-size` | `1` | Issues per batch |
702
- | `--concurrent` | `1` | Parallel batches |
703
- | `--include-resolved` | `false` | Re-process resolved issues |
704
- | `--reasoning-effort` | `medium` | `low`, `medium`, `high`, `xhigh` |
705
- | `--access-mode` | `full` | `default` or `full` runtime access policy |
706
- | `--timeout` | `10m` | Activity timeout per job |
707
- | `--max-retries` | `0` | Retry execution-stage ACP failures or timeouts N times |
708
- | `--retry-backoff-multiplier` | `1.5` | Multiplier applied to the next timeout after each retry |
709
- | `--tail-lines` | `0` | Maximum log lines retained per job in UI (`0` = full history) |
710
- | `--add-dir` | | Additional directories to allow (repeatable; currently `claude` and `codex` only) |
711
- | `--auto-commit` | `false` | Auto-commit after each batch |
712
- | `--dry-run` | `false` | Preview prompts without executing |
713
-
714
- </details>
715
-
716
736
  <details>
717
737
  <summary><strong>Go Package Usage</strong> — Use Compozy as a library in your own tools</summary>
718
738
 
@@ -776,7 +796,7 @@ skills/ Bundled installable skills
776
796
  .compozy/config.toml Optional workspace defaults for CLI execution
777
797
  .compozy/agents/ Optional reusable agents (`AGENT.md` + optional `mcp.json`)
778
798
  .compozy/extensions/ Workspace-scoped extensions (starts disabled)
779
- .compozy/runs/ Runtime artifacts for persisted executions and resumable exec sessions
799
+ ~/.compozy/runs/ Home-scoped runtime artifacts for daemon-managed and persisted exec runs
780
800
  .compozy/tasks/ Default workflow artifact root (PRDs, TechSpecs, tasks, ADRs, reviews)
781
801
  ```
782
802
 
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@compozy/cli",
3
3
  "type": "module",
4
- "version": "0.1.11",
4
+ "version": "0.2.0",
5
5
  "description": "Compozy CLI",
6
6
  "scripts": {
7
7
  "postinstall": "node install.js",
@@ -21,69 +21,69 @@
21
21
  "compozy": "run-compozy.js"
22
22
  },
23
23
  "dependencies": {
24
- "jszip": "^3.10.1",
25
- "proxy-agent": "^7.0.0",
26
- "tar": "^7.4.3"
24
+ "jszip": "3.10.1",
25
+ "proxy-agent": "8.0.1",
26
+ "tar": "7.5.13"
27
27
  },
28
28
  "archives": {
29
29
  "darwin-arm64": {
30
- "name": "compozy_0.1.11_darwin_arm64.tar.gz",
31
- "url": "https://github.com/compozy/compozy/releases/download/v0.1.11/compozy_0.1.11_darwin_arm64.tar.gz",
30
+ "name": "compozy_0.2.0_darwin_arm64.tar.gz",
31
+ "url": "https://github.com/compozy/compozy/releases/download/v0.2.0/compozy_0.2.0_darwin_arm64.tar.gz",
32
32
  "bins": [
33
33
  "compozy"
34
34
  ],
35
35
  "format": "tar.gz",
36
36
  "checksum": {
37
37
  "algorithm": "sha256",
38
- "digest": "9cbfc3642a8475abfcfb89fd99fcbff943e79b8a4a0ae51648e9bcd83c5826de"
38
+ "digest": "4b80db032018813cf38f5acc68bb602480cebddbabd4cb2e790f8d46f3168f04"
39
39
  }
40
40
  },
41
41
  "darwin-x64": {
42
- "name": "compozy_0.1.11_darwin_x86_64.tar.gz",
43
- "url": "https://github.com/compozy/compozy/releases/download/v0.1.11/compozy_0.1.11_darwin_x86_64.tar.gz",
42
+ "name": "compozy_0.2.0_darwin_x86_64.tar.gz",
43
+ "url": "https://github.com/compozy/compozy/releases/download/v0.2.0/compozy_0.2.0_darwin_x86_64.tar.gz",
44
44
  "bins": [
45
45
  "compozy"
46
46
  ],
47
47
  "format": "tar.gz",
48
48
  "checksum": {
49
49
  "algorithm": "sha256",
50
- "digest": "2e98122d651d646113672c5bf0c98743d25205e12548b9652b398b7d0e16eb11"
50
+ "digest": "25e9e43dc1c96ec592487172a980b59f068a56b9c27164eb305ae401a9672e55"
51
51
  }
52
52
  },
53
53
  "linux-arm64": {
54
- "name": "compozy_0.1.11_linux_arm64.tar.gz",
55
- "url": "https://github.com/compozy/compozy/releases/download/v0.1.11/compozy_0.1.11_linux_arm64.tar.gz",
54
+ "name": "compozy_0.2.0_linux_arm64.tar.gz",
55
+ "url": "https://github.com/compozy/compozy/releases/download/v0.2.0/compozy_0.2.0_linux_arm64.tar.gz",
56
56
  "bins": [
57
57
  "compozy"
58
58
  ],
59
59
  "format": "tar.gz",
60
60
  "checksum": {
61
61
  "algorithm": "sha256",
62
- "digest": "83e8bd3f52046384c70eb2ea8e34d084e39117775d987136b0aeb0842931526f"
62
+ "digest": "3da3223b3f1e038d5934fb2456da815537db75f0e915755b815133981c6eb04d"
63
63
  }
64
64
  },
65
65
  "linux-x64": {
66
- "name": "compozy_0.1.11_linux_x86_64.tar.gz",
67
- "url": "https://github.com/compozy/compozy/releases/download/v0.1.11/compozy_0.1.11_linux_x86_64.tar.gz",
66
+ "name": "compozy_0.2.0_linux_x86_64.tar.gz",
67
+ "url": "https://github.com/compozy/compozy/releases/download/v0.2.0/compozy_0.2.0_linux_x86_64.tar.gz",
68
68
  "bins": [
69
69
  "compozy"
70
70
  ],
71
71
  "format": "tar.gz",
72
72
  "checksum": {
73
73
  "algorithm": "sha256",
74
- "digest": "6a2c0ad67b81e0424983677f745daf72ce166b4e3dbfc99db45c1159037fb53f"
74
+ "digest": "e20c8aeb84bb928532bf5cece2e6517116edfd459bbdb48ccedd6f6bf8c7808a"
75
75
  }
76
76
  },
77
77
  "win32-x64": {
78
- "name": "compozy_0.1.11_windows_x86_64.zip",
79
- "url": "https://github.com/compozy/compozy/releases/download/v0.1.11/compozy_0.1.11_windows_x86_64.zip",
78
+ "name": "compozy_0.2.0_windows_x86_64.zip",
79
+ "url": "https://github.com/compozy/compozy/releases/download/v0.2.0/compozy_0.2.0_windows_x86_64.zip",
80
80
  "bins": [
81
81
  "compozy.exe"
82
82
  ],
83
83
  "format": "zip",
84
84
  "checksum": {
85
85
  "algorithm": "sha256",
86
- "digest": "6a27063b8e2a6932770d1f20932685e58e33796d24aac001b852f8faba1a4412"
86
+ "digest": "27550bd13ae7e44fb07192cfdf9f95dbdfdb3e0f1282592bf23ef3dfa75d23dd"
87
87
  }
88
88
  }
89
89
  }