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

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.

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.

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.

Integration Branch

Creates the configured integration branch. Liza merges approved tasks here. Pushing that branch to a remote is your responsibility.

​

Command Syntax

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:

<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

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

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:

# At init time
liza init "Project goal" --post-worktree-cmd "npm install"

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

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

Short Tasks (< 10 min)

config:
  heartbeat_interval: 30
  lease_duration: 900        # 15 min
  doer_max_wait: 600         # 10 min
  max_coder_iterations: 5    # escalate fast