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.
Codex users — upgrade caveat in 0.6.0:
[features.multi_agent_v2]block removed (beta.21) — Codex CLI changedfeaturesdeserialization 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 withdata did not match any variant of untagged enum FeatureToml in features.multi_agent_v2and aborted config load.trellis init/trellis updateno longer write this block — Codex’s own default is used. Tune it yourself in~/.codex/config.tomlif needed.codex.dispatch_mode: inlineis the default (beta.1) — Codex sub-agents run withfork_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 viacodex.dispatch_mode: sub-agentin.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/<name>/SKILL.md; slash commands are platform-built-in. Sub-agent skills carryrunAs: subagentfor isolated subagent loops. Closes#301. - Pi Agent — native
trellis_subagentextension — Pi now exposestrellis_subagent(avoiding thesubagentnamespace collision with community packages) withsingle/parallel/chaindispatch modes, native progress cards (Alt+Ofor detail view), throttled live updates, and Trellis-agent validation. Closes#286,#290.
OpenCode users — reader temporarily unavailable:
trellis memreturns empty on OpenCode 1.2+ — OpenCode 1.2 moved session storage to SQLite. The beta.3 SQLite reader added abetter-sqlite3native dependency that failed to install on machines without a C toolchain, so it was reverted in beta.4.trellis mem list / search / extractnow 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.
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 | prunesubcommands.- Claude
stream-jsonand Codexapp-serverJSON-RPC adapters translate provider output into normalizedmessage/progress/done/errorevents. - Events persist to
~/.trellis/channels/<project>/<channel>/events.jsonlwith locked sequence assignment. - Every subcommand accepts
--scope project|globalfor 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 <duration>emits asupervisor_warningevent (5m default lead time; disable via0ms).- Codex workers record completed answers before
doneand serialize non-interrupt turns (turn_started/turn_finished/interrupt_requested/interrupted). - Codex channel
progressevents carrydetail.kind(output | commentary | reasoning),detail.stream_id,detail.phase,detail.text_delta. Consumers should group deltas bystream_idand treatkind:"message"as the canonical completed answer.
Channel worker OOM guard
Default safeguardschannel.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 fromsend.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 <id> prints a non-blocking stderr warning when the resolved workflow references missing .trellis/agents/<name>.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 <id> --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: <slug> ---. 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/<name>/SKILL.md; sub-agent skills carryrunAs: subagent. Closes#301. - Pi Agent — native
trellis_subagentextension matured —single/parallel/chaindispatch modes, native progress cards (Alt+Ofor detail view), throttled live updates, Trellis-agent validation. Closes#286,#290. - Codex — inline mode default —
codex.dispatch_mode: inlinelets the main Codex agent edit code directly (sub-agents can’t inherit task context underfork_turns="none"). Opt back intosub-agentvia.trellis/config.yaml. - OpenCode — shell-dialect
TRELLIS_CONTEXT_ID— hook command now emits a shell-aware export so$TRELLIS_CONTEXT_IDresolves correctly across POSIX shells and OpenCode 1.2+ runners. - Cursor — sessionStart
additional_context— hook payload now uses the documentedadditional_contextfield, 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 requireprd.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@<channel> with channel-aware defaults (latest, beta, rc). Flags: --tag <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 <id> 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 |
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-implementandtrellis-checkdrop bothmcp__exa__*entries. These agents do not need external web search; the tools list shrinks toRead, Write, Edit, Bash, Glob, Grep.trellis-researchfolds the previousmcp__exa__*+mcp__chrome-devtools__*entries into a singlemcp__*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 (
mapLegacyToolToCopilotinpackages/cli/src/configurators/shared.ts) gets a matching case formcp__*that emits the full set of supported Copilot MCP equivalents.
mcp__exa__*: allow) that does not silent-skip, so they are intentionally left unchanged. Closes #302.
Breaking changes & upgrade
The breaking-change gate fires at0.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:--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.
From any 0.6.0 prerelease (beta.X / rc.X):
trellis update — clean version bump, no flag needed.
Install: