Quickstart

Prerequisites

Requirement	Minimum	Why
Node.js	18	`trellis` CLI runtime
Python	3.9	Hooks and automation scripts (`python` on Windows, `python3` on macOS/Linux)
git	any recent	Task branching, worktrees, and commit metadata

trellis init checks the same Python command it will render into generated files: python --version on Windows, python3 --version on macOS/Linux. If that command is older than 3.9, init warns but does not block.

Install Trellis

First, install the CLI globally:

npm install -g @mindfoldhq/trellis

Then initialize in your project:

trellis init

Trellis uses your name to create a personal workspace directory. If you don’t specify -u, it will automatically detect from git config user.name.To specify manually: trellis init -u john (replace john with your actual name).

Platform selection

By default, trellis init sets up for Claude Code. To include other platforms:

# Include Cursor support
trellis init --cursor

# Include multiple platforms
trellis init --cursor --pi

# All available platform flags
trellis init --claude       # Claude Code (default)
trellis init --cursor       # Cursor IDE
trellis init --opencode     # OpenCode
trellis init --codex        # Codex
trellis init --kiro         # Kiro
trellis init --gemini       # Gemini CLI
trellis init --qoder        # Qoder
trellis init --codebuddy    # CodeBuddy
trellis init --copilot      # GitHub Copilot
trellis init --droid        # Factory Droid
trellis init --pi           # Pi Agent
trellis init --kilo         # Kilo
trellis init --antigravity  # Antigravity
trellis init --devin        # Devin (formerly Windsurf)

Other useful flags

trellis init -t electron-fullstack   # Use a spec template
trellis init --overwrite             # Overwrite existing specs when using template
trellis init --append                # Only add missing files from template

What gets created

This creates a .trellis/ directory with the default structure:

.trellis/
├── workflow.md          # How the workflow works
├── spec/                # Your coding conventions
│   ├── frontend/
│   ├── backend/
│   └── guides/
├── workspace/           # Session journals
└── tasks/               # Task tracking

For Claude Code, it also sets up .claude/ with hooks, skills, agents, and session-boundary commands. For other platforms, it creates the corresponding config directory (.cursor/, .opencode/, .codex/, .pi/, .agents/, etc.).

Updating Trellis

When a new version is released:

npm install -g @mindfoldhq/trellis
trellis update

Useful update flags:

trellis update --dry-run     # Preview changes without applying
trellis update --force       # Overwrite all managed files
trellis update --migrate     # Run file migrations (renames, deletes)

trellis update only touches unmodified files. Your customizations stay intact. A timestamped backup is created automatically before any changes.

Uninstalling Trellis

To remove every file Trellis wrote into a project — .trellis/ itself plus the platform-specific files under .claude/, .cursor/, .codex/, .pi/, etc. — run:

trellis uninstall              # interactive: lists what will be deleted/modified, asks Continue?
trellis uninstall --dry-run    # only print the plan, change nothing
trellis uninstall --yes        # skip the prompt (for scripts)

Trellis only removes files it tracks in .trellis/.template-hashes.json. Files you added under managed directories (e.g. your own hook scripts under .claude/hooks/) are never deleted. Structured config files such as .claude/settings.json keep your custom fields; only the trellis-owned hook entries are stripped.

Write your first spec

Open .trellis/spec/backend/index.md (or frontend/ if that’s your focus) and fill in the template. Here’s what a real spec looks like:

# Backend Guidelines

## Error Handling

All API endpoints return errors in this format:

{ "error": { "code": "VALIDATION_ERROR", "message": "Email is required" } }

Use AppError class from src/lib/errors.ts. Don't throw raw Error objects.

## Database

- Table names: snake_case, plural (user_sessions, not UserSession)
- Always include created_at and updated_at timestamps
- Foreign keys: {table}\_id format

Be specific. Include file paths. Show actual code from your project. Vague guidelines don’t help.

Test it

Start a new Claude Code session and ask it to write some code. Check if it follows your specs. If it doesn’t, your specs probably aren’t specific enough. Add more examples.

What’s next

Core concepts

Learn how specs, tasks, and workspaces work together.

Write better specs

Tips for writing specs that AI actually follows.

Commands

Slash commands for common workflows.

Start Here

Advanced

Use Cases

Resource Marketplace

Community

Prerequisites

Install Trellis

Platform selection

Other useful flags

What gets created

Updating Trellis

Uninstalling Trellis

Write your first spec

Test it

What’s next

Core concepts

Write better specs

Commands

​Prerequisites

​Install Trellis

​Platform selection

​Other useful flags

​What gets created

​Updating Trellis

​Uninstalling Trellis

​Write your first spec

​Test it

​What’s next

Core concepts

Write better specs

Commands

Prerequisites

Install Trellis

Platform selection

Other useful flags

What gets created

Updating Trellis

Uninstalling Trellis

Write your first spec

Test it

What’s next