Multi-Platform and Team Configuration

Trellis ships on 21 platforms (Claude Code, Cursor, OpenCode, Codex, Kiro, Kilo, Gemini CLI, Antigravity, Devin (formerly Windsurf), Qoder, CodeBuddy, GitHub Copilot, Droid, Pi Agent, Oh My Pi, Reasonix, ZCode, Trae, Grok Build, Kimi Code, Snow CLI) and additionally supports any AI coding agent that reads the .agents/skills/ standard (Amp, Cline, Deep Agents, Firebender, Warp, and more). The .trellis/ core is identical everywhere; what differs is how hooks, extensions, skills, sub-agents, and commands are delivered on each platform.

Joining an Already-Initialized Trellis Project

Someone else already ran trellis init on the repo and you’re joining as a new team member. Just run trellis init — the CLI detects the existing setup and offers three choices:

? Trellis is already initialized. What would you like to do?
❯ Add AI platform(s)
  Set up developer identity on this device
  Full re-initialize

Option	When to pick
Add AI platform(s)	You want to add a platform others haven’t configured (e.g. you use Cursor but the team only set up Claude Code)
Set up developer identity on this device	You’re a new member, you just need to write your identity on your machine
Full re-initialize	Project config is broken and you want a clean slate

New members pick the second option. The CLI asks for your developer name (defaulting to your Git user), then:

Writes .trellis/.developer with your developer name (gitignored, per-machine)
Creates .trellis/workspace/<your-name>/ for your own journal

After that, on platforms with a SessionStart hook or extension, opening a new session auto-injects Trellis context. On platforms without automatic session injection, run /trellis:start or the platform’s start workflow.

Don’t pick Full re-initialize — it overwrites existing .trellis/, .claude/, etc. configuration and affects the whole team.

Capability Matrix

Capability	Claude Code	Cursor	OpenCode	Codex	Kiro	Gemini	Qoder	CodeBuddy	Copilot	Droid	Pi Agent	Oh My Pi
SessionStart / startup context	✅	✅	✅	⚡	⚡	✅	✅	✅	✅	✅	✅	✅
Sub-agent context injection	✅	✅	✅	❌	❌	❌	❌	✅	❌	✅	✅	✅
Dynamic spec loading	✅	pull	✅	✅	pull	pull	pull	pull	pull	pull	pull	pull
Sub-agents (`trellis-*`)	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅
Auto-trigger skills	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅
Explicit `/trellis:*` commands	✅	✅	✅	—	—	✅	✅	✅	✅	✅	✅	✅

Legend: ✅ Trellis wires the config and the platform executes it · ⚡ Partial (Codex uses AGENTS.md plus UserPromptSubmit; workflow breadcrumbs require features.hooks = true and a one-time /hooks review on 0.129+. Kiro ships a per-turn userPromptSubmit hook on the trellis agent, but the user must activate that agent — chat.defaultAgent trellis or /agent swap) · ❌ the platform does not expose this event · — the platform has no command primitive; start / finish-work / continue are delivered as skills instead. Qoder uses /trellis-{name} (hyphen, not colon) via its native Custom Commands for finish-work / continue; start is covered by its SessionStart hook. Pi Agent uses an extension rather than Python hook files, but the behavior is the same: session context, Bash environment propagation, and sub-agent context injection are handled before the agent acts. pull means the platform can resolve governing spec paths through get_context.py --mode spec, but Trellis does not push those specs into tool execution automatically. .kilocode/, .agent/ (Antigravity), and .devin/ are workflow-and-skill only: no sub-agents and no hooks. .agents/skills/ is written by every platform as a cross-platform shared layer.

Claude Code

Most complete automation. Hook layout:

Hook	Trigger	Effect
`session-start.py`	SessionStart	Injects identity, git status, active tasks
`inject-workflow-state.py`	UserPromptSubmit	Nudges the AI toward the current task’s state
`inject-subagent-context.py`	PreToolUse (Task)	Loads `implement.jsonl` / `check.jsonl` / etc.

Sub-agents: trellis-implement, trellis-check, trellis-research under .claude/agents/. Skills: trellis-brainstorm, trellis-before-dev, trellis-check, trellis-update-spec, trellis-break-loop under .claude/skills/. Commands: start, finish-work, continue under .claude/commands/trellis/.

Cursor

trellis init -u your-name --cursor

Cursor is a full class-1 platform: real hooks, real sub-agents, real skills. Layout:

.cursor/commands/trellis-{name}.md: start, finish-work, continue (flat file naming with trellis- prefix, invoked as /trellis-start etc.)
.cursor/skills/trellis-{name}/SKILL.md: the trellis skills
.cursor/agents/: trellis-implement.md, trellis-check.md, trellis-research.md
.cursor/hooks/: shared Python hook scripts (Claude-Code-compatible)
.cursor/hooks.json: hook configuration (Cursor uses a separate file, not settings.json)

OpenCode

trellis init -u your-name --opencode

OpenCode 1.2.x is a class-1 platform (real hooks + real sub-agents):

.opencode/commands/trellis/: start / finish-work / continue
.opencode/agents/: trellis-implement.md, trellis-check.md, trellis-research.md
.opencode/skills/: the trellis skills
.opencode/plugins/: JS plugins: session-start.js, inject-subagent-context.js, inject-workflow-state.js, inject-spec-context.js
.opencode/hooks/inject-spec-context.py: shared path matching, budgets, and delivery state

Plugins are factory functions (OpenCode 1.2+). Dynamic spec loading intercepts write, edit, and apply_patch; a newly matched full spec blocks the first mutation as a model-visible tool error, then the retry proceeds.

Codex

trellis init -u your-name --codex

Layout:

AGENTS.md (repo root): entry file; Codex auto-reads it every session (acts as the prelude)
.agents/skills/trellis-{name}/SKILL.md: the trellis skills (shared layer; Codex reads it natively)
.codex/skills/: created empty, for skills you add yourself
.codex/agents/: TOML sub-agents: trellis-implement.toml, trellis-check.toml, trellis-research.toml
.codex/hooks/inject-workflow-state.py + .codex/hooks.json: UserPromptSubmit workflow-state hook
.codex/hooks/session-start.py: retained compact SessionStart compatibility script, not wired by default

Codex hooks must be enabled, or typing / in the chat won’t surface Trellis’s three commands (/start, /finish-work, /continue) and you can’t launch a session with /start. Add to ~/.codex/config.toml:

[features]
hooks = true   # Codex 0.129+. Older versions: `codex_hooks = true`.

Codex 0.129+ also gates each installed hook behind a one-time /hooks TUI review — run /hooks once in Codex and approve the Trellis UserPromptSubmit hook, otherwise the hooks stay inactive, Trellis’s commands/skills won’t appear in the / menu, and the workflow breadcrumb won’t auto-inject. Without these two steps Codex runs prelude-only (reads AGENTS.md every session): the context is still there, but you can’t invoke Trellis commands from /.

Kiro

trellis init -u your-name --kiro

Layout:

.kiro/agents/trellis.json: main Trellis agent — per-turn userPromptSubmit hook + session-start agentSpawn hook + .trellis/workflow.md as an always-loaded resource
.kiro/agents/trellis-{implement,check,research}.json: sub-agents (agentSpawn injects task context)
.kiro/hooks/*.py + .kiro/hooks/trellis-workflow-state.kiro.hook: the per-turn workflow-state injector (CLI agent hook + IDE .kiro.hook)
.kiro/skills/*/SKILL.md: auto-trigger skills

Enable it (required — otherwise the workflow won’t activate):

Kiro CLI: make trellis the active agent so its hooks fire — kiro-cli settings chat.defaultAgent trellis (persists) or /agent swap trellis (per session). Kiro otherwise runs the built-in kiro_default agent.
Kiro IDE: the .kiro/hooks/trellis-workflow-state.kiro.hook (a promptSubmit hook) ships enabled; confirm it’s on/trusted in Kiro’s Agent Hooks UI.

The per-turn injection prints plain text that Kiro adds to the conversation context, per Kiro’s official hooks docs. The exact stdout-to-context behavior (and whether the IDE runCommand action injects stdout) is pending verification on real Kiro hardware; if it doesn’t, the fallback is a static steering nudge.

Gemini CLI

trellis init -u your-name --gemini

Layout:

.gemini/commands/trellis/{name}.toml: TOML command files — start.toml, finish-work.toml, continue.toml
.agents/skills/trellis-{name}/SKILL.md: the trellis skills (shared layer; Gemini CLI 0.40+ reads it natively)
.gemini/agents/{name}.md: sub-agent definitions with pull-based prelude (sub-agents Read their own JSONL because Gemini has no sub-agent PreToolUse hook)
.gemini/hooks/session-start.py: SessionStart hook
.gemini/settings.json: hook configuration (SessionStart only)

Qoder

trellis init -u your-name --qoder

Qoder supports native Custom Commands (typed with / in the agent input, stored under <project>/.qoder/commands/{name}.md with required name + description YAML frontmatter). Trellis delivers session-boundary entry points there so you can invoke them deterministically, and keeps the phase-level workflows as auto-trigger skills. Layout:

.qoder/commands/trellis-{name}.md: session-boundary commands — finish-work, continue — invoked as /trellis-finish-work, /trellis-continue (Qoder’s SessionStart hook already injects the “start” context, so there is no trellis-start command)
.qoder/skills/trellis-{name}/SKILL.md: auto-trigger workflow skills — brainstorm, before-dev, check, update-spec, break-loop
.qoder/agents/{name}.md: sub-agent definitions with pull-based prelude
.qoder/hooks/session-start.py: SessionStart hook
.qoder/settings.json: hook configuration (SessionStart only — Qoder has no sub-agent PreToolUse hook)

CodeBuddy

trellis init -u your-name --codebuddy

CodeBuddy is a full class-1 platform (real hooks + real sub-agents). Layout:

.codebuddy/commands/trellis/{name}.md: start, finish-work, continue
.codebuddy/skills/trellis-{name}/SKILL.md: the trellis skills
.codebuddy/agents/{name}.md: sub-agent definitions
.codebuddy/hooks/*.py: shared Python hook scripts
.codebuddy/settings.json: hook configuration (SessionStart + PreToolUse sub-agent injection)

GitHub Copilot

trellis init -u your-name --copilot

Layout:

.github/copilot-instructions.md: the Trellis prelude, loaded automatically every session
.github/prompts/trellis-{name}.prompt.md: prompt files for start / finish-work / continue
.github/skills/trellis-{name}/SKILL.md: the trellis skills
.github/agents/{name}.agent.md: sub-agent definitions with pull-based prelude (Copilot’s sub-agent hook does not fire reliably, so sub-agents Read their own JSONL)
.github/copilot/hooks/*.py: Copilot-specific + shared Python hook scripts
.github/copilot/hooks.json: hook configuration (SessionStart only — sub-agent PreToolUse is absent)

Droid

trellis init -u your-name --droid

Droid (factory.ai) is a class-1 platform with hooks + sub-agents:

.factory/commands/trellis/: start / finish-work / continue
.factory/droids/: the three trellis-* sub-agents
.factory/skills/: the trellis skills
.factory/hooks/: SessionStart + sub-agent injection

Pi Agent

trellis init -u your-name --pi

Pi Agent is extension-backed rather than Python-hook-backed. Trellis writes the same workflow primitives, then the extension resolves the current session id and injects task context before Bash commands and sub-agent runs. Layout:

.pi/prompts/trellis-{name}.md: session-boundary prompts (finish-work, continue; start only where applicable)
.agents/skills/trellis-{name}/SKILL.md: the five Trellis workflow skills (shared layer; Pi reads it natively)
.pi/agents/{name}.md: trellis-implement, trellis-check, trellis-research
.pi/extensions/trellis/index.ts: session context, Bash TRELLIS_CONTEXT_ID propagation, and sub-agent JSONL injection
.pi/settings.json: extension registration

The extension stores active task state under .trellis/.runtime/sessions/<session-key>.json, so each Pi window/session can work on its own task without taking over another window.

Oh My Pi

trellis init -u your-name --omp

Oh My Pi is extension-backed, like Pi Agent. Trellis writes the same workflow primitives, then the extension resolves the current session id and injects task context before Bash commands and sub-agent runs. Unlike Pi Agent, Oh My Pi has no settings.json — the native provider auto-discovers all subdirectories under .omp/. Layout:

.omp/commands/trellis-{name}.md: session-boundary prompts (finish-work, continue; start only where applicable)
.omp/skills/trellis-{name}/SKILL.md: the five Trellis workflow skills
.omp/agents/{name}.md: trellis-implement, trellis-check, trellis-research
.omp/extensions/trellis/index.ts: session context, Bash TRELLIS_CONTEXT_ID propagation, and sub-agent JSONL injection

The extension stores active task state under .trellis/.runtime/sessions/<session-key>.json, so each Oh My Pi window/session can work on its own task without taking over another window.

Other supported platforms

Trellis also ships configurators for platforms not covered by the capability matrix:

Kilo (--kilo): writes .kilocode/workflows/ (commands: start, finish-work) and .kilocode/skills/trellis-{name}/SKILL.md (the trellis skills). No hook integration.
Antigravity (--antigravity): writes Antigravity-native workflow files for the three commands.
Devin (--devin, formerly Windsurf): writes Devin-native workflow and skill files. The old --windsurf flag still works as a deprecated alias.
Reasonix (--reasonix): writes .reasonix/ skills and sub-agents; commands are invoked as /skill trellis-{name}. No hook integration, so the sub-agent loads its own task context.
ZCode (--zcode): writes .zcode/agents/, .zcode/commands/, .zcode/skills/, and .zcode/hooks/. Commands use the /trellis: prefix.
Trae (--trae): writes .trae/ agents, commands, skills, and Python hooks (SessionStart, workflow-state, sub-agent context injection).
Grok Build (--grok): writes .grok/skills/, .grok/commands/, .grok/agents/. Sub-agents are dispatched with spawn_subagent. No hook integration.
Kimi Code (--kimi): writes skills to .kimi-code/skills/ plus the shared .agents/skills/ layer; entry points are invoked as /skill:trellis-{name}. No project-level hooks (Kimi only supports a user-level ~/.kimi-code/config.toml).
Snow CLI (--snow): writes .snow/skills/, .snow/commands/, .snow/agents/, and .snow/hooks/ (Python hooks emit additionalContext JSON for session / user / sub-agent events).

Beyond the 21 configured platforms, Trellis can be consumed by any AI coding agent that follows the .agents/skills/ convention (the agentskills.io standard). Codex writes its skills there, and the files are directly usable by other agents in that ecosystem (Amp, Cline, Deep Agents, Firebender, Warp, and more). On those platforms you manage Trellis through the .trellis/ core plus whatever prelude file the agent reads.

Operating Systems

OS	Status	Notes
macOS	✅ Full	Primary platform
Linux	✅ Full	Verified
Windows	✅ Full	Scripts are Python; Claude Code sets `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1` so hooks cwd resolves correctly

Python 3.9+ is required for .trellis/scripts/ and any Python hooks. OpenCode plugins use Node.js 18+.

Multi-Developer Collaboration

Per-developer isolation (no conflicts):

.trellis/workspace/{name}/: each developer’s own journals and index
.trellis/.developer: gitignored
.trellis/.runtime/: gitignored session runtime; each AI session/window has its own active task file

Shared state (coordinate via PR):

.trellis/spec/: team conventions, PR-reviewed like any code
.trellis/tasks/: task JSONs; explicit --assignee avoids collisions

Important spec changes should be discussed in reviews; treat the spec library as team code.

`trellis update` and Version Management

cat .trellis/.version          # current version
trellis update                  # update to latest
trellis update --dry-run        # preview
trellis update --migrate        # apply breaking-change migrations (required for major)
trellis update -f               # force overwrite locally-modified files
trellis update -s               # skip locally-modified files

Template hash mechanism (.trellis/.template-hashes.json):

Compute local file hash.
Compare against recorded template hash.
Match ⇒ file unchanged by user ⇒ safe to update.
Differ ⇒ prompt (overwrite / skip), or silently respect policy with -f / -s.

Breaking changes (for example, removing the Multi-Agent Pipeline in 0.5.0) ship as migration manifests: running trellis update without --migrate on a breaking-manifest exits with instructions instead of silently renaming files. trellis update --migrate applies the rename / delete entries, asking once per conflict.

Start Here

Advanced

Use Cases

Resource Marketplace

Community

Multi-Platform and Team Configuration