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.

Behavioral Contracts

Installs CORE.md, PAIRING_MODE.md, MULTI_AGENT_MODE.md, COLLABORATION_CONTINUITY.md, and related contract files that govern how agents behave.

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

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.

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:

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:

liza setup --claude --codex --opencode --gemini --mistral

​

What Gets Installed

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

~/.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.

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.

liza setup --claude
liza init --claude   # run separately per project

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.

liza setup --codex
liza init --codex   # run separately per project

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.

liza setup --opencode
liza init --opencode   # run separately per project

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:

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

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:

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.

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:

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

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:

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:

liza setup --force --agent-tools ~/my-agent-tools.md

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 for a step-by-step guide.