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.

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

   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:

   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:

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

   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:

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

   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.

4. Initialize your project

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

   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.

   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:

   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.

   # 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 for collaboration modes (User Duck, Socratic Coach, Challenger), approval gates, and steering tools.

   Multi-Agent mode

   Launch the TUI to monitor and manage the autonomous pipeline:

   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:

   liza status
   

   Validate the project configuration before a run:

   liza validate
   

   See the Multi-Agent Usage guide 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

Introduction

Understand what Liza is, why it exists, and how the behavioral contract, adversarial pairs, and Go supervisors work together.

Installation

Explore install options: specific versions, branch builds, custom install directories, and building from source.

Operating Modes

Compare Pairing, Adversarial Pairing, and Multi-Agent modes and learn when to use each.

CLI Reference

Every liza command, flag, and environment variable documented in full.