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.
Beta.15 updates task runtime state, platform session identity propagation, Pi Agent integration, and beta documentation. It also keeps the shared-hook cleanup manifest entries from the pending beta.15 release.
Behavior Changes
Session-scoped active task runtime
Active task state now uses a per-session runtime file:
.trellis/.runtime/sessions/<session-key>.json
.trellis/.current-task is no longer used as the active-task fallback.
| Command | Behavior |
|---|
task.py start <task> | Writes the current task into the resolved session file |
task.py current --source | Reads the current task from the resolved session file |
task.py finish | Deletes the resolved session file |
task.py archive <task> | Deletes session files that still point at the archived task before moving it |
{
"platform": "session",
"last_seen_at": "2026-04-27T01:43:24Z",
"current_task": ".trellis/tasks/04-21-session-scoped-task-state",
"current_run": null
}
task.py start exits with code 1 when no session identity is available:
Error: Cannot set active task without a session identity.
Hint: run inside an AI IDE/session that exposes session identity, or set TRELLIS_CONTEXT_ID before running task.py start.
Bootstrap and joiner tasks
trellis init still creates bootstrap and joiner task directories, but it no longer writes .trellis/.current-task.
The generated PRDs now tell the AI to start the task from a session that exposes Trellis session identity.
Workflow task-creation policy
workflow.md and hook fallback breadcrumbs now use a softer task-creation policy.
| Area | Previous behavior | beta.15 behavior |
|---|
no_task trigger words | Treat matching words as requiring task creation | Treat matching words as task-creation signals |
| Simple turns | No explicit exemption | Task not required when all three hold: zero file writes, one-reply answer, no research beyond reading 1-2 repo files |
| User opt-out | Not documented in the hook prompt | Current-turn phrases such as skip trellis, no task, just do it, 跳过 trellis, 别走流程, 先别建任务 skip task creation for that turn |
in_progress implementation | Main session was told not to edit code | Sub-agent dispatch remains the default; explicit current-turn requests such as do it inline, main session 写就行, 不用 sub-agent allow main-session implementation |
Shell session identity handling
Several hosts expose session identity differently. beta.15 adds host-specific handling for task.py start/current/finish.
| Platform | Change |
|---|
| Claude Code | session-start.py writes TRELLIS_CONTEXT_ID through CLAUDE_ENV_FILE |
| Codex | task.py resolves native command env such as CODEX_SESSION_ID and Codex Desktop CODEX_THREAD_ID |
| Cursor | beforeShellExecution writes short-lived .trellis/.runtime/cursor-shell/*.json tickets for matching task.py commands |
| OpenCode | Bash tool commands are prefixed with TRELLIS_CONTEXT_ID |
| Pi | Bash tool calls and nested pi --mode json sub-agent runs receive TRELLIS_CONTEXT_ID |
.trellis/.runtime/sessions/ storage, but beta.15 does not add new shell-command handling for them.
| Platform group | beta.15 status |
|---|
| GitHub Copilot | The platform-specific SessionStart hook resolves session identity for context injection. task.py can use exported COPILOT_* session env vars when the host provides them; otherwise use TRELLIS_CONTEXT_ID for manual shell starts. |
| Gemini CLI, Qoder, CodeBuddy, Droid, Kiro | Shared hooks resolve session identity from hook input or platform env vars. No new shell-command bridge was added in beta.15. Manual shell starts still use TRELLIS_CONTEXT_ID when the host does not export a session id. |
| Kilo, Antigravity, Windsurf | No hook integration. Use their workflow/command files plus explicit TRELLIS_CONTEXT_ID when running task.py start manually. |
.agents/skills consumers | No Trellis-managed hook layer. They use the .trellis/ core and whatever prelude or env injection the host provides. |
Cursor sub-agent hook matching
Cursor hooks.json now matches both tool names:
{
"matcher": "Task|Subagent"
}
inject-subagent-context.py also parses Cursor custom-agent payloads in these shapes:
{ "custom": { "name": "trellis-implement" } }
{ "type": { "case": "custom", "value": { "name": "trellis-implement" } } }
Pi Agent session runtime
Pi Agent now reads active task state from .trellis/.runtime/sessions/.
Context key sources, in priority order:
| Source | Example |
|---|
| Explicit env | TRELLIS_CONTEXT_ID |
| Pi session manager | sessionManager.getSessionId() |
| Pi env | PI_SESSION_ID, PI_SESSIONID |
| Transcript path | transcript_path / transcriptPath |
| Process fallback | pi_process_<hash> |
TRELLIS_CONTEXT_ID.
Workflow-state override copy
workflow-state breadcrumbs now use exact Trellis agent names:
trellis-implement
trellis-check
trellis-research
Bug Fixes
OpenCode sub-agent name normalization
OpenCode now:
- recognizes
OPENCODE_RUN_ID as session identity
- strips the
trellis- prefix before matching sub-agent names
- keeps
implement.jsonl / check.jsonl injection working with renamed agents
Git-backed private registries
Template registry downloads now support private Git-backed registries. When a registry source requires local Git credentials, Trellis uses Git to read index.json and copy template directories instead of relying on anonymous raw HTTP.
This applies to self-hosted GitLab / GitHub Enterprise sources and SSH registry URLs. Registry errors are classified separately for authentication failures, missing refs, missing paths, invalid index.json, and network failures, so trellis init --registry no longer misclassifies those cases as direct-download mode.
Shared-hook cleanup
writeSharedHooks and collectSharedHooks now use the same platform capability table:
Claude Code statusLine is no longer installed by default for new projects. New installs do not write .claude/hooks/statusline.py or configure statusLine in .claude/settings.json.
Existing projects keep their installed Claude Code statusLine behavior: trellis update preserves .claude/hooks/statusline.py and carries an existing .claude/settings.json statusLine entry forward into the updated settings file.
The manifest includes 10 hash-verified safe-file-delete entries for hooks that were written to projects but are now orphaned.
| Removed path | Reason |
|---|
.cursor/hooks/statusline.py | Cursor has no statusLine event |
.codex/hooks/statusline.py | Codex has no statusLine event |
.gemini/hooks/statusline.py | Gemini has no statusLine event |
.qoder/hooks/statusline.py | Qoder has no statusLine event |
.github/copilot/hooks/statusline.py | Copilot has no statusLine event |
.codebuddy/hooks/statusline.py | CodeBuddy has no statusLine event |
.factory/hooks/statusline.py | Factory Droid has no statusLine event |
.kiro/hooks/statusline.py | Kiro has no statusLine event |
.kiro/hooks/session-start.py | Kiro exposes only agentSpawn |
.kiro/hooks/inject-workflow-state.py | Kiro exposes only agentSpawn |
Docs
Beta task docs
Updated beta docs now describe:
- current task state under
.trellis/.runtime/sessions/<session-key>.json
- session-scoped task ownership instead of a global project pointer
continue / finish-work as the primary user-facing task commandstask.py start as a session-bound operation- Cursor, Codex, Claude Code, OpenCode, and Pi hook/sub-agent behavior
Multi-agent docs
The beta multi-agent docs now describe native Git worktrees plus Trellis tasks. Removed references to Trellis-managed /trellis:parallel and worktree.yaml.
Upgrade
Existing projects:
No --migrate gate is required for beta.15.
Existing task directories and jsonl files remain valid. Existing .trellis/.current-task files are preserved but ignored by the new active-task resolver.
Manual shell usage requires an explicit context id:
TRELLIS_CONTEXT_ID=my-session python3 .trellis/scripts/task.py start .trellis/tasks/<task>
