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

# Liza Quickstart: Install, Set Up, and Run Your First Session

> Install Liza, configure your providers, initialize a project, and launch your first coding session — from zero to running in under 10 minutes.

This guide walks you from zero to a running Liza session. You'll install the `liza` binary, configure it once for your machine, activate it in a project, and choose whether to start with hands-on Pairing or let the Multi-Agent pipeline run autonomously. The whole process takes under 10 minutes.

> [!NOTE]
>
> **Windows users:** Liza requires a Unix-like environment. Native Windows is not supported. Run all commands from a WSL2 shell. The install script will exit with an error if you run it from PowerShell, CMD, or Git Bash on Windows.

**1. Install Liza**

Run the install script from your macOS or Linux terminal (or WSL2 shell on Windows):

```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/liza-mas/liza/main/install.sh | bash
```

The script auto-detects your OS and architecture, downloads the correct pre-built binary, and installs it to `~/.local/bin` by default. If `~/.local/bin` is not in your `PATH`, the script will tell you exactly which line to add to your shell profile.

Verify the installation:

```bash theme={null}
liza version
```

You should see the installed version number. If the command is not found, add `~/.local/bin` to your `PATH` and open a new terminal.

**2. Run global setup**

Run setup once per machine. Pass a flag for each coding agent CLI you have installed:

```bash theme={null}
# Claude Code only
liza setup --claude

# Claude Code and Codex
liza setup --claude --codex

# All supported providers
liza setup --claude --codex --opencode --gemini --mistral
```

`liza setup` writes the behavioral contract, skills, support docs, default pipeline configuration, and `AGENT_TOOLS.md` to `~/.liza/`. It also creates skill symlinks under your provider's config directory (e.g., `~/.claude/skills/`).

> [!TIP]
>
> After an upgrade, run `liza setup --force` to refresh existing global files with the latest versions.

**3. Customize AGENT\_TOOLS.md**

Before running any agent, open `~/.liza/AGENT_TOOLS.md` and review it against the tools actually installed in your environment:

```bash theme={null}
# Open in your editor
$EDITOR ~/.liza/AGENT_TOOLS.md
```

Agents treat this file as their operational tool contract. If it references tools you haven't installed, agents will waste turns trying to use unavailable commands, bloat context, and make weaker decisions.

**What to do:**

* Remove entries for tools you haven't installed.
* Add entries for MCP servers or CLI tools you use that aren't in the default list.
* Keep the entries accurate — leaving instructions for missing tools is not harmless.

> [!WARNING]
>
> Do not skip this step before a serious run. The default `AGENT_TOOLS.md` references several optional tools (like `scip-search`, `stacklit-cli`, and various MCP servers) that Liza does not install automatically.

For the full customization guide, see [Customizing AGENT\_TOOLS.md](https://lizamas.mintlify.site/configuration/agent-tools.md).

**4. Initialize your project**

Navigate to the repository where you want to use Liza, then run `liza init`:

```bash theme={null}
cd ~/my-project

# Initialize for Claude
liza init --claude

# Initialize for Claude and Codex
liza init --claude --codex

# Initialize with a goal description for Multi-Agent mode
liza init "Build a REST API for user management" --spec specs/vision.md --claude
```

`liza init` creates project-local contract discovery files, provider hooks and settings (e.g., `.claude/settings.json` and `.claude/hooks/` for Claude), and Liza project state when you supply a goal.

> [!NOTE]
>
> If your project already has a `CLAUDE.md`, `AGENTS.md`, or `GEMINI.md`, Liza will not overwrite it. It falls back to the provider's global config directory.

**5. Start your session**

You have two paths depending on how much autonomy you want:

> [tab] Pairing mode
>
> Open your coding agent CLI in the initialized project directory and greet the agent. Liza's contract files are loaded automatically, and the agent enters Pairing mode.
>
> ```bash theme={null}
> # Start Claude Code in your project
> claude
> ```
>
> The agent will acknowledge the contract and show the greeting protocol. From here, you direct the work — the agent codes, proposes changes, and waits for your approval before proceeding past decision points.
>
> See the [Pairing Usage guide](https://lizamas.mintlify.site/modes/pairing.md) for collaboration modes (User Duck, Socratic Coach, Challenger), approval gates, and steering tools.

> [tab] Multi-Agent mode
>
> Launch the TUI to monitor and manage the autonomous pipeline:
>
> ```bash theme={null}
> liza tui
> ```
>
> The TUI displays live system state — running agents, task statuses on the blackboard, worktree activity — and lets you spawn agents, pause and resume the pipeline, add tasks, and trigger sprint checkpoints.
>
> Check the pipeline status at any time:
>
> ```bash theme={null}
> liza status
> ```
>
> Validate the project configuration before a run:
>
> ```bash theme={null}
> liza validate
> ```
>
> See the [Multi-Agent Usage guide](https://lizamas.mintlify.site/modes/multi-agent.md) before starting a pipeline run. The guide covers roles, sprint checkpoints, worktree management, TUI controls, and the human review flow between sprints.

## What's Next

> [card] [Introduction](https://lizamas.mintlify.site/introduction.md)
>
> Understand what Liza is, why it exists, and how the behavioral contract, adversarial pairs, and Go supervisors work together.

> [card] [Installation](https://lizamas.mintlify.site/installation.md)
>
> Explore install options: specific versions, branch builds, custom install directories, and building from source.

> [card] [Operating Modes](https://lizamas.mintlify.site/concepts/modes.md)
>
> Compare Pairing, Adversarial Pairing, and Multi-Agent modes and learn when to use each.

> [card] [CLI Reference](https://lizamas.mintlify.site/reference/cli.md)
>
> Every `liza` command, flag, and environment variable documented in full.


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