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

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

Claude

Claude Code is the reference provider and the default when no config.default_cli is set.

Setup:

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.

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.

Codex

Codex is fully supported and equally capable to Claude for all agent roles.

Setup:

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:

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:

config:
  codex_package_version: "0.125.0"

Or use the environment variable as a temporary fallback:

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.

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.

OpenCode

OpenCode requires explicit flags at both setup and init time.

Setup:

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:

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:

{
  "agent_servers": {
    "OpenCode": {
      "command": "opencode",
      "args": ["acp"]
    }
  }
}

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.

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:

liza setup --gemini       # installs skill symlinks to ~/.gemini/skills/

Required manual step — add ~/.liza to ~/.gemini/settings.json:

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

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:

liza setup --claude       # Kimi reuses Claude's global setup
liza init --claude        # Kimi reuses Claude's project setup

Create a local kimi wrapper:

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:

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.

Mistral / Vibe

Mistral through the Vibe CLI is partial support only. Explicit activation and supervision are required.

Setup:

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:

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

liza init "Goal" \
  --default-doer-cli codex \
  --default-reviewer-cli claude

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

config:
  default_doer_cli: codex
  default_reviewer_cli: claude