Quick Start
2.1 Installation
# Global install
npm install -g @mindfoldhq/trellis@latest
# Navigate to your project directory
cd your-project
OS Requirements: Mac, Linux, and Windows are fully supported. All scripts have been migrated to Python for cross-platform compatibility.
- Claude Code
- Cursor
- Codex
- OpenCode
- Kilo
- Kiro
trellis init -u your-name
.claude/ directory (commands, agents, hooks).trellis init -u your-name
.cursor/commands/ directory.trellis init --codex -u your-name
AGENTS.md and .agents/skills/.trellis init --opencode -u your-name
.agents/skills/. Supports session hook for automatic context injection.trellis init --kilo -u your-name
.kilocode/ directory (workflows, rules, skills).trellis init --kiro -u your-name
.kiro/ directory (steering, hooks, prompts).your-name becomes your developer identity and creates your personal workspace at .trellis/workspace/your-name/.
2.2 Platform Configuration
trellis init automatically detects and configures installed platforms:
| Platform | Config Directory | Command Format |
|---|---|---|
| Claude Code | .claude/commands/trellis/, .claude/agents/, .claude/hooks/ | /start |
| Cursor | .cursor/commands/*.md | /start |
| Codex | AGENTS.md, .agents/skills/ | $start |
| OpenCode | .agents/skills/ | /start |
| Kilo | .kilocode/workflows/, .kilocode/rules/, .kilocode/skills/ | /start.md |
| Kiro | .kiro/steering/, .kiro/hooks/, .kiro/prompts/ | @start |
Platform Capability Comparison
| Capability | Claude Code | Cursor | Codex | OpenCode | Kilo | Kiro |
|---|---|---|---|---|---|---|
| Session auto-injection | ✅ Hook | ❌ Manual /start | ⚡ AGENTS.md | ✅ Hook | ⚡ rules/ + launchConfig | ⚡ steering/ |
| Sub-Agent spec injection | ✅ PreToolUse Hook | ❌ | ❌ | ❌ | ⚡ Orchestrator Mode | ⚡ Custom Agents |
| Ralph Loop quality gate | ✅ SubagentStop Hook | ❌ | ❌ | ❌ | ❌ | ⚡ Agent Hooks |
| Multi-Agent Pipeline | ✅ | ❌ | ❌ | ❌ | ✅ Orchestrator + worktree | ✅ Autonomous Agent |
| Number of commands | 13 | 12 | 13 | 13 | workflows | prompts |
2.3 Three Steps to Get Started
- Claude Code
- Cursor
- Codex
- OpenCode
- Kilo
- Kiro
# Step 1: Open the Claude Code terminal
# Hook auto-injects context — you can describe your task directly (or run /start to see the full flow)
# Step 2: Describe what you want to do
"Add user login feature"
# Step 3: AI works automatically
# AI reads specs → creates task → invokes Agent to implement → self-checks
# Once done, you test, commit, and record the session
# Step 1: Open Cursor, you must first run
/start
# Step 2: Describe what you want to do
"Add user login feature"
# Step 3: AI works automatically
# AI reads specs → creates task → implements → you manually run /trellis-check-backend to check
# Once done, you test, commit, and record the session
# Step 1: Codex provides base context via AGENTS.md
# Run $start for full context
# Step 2: Describe what you want to do
"Add user login feature"
# Step 3: AI works automatically
# Once done, you test, commit, and record the session
# Step 1: Open the OpenCode terminal
# Hook auto-injects context — you can describe your task directly (or run /start to see the full flow)
# Step 2: Describe what you want to do
"Add user login feature"
# Step 3: AI works automatically
# Once done, you test, commit, and record the session
# Step 1: Kilo auto-loads project specs via .kilocode/rules/
# Run the /start.md workflow for full context
# Step 2: Describe what you want to do
"Add user login feature"
# Step 3: AI works automatically
# Kilo Orchestrator Mode breaks down tasks and assigns them to Code/Architect modes
# Once done, you test, commit, and record the session
# Step 1: Kiro auto-loads project specs via .kiro/steering/
# Choose Spec mode to generate requirements → design → tasks
# Step 2: Describe what you want to do
"Add user login feature"
# Step 3: AI works automatically
# Kiro implements step by step following the tasks.md checklist
# Agent Hooks can auto-trigger checks on file save
# Once done, you test, commit, and record the session
2.4 Full Directory Structure
your-project/
├── .trellis/ # Trellis core directory
│ ├── .developer # Developer identity (gitignored)
│ ├── .current-task # Active task pointer
│ ├── .version # Trellis version number
│ ├── .template-hashes.json # Template file hashes (for update)
│ ├── workflow.md # Development workflow guide
│ ├── worktree.yaml # Multi-Agent worktree config
│ │
│ ├── spec/ # Project spec library
│ │ ├── frontend/ # Frontend specs
│ │ │ ├── index.md # Spec index
│ │ │ ├── component-guidelines.md
│ │ │ ├── hook-guidelines.md
│ │ │ ├── state-management.md
│ │ │ ├── type-safety.md
│ │ │ ├── quality-guidelines.md
│ │ │ └── directory-structure.md
│ │ ├── backend/ # Backend specs
│ │ │ ├── index.md
│ │ │ ├── database-guidelines.md
│ │ │ ├── error-handling.md
│ │ │ ├── logging-guidelines.md
│ │ │ ├── quality-guidelines.md
│ │ │ └── directory-structure.md
│ │ └── guides/ # Thinking guides
│ │ ├── index.md
│ │ ├── cross-layer-thinking-guide.md
│ │ └── code-reuse-thinking-guide.md
│ │
│ ├── workspace/ # Developer workspace
│ │ ├── index.md # Workspace master index
│ │ └── {developer-name}/ # Per-developer directory
│ │ ├── index.md # Personal index
│ │ └── journal-N.md # Session journal
│ │
│ ├── tasks/ # Task directory
│ │ ├── {MM-DD-task-name}/ # Active tasks
│ │ │ ├── task.json # Task metadata
│ │ │ ├── prd.md # Requirements document
│ │ │ ├── info.md # Technical design (optional)
│ │ │ ├── implement.jsonl # Implement Agent context
│ │ │ ├── check.jsonl # Check Agent context
│ │ │ └── debug.jsonl # Debug Agent context
│ │ └── archive/ # Archived tasks
│ │ └── {YYYY-MM}/
│ │
│ └── scripts/ # Automation scripts
│ ├── task.py # Task management (14 subcommands)
│ ├── get-context.py # Get session context
│ ├── get-developer.py # Get developer identity
│ ├── init-developer.py # Initialize developer
│ ├── add-session.py # Record session
│ ├── common/ # Shared libraries
│ │ ├── paths.py
│ │ ├── developer.py
│ │ ├── git-context.py
│ │ ├── task-utils.py
│ │ ├── task-queue.py
│ │ ├── phase.py
│ │ ├── registry.py
│ │ └── worktree.py
│ └── multi-agent/ # Parallel development scripts
│ ├── plan.py
│ ├── start.py
│ ├── status.py
│ ├── create-pr.py
│ └── cleanup.py
│
├── .claude/ # Claude Code configuration
│ ├── settings.json # Hook and permission config
│ ├── commands/ # Slash commands
│ │ └── trellis/ # Trellis command set
│ │ ├── start.md
│ │ ├── parallel.md
│ │ ├── record-session.md
│ │ ├── finish-work.md
│ │ ├── onboard.md
│ │ ├── before-backend-dev.md
│ │ ├── before-frontend-dev.md
│ │ ├── check-backend.md
│ │ ├── check-frontend.md
│ │ ├── check-cross-layer.md
│ │ ├── break-loop.md
│ │ ├── create-command.md
│ │ └── integrate-skill.md
│ ├── agents/ # Agent definitions
│ │ ├── dispatch.md
│ │ ├── plan.md
│ │ ├── implement.md
│ │ ├── check.md
│ │ ├── debug.md
│ │ └── research.md
│ ├── hooks/ # Hook scripts
│ │ ├── session-start.py
│ │ ├── inject-subagent-context.py
│ │ └── ralph-loop.py
│ └── skills/ # Skill directory
│
├── .cursor/ # Cursor configuration
│ └── commands/
│ └── trellis-*.md # Cursor command set
│
├── AGENTS.md # Codex entry file
├── .agents/ # Agent Skills (Codex / OpenCode)
│ └── skills/
│
├── .kilocode/ # Kilo Code configuration
│ ├── rules/ # Project rules (all modes)
│ ├── workflows/ # Workflow commands
│ └── skills/ # Agent Skills
│
└── .kiro/ # Kiro configuration
├── steering/ # Project context (Steering system)
├── hooks/ # Agent Hooks (event-driven automation)
├── prompts/ # Custom prompts
└── specs/ # Spec-Driven Development docs