> ## Documentation Index > Fetch the complete documentation index at: https://docs.trytrellis.app/llms.txt > Use this file to discover all available pages before exploring further. # v0.6.0 > 2026-06-15 Stable promotion of `0.6.0-rc.0` with no new src/ changes. v0.6.0 is a breaking release from 0.5.x — multi-agent collaboration via `trellis channel`, a published `@mindfoldhq/trellis-core` SDK, and cross-session memory recall via `trellis mem`. **Multi-agent collaboration is now a first-class primitive.** `trellis channel` ships a worker-supervisor runtime with Claude `stream-json` and Codex `app-server` adapters, persistent event logs under `~/.trellis/channels/`, forum/thread channels for issue-style boards, a default OOM guard, and reusable lifecycle/subscription APIs in `@mindfoldhq/trellis-core/channel`. The bundled `check` / `implement` agent definitions auto-install with `trellis init` / `trellis update`, so `channel spawn --agent check` works out of the box. See the "[Multi-agent collaboration](#multi-agent-collaboration)" section below. **Codex users — upgrade caveat in 0.6.0:** * **`[features.multi_agent_v2]` block removed (beta.21)** — Codex CLI changed `features` deserialization between 0.130 and 0.131. The structured table form only loads on 0.131+; on 0.130 and earlier (including the Codex desktop app's bundled CLI) it failed with `data did not match any variant of untagged enum FeatureToml in features.multi_agent_v2` and aborted config load. `trellis init` / `trellis update` no longer write this block — Codex's own default is used. Tune it yourself in `~/.codex/config.toml` if needed. * **`codex.dispatch_mode: inline` is the default (beta.1)** — Codex sub-agents run with `fork_turns="none"`, so they can't inherit the parent session's task context. The main Codex agent now edits code directly. Opt back into sub-agent dispatch via `codex.dispatch_mode: sub-agent` in `.trellis/config.yaml`. **New platforms in 0.6.0:** * **Reasonix (DeepSeek-Reasonix)** — 15th supported AI coding tool, available via `trellis init --reasonix`. Skills live at `.reasonix/skills//SKILL.md`; slash commands are platform-built-in. Sub-agent skills carry `runAs: subagent` for isolated subagent loops. Closes `#301`. * **Pi Agent — native `trellis_subagent` extension** — Pi now exposes `trellis_subagent` (avoiding the `subagent` namespace collision with community packages) with `single` / `parallel` / `chain` dispatch modes, native progress cards (`Alt+O` for detail view), throttled live updates, and Trellis-agent validation. Closes `#286`, `#290`. **OpenCode users — reader temporarily unavailable:** * **`trellis mem` returns empty on OpenCode 1.2+** — OpenCode 1.2 moved session storage to SQLite. The beta.3 SQLite reader added a `better-sqlite3` native dependency that failed to install on machines without a C toolchain, so it was reverted in beta.4. `trellis mem list / search / extract` now returns empty with a one-shot stderr warning for OpenCode; Claude and Codex paths are unchanged. A permanent OpenCode reader rework is deferred past v0.6.0. **Known upstream issues at GA cut (not fixable from Trellis):** * **OpenCode 1.2+ SQLite session reader** — see the `` above. Tracked for v0.7+. * **Feature requests deferred past v0.6** — `#193`, `#318`, `#320`, `#325`, `#326` and similar tracker items are explicitly punted to v0.7 or later per the `rc.0` cut. ## Multi-agent collaboration `trellis channel` is the headline addition of v0.6.0 — a worker-supervisor primitive for coordinating multiple AI processes through a shared event log. ### `trellis channel` runtime * `channel create | send | wait | spawn | run | list | messages | kill | rm | prune` subcommands. * Claude `stream-json` and Codex `app-server` JSON-RPC adapters translate provider output into normalized `message` / `progress` / `done` / `error` events. * Events persist to `~/.trellis/channels///events.jsonl` with locked sequence assignment. * Every subcommand accepts `--scope project|global` for explicit project-or-global targeting. ### Forum and thread channels `--type threads` and `--type forum` produce durable issue/thread-style boards. `channel post | threads | thread | forum` subcommands plus `channel context add | delete | list`, `channel title set | clear`, and `channel thread rename` cover the lifecycle. Events can carry stable `--description`, `--context-file`, `--context-raw` (legacy `--linked-context-*` aliases preserved). ### Worker coordination * `channel wait --kind done,killed` — multi-kind filter. * `channel spawn --warn-before ` emits a `supervisor_warning` event (5m default lead time; disable via `0ms`). * Codex workers record completed answers before `done` and serialize non-interrupt turns (`turn_started` / `turn_finished` / `interrupt_requested` / `interrupted`). * Codex channel `progress` events carry `detail.kind` (`output | commentary | reasoning`), `detail.stream_id`, `detail.phase`, `detail.text_delta`. Consumers should group deltas by `stream_id` and treat `kind:"message"` as the canonical completed answer. ### Channel worker OOM guard Default safeguards `channel.worker_guard.idle_timeout` (5m) and `channel.worker_guard.max_live_workers` (6), configurable per-spawn (`--idle-timeout`, `--max-live-workers`) or via env vars (`TRELLIS_CHANNEL_WORKER_IDLE_TIMEOUT`, `TRELLIS_CHANNEL_MAX_LIVE_WORKERS`). Idle workers emit `killed` with `reason: "idle-timeout"`; mid-turn workers are never killed. ### Message-routing cleanup + durable idempotency Tag-based routing is removed from `send.ts` / `wait.ts` / provider adapters — tags are kept only on channel events, worker inbox policy, and explicit `to`. `sendMessage` and `postThread` accept a durable `idempotencyKey` option: repeated writes with the same key return the original JSONL event without producing duplicate `undeliverable` events. ### Channel runtime agent definitions auto-dispatched `trellis init` and `trellis update` now ship platform-agnostic `.trellis/agents/{check,implement}.md` on every install, so `trellis channel spawn --agent check` works out of the box. `trellis workflow --template ` prints a non-blocking stderr warning when the resolved workflow references missing `.trellis/agents/.md` files (detection via `utils/agent-refs.ts`). Closes `#323`. ## Memory (`trellis mem`) A local CLI that indexes Claude Code and Codex conversation logs already on disk and exposes them through `list`, `search`, `context`, `extract`, and `projects` subcommands. Nothing is uploaded. (84 unit tests, 81.89% coverage on first ship.) ### Phase slicing `mem extract --phase brainstorm` slices between `task.py create` and `task.py start`; `--phase implement` is the inverse; `--phase all` is the default. Multi-task sessions are separated by `--- task: ---`. The `--phase` parser handles `$(... --slug NAME)` substitution, multiple `task.py` invocations per Bash command, and `task.py start` inside commit-message heredocs. ### Cross-day session window correctness `--since` now filters by `inRangeOverlap(start, end, filter)` — sessions match if `[created, updated]` overlaps `[since, until]`. The previous "session created in range" filter dropped 29MB Claude sessions that started on day N–1 and were still being written on day N, even when they contained 19 matching turns written that day. ### Reusable retrieval primitives `@mindfoldhq/trellis-core/mem` exports `listMemSessions`, `searchMemSessions`, `readMemContext`, `extractMemDialogue`, `listMemProjects`, with per-platform adapters under `packages/core/src/mem/adapters/`. The CLI is a thin wrapper. ## Platform coverage v0.6.0 supports 15 AI coding tools: Claude Code, Codex, Cursor, OpenCode, Gemini, Kiro, Qoder, CodeBuddy, Droid, Pi, GitHub Copilot, Windsurf, Kilo Code, Factory, and the new Reasonix. * **Reasonix (DeepSeek-Reasonix), new** — 15th supported platform via `trellis init --reasonix`. Skills under `.reasonix/skills//SKILL.md`; sub-agent skills carry `runAs: subagent`. Closes `#301`. * **Pi Agent — native `trellis_subagent` extension matured** — `single` / `parallel` / `chain` dispatch modes, native progress cards (`Alt+O` for detail view), throttled live updates, Trellis-agent validation. Closes `#286`, `#290`. * **Codex — inline mode default** — `codex.dispatch_mode: inline` lets the main Codex agent edit code directly (sub-agents can't inherit task context under `fork_turns="none"`). Opt back into `sub-agent` via `.trellis/config.yaml`. * **OpenCode — shell-dialect `TRELLIS_CONTEXT_ID`** — hook command now emits a shell-aware export so `$TRELLIS_CONTEXT_ID` resolves correctly across POSIX shells and OpenCode 1.2+ runners. * **Cursor — sessionStart `additional_context`** — hook payload now uses the documented `additional_context` field, restoring task-context injection on session resume. * **GitHub Copilot — hook payload corrected** — Copilot-specific hook envelope schema fixed so context injection lands on the Copilot side without truncation. ## SDK extraction (`@mindfoldhq/trellis-core`) A second published package, `@mindfoldhq/trellis-core`, exposes `/channel`, `/task`, `/testing` subpath exports. The CLI now depends on it; both packages share one git tag, one npm dist-tag, and one version per release. `.github/workflows/publish.yml` publishes `@mindfoldhq/trellis-core` before `@mindfoldhq/trellis`, and post-publish `verify-npm --package all` confirms both on the public npm registry. ### Exported APIs | Module | Surface | | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `@mindfoldhq/trellis-core/channel` | `listWorkers`, `watchWorkers`, `spawnWorker`, `requestInterrupt`, `interruptWorker`, `readChannelEvents`, `watchChannels`, `readWorkerInbox`, `watchWorkerInbox`, `WorkerInboxError`, `matchesInboxPolicy` | | `@mindfoldhq/trellis-core/mem` | `listMemSessions`, `searchMemSessions`, `readMemContext`, `extractMemDialogue`, `listMemProjects` | | `@mindfoldhq/trellis-core/task` | task lifecycle primitives | | `@mindfoldhq/trellis-core/testing` | test helpers shared with the CLI | ## Workflow + planning ### Task triage consent gates No-task turns now classify the request. Simple/small requests ask only whether to create a Trellis task; if not, Trellis is skipped for the turn. Complex requests ask permission to create a task and enter planning; if declined, scope is clarified or a smaller split suggested. ### Planning artifacts (`prd.md` / `design.md` / `implement.md`) `task.py create` creates a default `prd.md`. Complex planning uses `prd.md` (requirements, constraints, acceptance criteria, out-of-scope), `design.md` (boundaries, data flow, contracts, tradeoffs), and `implement.md` (checklist, validation commands, review gates) before `task.py start`. Implement/check context loading order is consistent across hook-push, pull-prelude, Pi extension, OpenCode plugin, and inline modes: `jsonl entries → prd.md → design.md → implement.md`. ### Workflow templates (selectable + switchable) `trellis init --workflow / --workflow-source` and `trellis workflow` switch between built-in flavors `native`, `tdd`, `channel-driven-subagent-dispatch`, plus marketplace templates via `workflow-resolver.ts`. The active file remains `.trellis/workflow.md`. ### Parent / child task trees `.trellis/workflow.md` and `get_context.py --mode phase --step 1.1` document parent/child task tree usage. Breadcrumbs `[workflow-state:planning]` and `[workflow-state:planning-inline]` updated. The `trellis-brainstorm` and `trellis-meta` skills cover the pattern. ### Check agents read artifacts first Check agents now require `prd.md` and optionally read `design.md` / `implement.md` before checking code. Applied to Claude Code, Cursor, OpenCode, Gemini, Kiro, Qoder, CodeBuddy, Droid, and Pi. ### Workflow-state tool routing — agents vs skills `trellis-implement` and `trellis-research` are declared as sub-agent types only; `trellis-update-spec` is a skill; `trellis-check` exists as both (verification after code changes prefers the Agent form). ## Updater ### `trellis upgrade` command Wraps `npm install -g @mindfoldhq/trellis@` with channel-aware defaults (`latest`, `beta`, `rc`). Flags: `--tag ` for explicit dist-tag/version, `--dry-run` to preview. Validates input, avoids shell interpolation on POSIX, uses `cmd.exe /d /s /c` on Windows, prints npm/PATH troubleshooting on failure. Session-start hints now point at `trellis upgrade`. ### Registry-backed `.trellis/spec` refresh `trellis init --template ` persists the spec source and template id into `.trellis/config.yaml` under a new `registry.spec` block. `trellis update` reads that block, downloads the configured spec registry into a temp dir, and feeds it through the existing hash / conflict / "modified by you" flow. Supports direct spec registries and marketplace-style registries, including SSH and self-hosted Git. New utility: `utils/registry-config.ts`. Closes `#315`. ### Configurable hooks via `.trellis/config.yaml` | Knob | Controls | | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | `session_commit_message` / `max_journal_lines` / `session_auto_commit` | journal auto-commit shape | | `hooks.after_create` / `after_start` / `after_finish` / `after_archive` | user shell commands run after each task lifecycle event | | `channel.worker_guard.idle_timeout` / `max_live_workers` | channel worker OOM protection | | `codex.dispatch_mode: inline \| sub-agent` | whether the main Codex agent edits code directly or routes through `trellis-implement` / `trellis-check` sub-agents | Existing projects receive commented-out blocks via `configSectionsAdded` on `trellis update`. ### Updater hardening `initializeHashes()` tracks platform/root files from `startRecordingWrites()` output instead of walking `.codex/` / `.claude/`. `pruneOrphanManifestKeys()` removes stale orphans before `update` and `uninstall`. `trellis init` / `uninstall` refuse to run in `$HOME` unless `TRELLIS_ALLOW_HOMEDIR=1`. `trellis update` refreshes hash-tracked `.trellis/workflow.md` as a whole template (fixes upgraded Codex installs with stale `[Codex]` blocks). Hook templates force UTF-8 on Windows (`python -X utf8` + stdio reconfigure with replacement errors). ## Bundled skills ### `trellis-channel` New bundled capability skill that teaches the AI when to reach for `trellis channel` — multi-agent collaboration, spawned workers, cross-agent review, progress inspection, forum/thread boards, and channel log debugging. SKILL.md plus five reference files (workflows, forum, workers, progress-debugging, command-reference). Auto-dispatched on every supported platform via `getBundledSkillTemplates()` directory scan. ### `trellis-meta` Rewritten for v0.6 architecture. SKILL.md preamble now covers the channel runtime, `trellis mem`, and dual-package SDK; description triggers cover bundled-skill auto-dispatch. New `references/local-architecture/multi-agent-channel.md` and `references/local-architecture/bundled-skills.md` explain channel-vs-other primitives, where state lives, `.trellis/config.yaml channel.*` knobs, and bundled vs project-local ownership / override convention. `platform-files/platform-map.md` adds the Reasonix row (15th platform) and Pi native `trellis_subagent` annotation; `customize-local/change-skills-or-commands.md` expands the platform path table from 6 to 13 platforms and documents anti-collision rules for all four bundled skills. ### `trellis-spec-bootstrap` Platform-neutral bundled skill at `templates/common/bundled-skills/trellis-spec-bootstrap/` provides source-backed references for repository analysis, spec task planning, spec writing, and MCP setup. Auto-installed across all platforms on `trellis init` / `trellis update`, replacing the older `cc-codex-spec-bootstrap` marketplace entry. The beta.23 `rename-dir` migration renames already-installed typoed directories across `.claude/skills/`, `.cursor/skills/`, `.opencode/skills/`, `.agents/skills/`, `.kiro/skills/`, `.qoder/skills/`, `.codebuddy/skills/`, `.github/skills/`, `.factory/skills/`, `.pi/skills/`, `.agent/skills/`, `.windsurf/skills/`, `.kilocode/skills/`. Closes `#296`. ### `trellis-session-insight` A capability skill that teaches the AI when to reach for `trellis mem` (past-solution recall, decision retrieval, cross-session continuation, familiar-bug debugging, self-pattern spotting, finish-work retrospective) with verbatim English + Chinese triggering phrases. Intentionally does not prescribe a fixed write-back file — what to do with what `mem` returns is judged in the moment based on the live conversation. Auto-dispatched to every supported platform. ## Bug Fixes ### `trellis-implement` / `trellis-check` no longer silent-skip when Exa MCP is absent The bundled `trellis-implement` and `trellis-check` agent definitions declared `mcp__exa__web_search_exa` and `mcp__exa__get_code_context_exa` as explicit tools. Claude Code's `tools:` parser silently skips agent registration when an explicit MCP tool name fails to resolve, so users without Exa MCP installed had every Trellis sub-agent disappear from the dispatch list — the main agent ended up implementing work itself rather than delegating. Fix: * `trellis-implement` and `trellis-check` drop both `mcp__exa__*` entries. These agents do not need external web search; the tools list shrinks to `Read, Write, Edit, Bash, Glob, Grep`. * `trellis-research` folds the previous `mcp__exa__*` + `mcp__chrome-devtools__*` entries into a single `mcp__*` wildcard. Claude Code resolves wildcards lazily (no silent-skip when nothing matches), so this opts research into any MCP the user has configured without locking the source template to a specific provider. * The Copilot transformer (`mapLegacyToolToCopilot` in `packages/cli/src/configurators/shared.ts`) gets a matching case for `mcp__*` that emits the full set of supported Copilot MCP equivalents. OpenCode agent files use a different permission mapping syntax (`mcp__exa__*: allow`) that does not silent-skip, so they are intentionally left unchanged. Closes `#302`. ## Breaking changes & upgrade The breaking-change gate fires at `0.6.0-beta.0` — that manifest carries the rename + delete migration chain. The `0.6.0` manifest itself has `breaking: false` and no migrations (rc.0 → GA is zero source change), but users coming from any `0.5.x` will traverse `0.6.0-beta.0.json` during the manifest chain walk, which IS breaking. Pass `--migrate` so the chain is honored. ## RC stabilization v0.6.0 GA = `0.6.0-rc.0` with zero `src/` changes; no rc.1 cut was needed. The breaking work happened at `0.6.0-beta.0` and the migration chain was absorbed throughout the beta line. ## Upgrade From 0.5.x: ```bash theme={null} trellis update --migrate ``` The `--migrate` flag is REQUIRED — the breaking-change gate from `0.6.0-beta.0` fires when traversing the migration chain. Local customizations are preserved with a warning. Per-prompt `reason` field explains version-specific nuances inline. Users running `update --migrate` from a 0.5.x install will also see a `rename-dir` migration that fixes the bundled skill directory name from `trellis-spec-bootstarp/` → `trellis-spec-bootstrap/` across every configured platform skill root. This is automatic and idempotent; missing roots silently skip. From any 0.6.0 prerelease (`beta.X` / `rc.X`): ```bash theme={null} trellis update ``` Plain `trellis update` — clean version bump, no flag needed. Install: ```bash theme={null} npm install -g @mindfoldhq/trellis ```