> ## 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.

# Quickstart

> Set up Trellis in your project

## 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:

```bash theme={null}
npm install -g @mindfoldhq/trellis
```

Then initialize in your project:

```bash theme={null}
trellis init
```

<Tip>
  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).
</Tip>

### Platform selection

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

```bash theme={null}
# 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

```bash theme={null}
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:

```bash theme={null}
npm install -g @mindfoldhq/trellis
trellis update
```

Useful update flags:

```bash theme={null}
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:

```bash theme={null}
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:

<CodeGroup>
  ```markdown Backend spec example theme={null}
  # 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

  ```
</CodeGroup>

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

<CardGroup cols={2}>
  <Card title="Core concepts" icon="book" href="/concepts/overview">
    Learn how specs, tasks, and workspaces work together.
  </Card>

  <Card title="Write better specs" icon="pencil" href="/guides/specs">
    Tips for writing specs that AI actually follows.
  </Card>

  <Card title="Commands" icon="terminal" href="/guides/commands">
    Slash commands for common workflows.
  </Card>
</CardGroup>

```
```