Trellis ships on 13 platforms (Claude Code, Cursor, OpenCode, Codex, Kiro, Kilo, Gemini CLI, Antigravity, Windsurf, Qoder, CodeBuddy, GitHub Copilot, Droid) and additionally supports any AI coding agent that reads the .agents/skills/ standard (Amp, Cline, Deep Agents, Firebender, Kimi Code CLI, Warp, and more). The .trellis/ core is identical everywhere; what differs is how hooks, 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 |
- 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, opening a new session auto-injects Trellis context. On platforms without hooks, run /trellis:start (or @trellis:start on Kiro).
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 |
|---|
| SessionStart hook (auto-inject) | โ
| โ
| โ
| โก | โก | โ
| โ
| โ
| โ
| โ
|
| Sub-agent PreToolUse hook | โ
| โ
| โ
| โ | โ | โ | โ | โ
| โ | โ
|
Sub-agents (trellis-*) | โ
| โ
| โ
| โ
| โ
| โ
| โ
| โ
| โ
| โ
|
| Auto-trigger skills | โ
| โ
| โ
| โ
| โ
| โ
| โ
| โ
| โ
| โ
|
Explicit /trellis:* commands | โ
| โ
| โ
| โ | โ | โ
| โ | โ
| โ
| โ
|
codex_hooks = true opt-in; Kiroโs Agent Hooks are user-configured, not auto-executed) ยท โ the platform does not expose this event ยท โ the platform has no command primitive; start / finish-work / continue are delivered as skills instead
.kilocode/, .agent/ (Antigravity), and .windsurf/ 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. |
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/.
trellis init -u your-name --cursor
.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 5 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/commands/trellis/: start / finish-work / continue.opencode/agents/: trellis-implement.md, trellis-check.md, trellis-research.md.opencode/skills/: the 5 trellis skills.opencode/plugins/: JS plugins: session-start.js, inject-subagent-context.js, inject-workflow-state.js
Plugins are factory functions (OpenCode 1.2+). Trellis generates them so behavior parity with Claude Code is the goal.
trellis init -u your-name --codex
AGENTS.md (repo root): entry file; Codex auto-reads it every session (acts as the prelude).codex/prompts/: trellis-start.md, trellis-finish-work.md, trellis-continue.md.codex/skills/: the 5 trellis skills.codex/agents/: TOML sub-agents: trellis-implement.toml, trellis-check.toml, trellis-research.toml.codex/hooks/session-start.py + .codex/hooks.json: SessionStart hook (experimental)
Codex hooks are experimental. Enable by adding to ~/.codex/config.toml:[features]
codex_hooks = true
AGENTS.md every session): same content, just no event-driven injection. trellis init -u your-name --kiro
.kiro/steering/trellis.md: Trellis prelude, loaded every session.kiro/prompts/trellis-*.md: prompt-style commands.kiro/skills/*/SKILL.md: auto-trigger skills (Kiro matches by description/YAML)
Kiroโs Agent Hooks can auto-run Trellis skills on file save or build success, but thatโs user-configured; Trellis doesnโt install any Kiro Agent Hook out of the box.
Gemini CLI
trellis init -u your-name --gemini
.gemini/commands/trellis/{name}.toml: TOML command files โ start.toml, finish-work.toml, continue.toml.gemini/skills/trellis-{name}/SKILL.md: the 5 trellis skills.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)
trellis init -u your-name --qoder
/ in the agent input, stored under ~/.qoder/commands/ or <project>/.qoder/commands/), but Trellisโs design choice is to deliver everything as auto-trigger skills on Qoder, leaving .qoder/commands/ free for your own custom commands.
Layout:
.qoder/skills/trellis-{name}/SKILL.md: all templates (start, finish-work, continue, brainstorm, before-dev, check, update-spec, break-loop) delivered as skills; skill matching drives everything.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/commands/trellis/{name}.md: start, finish-work, continue.codebuddy/skills/trellis-{name}/SKILL.md: the 5 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
.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 5 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)
trellis init -u your-name --droid
.factory/commands/trellis/: start / finish-work / continue.factory/agents/: the three trellis-* sub-agents.factory/skills/: the five trellis skills.factory/hooks/: SessionStart + sub-agent injection
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 5 trellis skills). No hook integration.
- Antigravity (
--antigravity): writes Antigravity-native workflow files for the three commands.
- Windsurf (
--windsurf): writes Windsurf-native command and rule files.
Beyond the 13 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, Kimi Code CLI, 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 |
.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/.current-task: gitignored
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
.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 (e.g. 0.5.0-beta.0โs Multi-Agent Pipeline removal) 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.
