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

# Configuring Providers: Claude, Codex, OpenCode, and More

> Liza wraps provider CLIs directly — no API keys required. Configure Claude Code, Codex, OpenCode, Kimi, Mistral, or Gemini for use with Liza.

Liza integrates with coding agent providers by wrapping their own CLIs directly. You authenticate with each provider CLI separately using that provider's own mechanism — Liza does not store or manage API keys. When you run a Liza agent, Liza invokes the underlying CLI with the correct arguments, contract files, and workspace permissions it needs to operate autonomously.

## How Provider Integration Works

Each provider CLI handles authentication, model selection, and execution independently. Liza's role is to:

1. Install behavioral contracts and skills that the CLI reads at session start (`liza setup`)
2. Configure project-level permissions, hooks, and settings so agents can operate headlessly (`liza init`)
3. Invoke the CLI with the right arguments for pairing or multi-agent mode (`liza agent`)

This architecture means you can switch providers per-task or per-role without changing your workflow. Reviewers can use a different provider than coders, enabling adversarial diversity in your pipeline.

## Supported Provider CLIs

The `--cli` flag on `liza agent` accepts any of these values:

| CLI name | Description |
| - | - |
| `claude` | Claude Code CLI (default when no config is set) |
| `codex` | OpenAI Codex CLI |
| `codex-acp` | Codex through ACPX; requires `acpx` on PATH |
| `opencode` | OpenCode CLI via `opencode run` |
| `opencode-acp` | OpenCode through ACPX; requires `acpx` on PATH |
| `gemini` | Google Gemini CLI |
| `mistral` | Mistral Le Chat CLI |
| `kimi` | Kimi (alias to Claude with Kimi-specific env vars) |

## Provider Compatibility Matrix

| Provider | Classification | Notes |
| - | - | - |
| Claude Opus 4.x | **Fully compatible** | Reference provider; recommended for all roles |
| GPT-5.x / Codex | **Fully compatible** | Equally capable; recommended alongside Claude |
| Kimi 2.5 | Compatible — limited real-world performance | Responsive to tooling feedback; verify before unattended use |
| Mistral Devstral-2 | **Partial** | Requires explicit activation and supervision; not recommended as primary |
| Gemini 2.5 Flash | **Incompatible** | Architectural limitation — cannot be fixed at the prompt level |

> [!NOTE]
>
> Running Claude and Codex as adversarial pairs — Claude as coder and Codex as reviewer, or vice versa — increases review diversity and catches a wider class of errors than same-provider pairing. This is especially useful for high-stakes pipelines.

## Per-Provider Setup

> [tab] Claude
>
> Claude Code is the reference provider and the default when no `config.default_cli` is set.
>
> **Setup:**
>
> ```bash theme={null}
> liza setup --claude       # installs skill symlinks to ~/.claude/skills/
> liza init --claude        # writes .claude/settings.json and .claude/hooks/
> ```
>
> **What `liza init --claude` manages:**
>
> * `.claude/settings.json` — written from Liza's embedded template; includes `defaultMode: acceptEdits` (required for headless operation), `enableAllProjectMcpServers`, all `Bash(liza:*)` permissions, skill references, and `permissions.additionalDirectories` granting access to `~/.liza` and `/tmp`
> * `.claude/hooks/` — session initialization, project context injection, Git usage guards, and wrong-worktree path detection
> * `.claudeignore` — created when absent
>
> **Two-layer permission model:**
>
> Claude Code unions permissions from two files:
>
> | Layer | File | Managed by | Contains |
> | - | - | - | - |
> | Project | `<project>/.claude/settings.json` | `liza init` (automatic) | Liza CLI permissions, skills, Git/build commands |
> | Global | `~/.claude/settings.json` | Manual (one-time) | Personal MCP tools, machine-specific permissions |
>
> The project layer is portable and team-shareable. The global layer is machine-specific. Both layers are required — neither alone is sufficient.
>
> > [!WARNING]
> >
> > Do not hand-craft a subset of `.claude/settings.json`. Liza's embedded template includes the complete set of permissions agents need. A missing permission will silently block an agent mid-task.

> [tab] Codex
>
> Codex is fully supported and equally capable to Claude for all agent roles.
>
> **Setup:**
>
> ```bash theme={null}
> liza setup --codex        # installs skill symlinks to ~/.codex/skills/
> liza init --codex         # configures ~/.codex/config.toml and project hooks
> ```
>
> **What `liza init --codex` manages:**
>
> * `~/.codex/config.toml` — adds the project root and project `.git` directory to `sandbox_workspace_write.writable_roots`, sets model, approval policy, sandbox mode, reasoning effort, and network access
> * `.codex/config.toml` and `.codex/hooks.json` — project-local hook activation
> * Global fallback `~/.codex/AGENTS.md` symlink for brownfield projects
>
> **Recommended global `~/.codex/config.toml` shape:**
>
> ```toml theme={null}
> model = "gpt-5.5"
> approval_policy = "never"
> sandbox_mode = "workspace-write"
> model_reasoning_effort = "high"
> personality = "pragmatic"
>
> [permissions.workspace.network]
> enabled = true
>
> [sandbox_workspace_write]
> network_access = true
> exclude_tmpdir_env_var = false
> exclude_slash_tmp = false
> writable_roots = [
>   "/home/<USER>/.codex",
>   "/home/<USER>/.liza",
>   "/home/<USER>/.npm",
>   "/home/<USER>/.pyenv/shims",
>   "/home/<USER>/.cache",
>   "/tmp",
>   "/path/to/project",
>   "/path/to/project/.git",
> ]
> ```
>
> **Pinning the Codex version for headless agents:**
>
> Add `codex_package_version` to `.liza/state.yaml` for a durable pin:
>
> ```yaml theme={null}
> config:
>   codex_package_version: "0.125.0"
> ```
>
> Or use the environment variable as a temporary fallback:
>
> ```bash theme={null}
> export LIZA_CODEX_VERSION=0.125.0
> ```
>
> The state config value takes precedence over the environment variable. The version pin makes Liza launch headless agents through `npm exec --yes --package @openai/codex@<version> -- codex`. Interactive `liza agent -i` always uses the installed binary regardless of the pin.
>
> > [!NOTE]
> >
> > Git worktrees write their task index under the main repo's `.git/worktrees/<task>/index.lock` path, not under the worktree directory itself. This is why the project `.git` directory must appear in `writable_roots` — without it, Codex cannot write Git metadata in worktrees.

> [tab] OpenCode
>
> OpenCode requires explicit flags at both setup and init time.
>
> **Setup:**
>
> ```bash theme={null}
> liza setup --opencode     # installs skill symlinks to ~/.config/opencode/skills/
> liza init --opencode      # activates contract and installs exec.ts compatibility tool
> ```
>
> **What `liza init --opencode` manages:**
>
> * `AGENTS.md` symlink → `~/.liza/CORE.md` (or `~/.config/opencode/AGENTS.md` fallback for brownfield)
> * `.opencode/tools/exec.ts` — Liza's managed compatibility tool that exposes a simple `exec` schema with required `cmd` and nullable optional `workdir` and `timeout_ms` fields; agents prefer this for shell and file operations
>
> **Headless MAS execution:**
>
> Liza runs headless OpenCode agents with:
>
> ```bash theme={null}
> opencode run "<prompt>" --dangerously-skip-permissions
> ```
>
> Use `--cli opencode-acp` if another ACP-capable tool needs OpenCode as an agent server. This selects the ACPX-backed runtime; it is not an OpenCode command name. To configure OpenCode as an ACP server for external tools:
>
> ```json theme={null}
> {
>   "agent_servers": {
>     "OpenCode": {
>       "command": "opencode",
>       "args": ["acp"]
>     }
>   }
> }
> ```
>
> > [!TIP]
> >
> > For Groq-backed OpenCode runs, prefer Llama 3.3 70B over GPT-OSS 120B until tool-call reliability is validated against a real Liza task. Always test the selected model before relying on it for unattended work.

> [tab] Gemini
>
> Gemini has weaker instruction-following than Claude and Codex and is not recommended as a primary provider. If you use it, perform the required manual setup step after running `liza setup --gemini`.
>
> **Setup:**
>
> ```bash theme={null}
> liza setup --gemini       # installs skill symlinks to ~/.gemini/skills/
> ```
>
> **Required manual step** — add `~/.liza` to `~/.gemini/settings.json`:
>
> ```json theme={null}
> {
>   "context": {
>     "includeDirectories": [
>       "~/.liza"
>     ]
>   }
> }
> ```
>
> Without this entry, Gemini cannot read the behavioral contracts and will not follow the Liza protocol. Verify activation by starting Gemini in the initialized project and confirming it acknowledges the contract.
>
> Gemini 2.5 Flash is architecturally incompatible with Liza and cannot be fixed at the prompt level. Use other Gemini model variants if you must use Gemini.

> [tab] Kimi
>
> Kimi runs through the Claude CLI by pointing it at Kimi's API endpoint. No separate Liza setup flag is required beyond `--claude`.
>
> **Setup:**
>
> ```bash theme={null}
> liza setup --claude       # Kimi reuses Claude's global setup
> liza init --claude        # Kimi reuses Claude's project setup
> ```
>
> **Create a local `kimi` wrapper:**
>
> ```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
> ```
>
> Then run `kimi` as you would run `claude`. It inherits Claude's config automatically. To use Kimi as a Liza agent:
>
> ```bash theme={null}
> liza agent coder --cli kimi
> ```
>
> Kimi 2.5 is compatible but performs poorly on complex real-world tasks. Verify its behavior against a representative task before using it for unattended multi-agent runs.

> [tab] Mistral / Vibe
>
> Mistral through the Vibe CLI is partial support only. Explicit activation and supervision are required.
>
> **Setup:**
>
> ```bash theme={null}
> liza setup --mistral      # installs prompt link under ~/.vibe/prompts/
> ```
>
> **Filesystem MCP server** — Mistral may need this in `~/.vibe/config.toml` to read `~/.liza` and your workspace:
>
> ```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"
> ]
> ```
>
> Mistral is not recommended as a primary Liza provider. Use it only when Claude and Codex are unavailable, and verify contract activation before running any autonomous tasks.

## Environment Variables

| Variable | Default | Purpose |
| - | - | - |
| `LIZA_CODEX_VERSION` | unset | Process-local fallback for `config.codex_package_version` when launching headless Codex agents |
| `ANTHROPIC_BASE_URL` | (Claude default) | Override the Anthropic API base URL — used by the Kimi wrapper to point Claude CLI at Kimi's endpoint |
| `ANTHROPIC_API_KEY` | (Claude default) | Override the API key — used by the Kimi wrapper |
| `LIZA_DEFAULT_CLI` | unset | Fallback default CLI when no role-specific default is configured |
| `LIZA_DEFAULT_DOER_CLI` | unset | Default CLI for coders and orchestrators |
| `LIZA_DEFAULT_REVIEWER_CLI` | unset | Default CLI for reviewers |
| `LIZA_DISABLE_CLAUDE_SUBAGENTS` | unset | Set to `1` to launch Claude Code with `--disallowedTools Task`, disabling subagent delegation |

## Setting Provider Defaults

Set default CLIs at init time rather than passing `--cli` on every `liza agent` call:

```bash theme={null}
liza init "Goal" \
  --default-doer-cli codex \
  --default-reviewer-cli claude
```

Or add them to `.liza/state.yaml` directly:

```yaml theme={null}
config:
  default_doer_cli: codex
  default_reviewer_cli: claude
```


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