> ## Documentation Index
> Fetch the complete documentation index at: https://lizamas.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Initialize a Liza Project with liza init: Complete Guide

> Run liza init in your project directory to create contract symlinks, provider hooks, state.yaml, and the integration branch for a Liza coding session.

After running `liza setup` globally, run `liza init` inside each repository where you want Liza active. This command creates the `.liza/` directory, wires up contract discovery files and provider hooks, establishes project state, and — when you supply a goal — creates the integration branch that agents merge approved work into.

## What `liza init` Does

`liza init` bridges the global contracts in `~/.liza/` with the specific project you are working in. It writes or updates files at three levels: the project root (contract discovery files), provider config directories (hooks and settings), and the `.liza/` workspace directory (state and pipeline configuration).

> [card] Contract Discovery Files
>
> Creates `CLAUDE.md`, `AGENTS.md`, or `GEMINI.md` at the project root — usually as symlinks to `~/.liza/CORE.md` — so provider CLIs find the behavioral contract automatically.

> [card] Provider Hooks & Settings
>
> Writes `.claude/settings.json`, `.claude/hooks/`, `.codex/hooks.json`, and related files that enforce session initialization, inject project context, and guard Git usage.

> [card] Project State
>
> Creates `.liza/state.yaml` and `.liza/pipeline.yaml` — the runtime configuration files you tune to match your task size, team cadence, and infrastructure.

> [card] Integration Branch
>
> Creates the configured integration branch. Liza merges approved tasks here. Pushing that branch to a remote is your responsibility.

## Command Syntax

```bash theme={null}
liza init                                       # interactive wizard
liza init --claude --codex                      # non-interactive with providers
liza init --opencode                            # OpenCode provider
liza init "Project goal" --spec specs/vision.md # multi-agent run with spec file
liza init "Project goal" --claude --codex       # non-interactive with goal
```

**1. Run the interactive wizard or pass flags**

Run `liza init` with no flags to walk through provider selection, mode selection, and project-local activation interactively. Pass `--claude`, `--codex`, or `--opencode` to skip the prompts and activate those providers directly.

**2. Supply a goal for multi-agent mode**

Pass a description string and optionally `--spec <file>` to initialize Liza for a full multi-agent pipeline run. Liza writes the planning spec reference into `.liza/state.yaml` and prepares the integration branch.

**3. Customize state.yaml**

After init, open `.liza/state.yaml` and tune the `config` section to match your project's task size and infrastructure. See the configuration matrix below.

**4. Customize GUARDRAILS.md**

Edit the `GUARDRAILS.md` placeholder that `liza init` creates. This file lets you define project-specific agent constraints that override or extend the global contract.

## What Gets Created

Running `liza init --claude --codex` in a project produces:

```text theme={null}
<project>/
├── CLAUDE.md                      # symlink → ~/.liza/CORE.md (or fallback)
├── AGENTS.md                      # symlink → ~/.liza/CORE.md (or fallback)
├── GUARDRAILS.md                  # project-specific constraint placeholder
├── .claudeignore                  # created when absent
├── .claude/
│   ├── settings.json              # auto-managed; do not hand-craft a subset
│   └── hooks/                     # session init, context inject, Git guards
├── .codex/
│   ├── config.toml                # project-local Codex hook activation
│   └── hooks.json                 # Codex hook definitions
└── .liza/
    ├── state.yaml                 # runtime configuration and task state
    ├── pipeline.yaml              # pipeline definition
    └── log.yaml                   # agent activity log
```

> [!NOTE]
>
> `.claude/settings.json` is generated from Liza's embedded template and includes all required permissions for Liza CLI commands, skills, and Git operations. Do not hand-craft a subset of this file — missing permissions will block agents at runtime.

## The Interactive Wizard

When you run `liza init` with no flags, the wizard prompts you for:

* **Providers** — which coding agent CLIs to activate (Claude, Codex, OpenCode)
* **Mode** — Pairing mode (single agent + human) or Multi-Agent mode (autonomous pipeline)
* **Goal** — a description of what you want to build, used as the pipeline seed for multi-agent runs

You can always re-run `liza init` later with specific flags to activate additional providers without re-running the full wizard.

## GUARDRAILS.md

`liza init` creates a `GUARDRAILS.md` placeholder at the project root. This file is optional but powerful — it lets you define project-specific agent constraints that supplement or override the global behavioral contracts.

GUARDRAILS.md supports **Tier 0–3 overrides**, letting you tune agent autonomy, permitted file paths, allowed commands, and escalation rules per project. Leave it as the generated placeholder if you have no project-specific constraints; agents will read it and find no additional restrictions.

> [!TIP]
>
> For regulated codebases, sensitive data environments, or monorepos with multiple team boundaries, invest time in `GUARDRAILS.md` before your first multi-agent run. It is your primary lever for constraining what agents can touch.

## Brownfield Projects

`liza init` respects existing contract files. If your repository already has its own `CLAUDE.md`, `AGENTS.md`, or `GEMINI.md`, Liza does not overwrite them. It falls back to a global symlink instead:

| Existing repo-root file | Global fallback created |
| - | - |
| `CLAUDE.md` | `~/.claude/CLAUDE.md` |
| `AGENTS.md` (Codex) | `~/.codex/AGENTS.md` |
| `AGENTS.md` (OpenCode) | `~/.config/opencode/AGENTS.md` |
| `GEMINI.md` | `~/.gemini/GEMINI.md` |

If both the repo-root file and the global fallback are non-Liza files, `liza init` warns and skips that provider activation path. If a Liza symlink already exists at either location, `liza init` reports it and does not create a duplicate.

## The Integration Branch

`liza init` creates the integration branch that Liza uses as the merge target for approved tasks. During a multi-agent run, every task that passes review gets merged into this branch automatically.

The integration branch is local-only after `liza init`. Pushing it to a remote — and any CI/CD integration — is your responsibility. Liza never pushes to a remote on your behalf.

## Configuration Matrix

All tunable parameters live under the `config` section of `.liza/state.yaml`. Edit this file directly after `liza init` to adjust Liza's behavior for your project.

| Parameter | Default | Unit | Purpose |
| - | - | - | - |
| `heartbeat_interval` | `60` | seconds | How often agents write heartbeats; lower values detect crashes faster |
| `lease_duration` | `1800` | seconds | How long an agent holds a task claim before it expires |
| `agent_progress_timeout` | `1800` | seconds | Max time without observable progress before the supervisor blocks the task |
| `max_coder_iterations` | `10` | count | Max implementation iterations per coder per task |
| `max_review_cycles` | `5` | count | Max review rejection cycles before a task is escalated |
| `doer_max_wait` | `18000` | seconds | Max idle time before a doer-role supervisor exits |
| `post_worktree_cmd` | (none) | shell cmd | Command run after every worktree creation — use for `npm install`, `go mod download`, etc. |
| `copy_worktree_env_files` | `false` | boolean | Authorize copying root-level `.env` files into task worktrees |
| `default_cli` | (none) | CLI name | Global default agent CLI when no role-specific default is set |
| `default_doer_cli` | (none) | CLI name | Default CLI for coders and orchestrators |
| `default_reviewer_cli` | (none) | CLI name | Default CLI for reviewers |
| `codex_package_version` | (none) | npm version | Pins headless Codex agents to `@openai/codex@<version>` |
| `auto_checkpoint_summary` | `true` | boolean | Auto-run checkpoint-summary skill after successful merges |

### Agent Execution Timeouts

These timeouts are enforced by the supervisor and are not directly configurable per agent, but they inform how you tune `agent_progress_timeout` and `lease_duration`:

| Role | Timeout | Rationale |
| - | - | - |
| Code Reviewer | 30 min | Reviews should complete quickly |
| Coder | 2 hours | Implementation takes longer |
| Planner | 4 hours | Complex planning needs time |

When a timeout is exceeded, the supervisor kills the CLI, resets the agent to IDLE, and retries after a 5-second delay.

### Worktree Setup with `post_worktree_cmd`

Worktrees are bare checkouts — they do not contain build artifacts like `node_modules/` or `vendor/`. Set `post_worktree_cmd` to a shell command that runs after every worktree creation so agents start with a build-ready workspace:

```bash theme={null}
# At init time
liza init "Project goal" --post-worktree-cmd "npm install"

# Or directly in .liza/state.yaml after init
```

```yaml theme={null}
config:
  post_worktree_cmd: "npm install"
```

`liza init` auto-detects common Node.js lockfile patterns and suggests the appropriate install command. For monorepos with multiple subdirectories, it prompts for manual configuration.

| Lockfile detected | Suggested command |
| - | - |
| `pnpm-lock.yaml` | `pnpm install` |
| `yarn.lock` | `yarn install` |
| `bun.lockb` / `bun.lock` | `bun install` |
| `package-lock.json` (or none) | `npm install` |

### Tuning Presets

```yaml Short Tasks (< 10 min) theme={null}
config:
  heartbeat_interval: 30
  lease_duration: 900        # 15 min
  doer_max_wait: 600         # 10 min
  max_coder_iterations: 5    # escalate fast
```

```yaml Long Tasks (30 min – 5 hr) theme={null}
config:
  heartbeat_interval: 60
  lease_duration: 3600       # 1 hour
  doer_max_wait: 18000       # 5 hours
  max_coder_iterations: 15   # more iterations
```

```yaml Network Filesystems (NFS, SMB) theme={null}
config:
  heartbeat_interval: 90     # less frequent writes
  lease_duration: 2700       # 45 min
  # fsnotify may not work — agents fall back to polling
```

```yaml Fast Feedback / CI theme={null}
config:
  max_coder_iterations: 5    # escalate faster
  max_review_cycles: 3       # fewer rejection cycles
  heartbeat_interval: 30     # faster crash detection
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.