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

# Global Setup: Install Liza Contracts, Skills, and Tools

> Run liza setup to install behavioral contracts, composable skills, provider hooks, and AGENT_TOOLS.md into ~/.liza/ before starting any project.

Before you initialize any project, run `liza setup` once per machine to install Liza's global contract files. This command writes behavioral contracts, composable skills, support documentation, default pipeline configuration, and the critical `AGENT_TOOLS.md` tool contract to `~/.liza/` — the foundation every project and agent session depends on.

## What `liza setup` Does

`liza setup` populates `~/.liza/` with everything Liza needs to operate across any project on your machine. It does not touch your project directories — that is the job of `liza init`.

> [card] Behavioral Contracts
>
> Installs `CORE.md`, `PAIRING_MODE.md`, `MULTI_AGENT_MODE.md`, `COLLABORATION_CONTINUITY.md`, and related contract files that govern how agents behave.

> [card] Composable Skills
>
> Installs the `skills/` directory with reusable agent skills such as `checkpoint-summary`. Provider flags create symlinks from each provider's own skill directory back to `~/.liza/skills/`.

> [card] AGENT\_TOOLS.md
>
> Installs the agent tool contract — the file that tells agents which CLI tools and MCP servers to use and in what order.

> [card] Support Docs & Pipeline Config
>
> Installs `support-docs/`, a default `pipeline.yaml`, and the `CUSTOMIZING_AGENT_TOOLS.md` guide agents can reference during setup review.

## Command Syntax

Run the base setup, then add provider flags for every coding agent CLI you intend to use:

```bash theme={null}
liza setup                          # base setup — installs to ~/.liza/
liza setup --claude --codex         # + provider-specific skill symlinks
liza setup --opencode               # + OpenCode support
liza setup --gemini                 # + Gemini skill symlinks
liza setup --mistral                # + Mistral/Vibe prompt link
liza setup --force                  # refresh existing files after upgrade
```

You can combine multiple provider flags in a single call:

```bash theme={null}
liza setup --claude --codex --opencode --gemini --mistral
```

## What Gets Installed

After running `liza setup`, your `~/.liza/` directory contains:

```text theme={null}
~/.liza/
├── CORE.md                        # primary behavioral contract
├── PAIRING_MODE.md                # pairing-mode contract
├── MULTI_AGENT_MODE.md            # multi-agent contract
├── COLLABORATION_CONTINUITY.md    # session continuity contract
├── AGENT_TOOLS.md                 # agent tool contract (customize this)
├── pipeline.yaml                  # default pipeline configuration
├── skills/                        # composable agent skills
└── support-docs/                  # CUSTOMIZING_AGENT_TOOLS.md and others
```

Provider flags create additional symlinks in each CLI's own config directory pointing back to `~/.liza/skills/`:

| Provider flag | Symlink location |
| - | - |
| `--claude` | `~/.claude/skills/` |
| `--codex` | `~/.codex/skills/` |
| `--opencode` | `~/.config/opencode/skills/` |
| `--gemini` | `~/.gemini/skills/` |
| `--mistral` | `~/.vibe/prompts/` |

## Provider-Specific Notes

Each provider CLI has a different integration model. Read the relevant section before running setup.

> [tab] Claude
>
> `liza setup --claude` handles the full global install for Claude Code. It creates skill symlinks under `~/.claude/skills/` pointing to `~/.liza/skills/`.
>
> Project-level Claude settings (`.claude/settings.json`, `.claude/hooks/`) are written by `liza init --claude` — not by setup.
>
> ```bash theme={null}
> liza setup --claude
> liza init --claude   # run separately per project
> ```

> [tab] Codex
>
> `liza setup --codex` handles the full global install for the Codex CLI. It creates skill symlinks under `~/.codex/skills/`.
>
> Project-level Codex hooks and the global `~/.codex/config.toml` writable-root entries are managed by `liza init --codex`.
>
> ```bash theme={null}
> liza setup --codex
> liza init --codex   # run separately per project
> ```

> [tab] OpenCode
>
> OpenCode requires `--opencode` explicitly. `liza setup --opencode` installs skill symlinks under `~/.config/opencode/skills/`.
>
> `liza init --opencode` then installs Liza's managed `.opencode/tools/exec.ts` compatibility tool so OpenCode agents have a simple shell and file-operation interface with tolerant optional arguments.
>
> ```bash theme={null}
> liza setup --opencode
> liza init --opencode   # run separately per project
> ```

> [tab] Gemini
>
> Gemini requires one **manual step** that `liza setup` cannot perform. After running `liza setup --gemini`, add `~/.liza` to the `includeDirectories` list in `~/.gemini/settings.json`:
>
> ```json theme={null}
> {
>   "context": {
>     "includeDirectories": [
>       "~/.liza"
>     ]
>   }
> }
> ```
>
> Gemini has weaker instruction-following compatibility than Claude and Codex. Verify contract activation by starting the provider and confirming it reads the contract files.

> [tab] Kimi
>
> Kimi runs through the Claude CLI using environment variable overrides — no separate `liza setup` flag is needed beyond `--claude`. Create a local `kimi` wrapper script that points to Kimi's endpoint:
>
> ```bash theme={null}
> cat > ~/.local/bin/kimi <<'EOF'
> #!/bin/bash
> source ~/.llm-credentials
> ANTHROPIC_BASE_URL=https://api.kimi.com/coding/ \
> ANTHROPIC_API_KEY=$KIMI_API_KEY \
> ANTHROPIC_MODEL='kimi-k2.5' \
> claude "$@"
> EOF
> chmod +x ~/.local/bin/kimi
> ```
>
> The wrapper inherits Claude's existing config automatically.

> [tab] Mistral / Vibe
>
> Mistral through the Vibe CLI may require a filesystem MCP server so agents can read `~/.liza` and your workspace. Add it to `~/.vibe/config.toml`:
>
> ```toml theme={null}
> [[mcp_servers]]
> name = "filesystem"
> transport = "stdio"
> command = "npx"
> args = [
>   "-y",
>   "@modelcontextprotocol/server-filesystem",
>   "/home/<USER>/.vibe",
>   "/home/<USER>/Workspace",
>   "/home/<USER>/.liza"
> ]
> ```
>
> > [!NOTE]
> >
> > Mistral is not recommended as a primary Liza provider. Verify contract activation before relying on it for real work.

## How to Upgrade

After updating the Liza binary, refresh existing global files with the `--force` flag:

```bash theme={null}
liza setup --force
liza setup --claude --codex --force   # force-refresh with provider symlinks
```

Without `--force`, `liza setup` skips files that already exist. Use `--force` after every binary upgrade to ensure contracts, skills, and `AGENT_TOOLS.md` reflect the latest version.

## Using a Custom AGENT\_TOOLS.md

If you maintain your own tool contract, pass it at setup time:

```bash theme={null}
liza setup --agent-tools ~/my-agent-tools.md
```

Liza installs your file to `~/.liza/AGENT_TOOLS.md` instead of the embedded default. Repass this flag with `--force` after upgrades if you want to keep your custom version:

```bash theme={null}
liza setup --force --agent-tools ~/my-agent-tools.md
```

> [!WARNING]
>
> **Do not skip `AGENT_TOOLS.md` customization before a serious run.** The default file references optional tools that Liza does not install for you. Agents follow this file as an operational contract — instructions for missing tools cause failed attempts, fallback churn, and bloated context windows. Review and adapt it before your first real task. See [Customize AGENT\_TOOLS.md](https://lizamas.mintlify.site/configuration/agent-tools.md) for a step-by-step guide.


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