0x0 CLI Guide

This guide documents 0x0 in this repository, from installation to advanced configuration.

Installation

Use one of the supported install methods:

# Install script
curl -fsSL https://0x0.ai/install | bash

# Package managers
npm i -g @anonymous-dev/0x0@latest
pnpm add -g @anonymous-dev/0x0@latest
bun install -g @anonymous-dev/0x0@latest
brew install anonymous-dev-org/tap/0x0
brew install 0x0
scoop install 0x0
choco install 0x0
mise use -g 0x0

Verify:

0x0 --version
0x0 --help

Core usage

Start TUI: 0x0 or 0x0 [project]
One-shot mode: 0x0 run "your prompt"
Headless server: 0x0 server (alias: serve)
Attach to running server: 0x0 attach <url>

Global CLI options:

--help, -h
--version, -v
--print-logs
--log-level DEBUG|INFO|WARN|ERROR

Command reference

Top-level commands:

0x0 / $0 [project]: start TUI (--model, --continue, --session, --fork, --prompt, --agent + network options)
0x0 completion: generate shell completion script
0x0 run [message..]: non-interactive prompt/command execution
0x0 attach <url>: attach TUI to server (--dir, --session, --password)
0x0 server (alias: serve): start headless server (network options)
0x0 acp: start ACP server (--cwd + network options)
0x0 auth: credential management
0x0 mcp: MCP server management
0x0 agent: generate/list agents
0x0 models [provider]: list models (--verbose, --refresh)
0x0 session list: list sessions (--max-count, --format table|json)
0x0 stats: usage/cost stats (--days, --tools, --models, --project)
0x0 export [sessionID]: export session JSON
0x0 import <file-or-share-url>: import session JSON or /share/<id> URL
0x0 pr <number>: checkout PR and launch 0x0
0x0 github: GitHub agent install/run helpers
0x0 upgrade [target]: upgrade CLI (--method)
0x0 uninstall: remove installation/data (--keep-config, --keep-data, --dry-run, --force)
0x0 debug: diagnostics (config, paths, lsp, rg, file, scrap, skill, snapshot, agent, wait)
0x0 generate: output the OpenAPI specification for the 0x0 server as JSON

Network options shared by server/serve, TUI, and acp:

--port (default 0)
--hostname (default 127.0.0.1)
--mdns (default false)
--mdns-domain (default zeroxzero.local)
--cors <origin> (repeatable)

Configuration files

Want architecture-first guidance? Read Config Strategy for a concise global-vs-project contract, memory pattern, and type-safe workflow.

0x0 uses YAML for configuration. The only recognized config filename is config.yaml.

Global config

Primary location: Global.Path.config (XDG config path, app folder 0x0). Typical examples:

macOS/Linux: ~/.config/0x0/config.yaml
Windows: XDG config directory for the current user, under 0x0

Check exact runtime paths with:

0x0 debug paths

Per-project config

Project config is discovered from the current directory upward to the repo/worktree root. For each directory in the chain, 0x0 checks:

<dir>/.0x0/config.yaml

Example project config file:

.0x0/config.yaml

Important conflict rule:

If multiple project config files exist in the same directory level, 0x0 throws a conflict error.

Provider config files

Provider-specific config can be stored in providers/*.yaml directories:

Global: ~/.config/0x0/providers/<provider-id>.yaml
Project: .0x0/providers/<provider-id>.yaml

The provider ID is derived from the filename (e.g., anthropic.yaml registers provider anthropic). These files are parsed against the provider config schema and merged into the main config at their respective precedence levels.

`.zeroxzero` extension directories

In addition to YAML config files, 0x0 loads extension content from .zeroxzero directories:

.zeroxzero/config.yaml
.zeroxzero/agent/**/*.md or .zeroxzero/agents/**/*.md
.zeroxzero/command/**/*.md or .zeroxzero/commands/**/*.md
.zeroxzero/mode/*.md or .zeroxzero/modes/*.md
.zeroxzero/plugin/*.{ts,js} or .zeroxzero/plugins/*.{ts,js}

These are loaded from project scope and home scope (~/.zeroxzero/).

Config precedence

Low to high precedence:

Remote .well-known/zeroxzero config (when authenticated provider supports it)
Global config (~/.config/0x0/config.yaml)
Global provider configs (~/.config/0x0/providers/*.yaml)
ZEROXZERO_CONFIG file path override
Project config files (.0x0/config.yaml, walked upward from cwd to worktree root)
Project provider configs (.0x0/providers/*.yaml)
.zeroxzero directories (config, commands, agents, plugins — project dirs upward + ~/.zeroxzero/ + ZEROXZERO_CONFIG_DIR)
Inline ZEROXZERO_CONFIG_CONTENT JSON
Managed enterprise config directory (highest):
- macOS: /Library/Application Support/zeroxzero
- Linux: /etc/zeroxzero
- Windows: %ProgramData%\\zeroxzero

Array fields plugin, instructions, and knowledge_base are concatenated (with dedup) across layers rather than replaced.

Global config YAML example

# yaml-language-server: $schema=https://zeroxzero.ai/config.json
$schema: https://zeroxzero.ai/config.json

theme: zeroxzero
logLevel: INFO
model: zeroxzero/gpt-5.1
default_agent: build
share: manual
autoupdate: notify

server:
  hostname: 127.0.0.1
  port: 0
  mdns: false
  mdnsDomain: zeroxzero.local
  cors:
    - https://example.com

provider:
  openai:
    options:
      apiKey: '{env:OPENAI_API_KEY}'
      timeout: 300000

mcp:
  local-files:
    type: local
    command: ['npx', '-y', '@modelcontextprotocol/server-filesystem', '.']
  remote-docs:
    type: remote
    url: https://example.com/mcp
    oauth:
      clientId: '{env:MCP_CLIENT_ID}'
      clientSecret: '{file:./secrets/mcp-client-secret.txt}'

compaction:
  auto: true
  prune: true

experimental:
  batch_tool: true
  mcp_timeout: 10000

Per-project config YAML example

Use project config for repo-specific behavior. .0x0/config.yaml:

# yaml-language-server: $schema=https://zeroxzero.ai/config.json
$schema: https://zeroxzero.ai/config.json

model: anthropic/claude-sonnet-4
default_agent: plan
knowledge_base:
  - This repo uses Bun workspaces
  - Use `bun test` for tests

permission:
  bash: ask
  edit: allow
  read: allow

watcher:
  ignore:
    - '**/dist/**'
    - '**/.next/**'

.0x0/config.yaml can be used for a dedicated per-project settings file managed by the CLI.

Recommended config strategy

For the full decision table and policy guidance, use Config Strategy. Quick rule of thumb:

Keep cross-repo defaults in global config.
Keep repo facts and workflow policy in project config.
Use the plan agent (agent.plan; or your custom planner) as the only writer for mutable memory.

Minimal project memory gate example:

permission:
  edit:
    .zeroxzero/memory.md: deny

agent:
  plan:
    permission:
      edit:
        .zeroxzero/memory.md: allow

Advanced configuration areas

Full guides are available for major subsystems:

Agents: define primary/all agents, model overrides, prompts, permission rules, step limits
Commands: define reusable slash commands and templates
Permissions: global tool permission policy (ask, allow, deny) and path rules
Providers: provider-specific API settings, model overrides, variant options, allow/deny lists
MCP Servers: local and remote MCP servers, headers, OAuth, timeouts, enabled flags
Plugins: custom hooks, tools, and integrations
Skills: portable instruction packs from local or remote sources
Keybinds: customize TUI key mappings
Tools: built-in tool reference and custom tool registration

`tui`

TUI-specific display and interaction settings:

Field	Type	Default	Description
`scroll_speed`	`number`	—	Scroll speed (min 0.001)
`scroll_acceleration.enabled`	`boolean`	—	Enable scroll acceleration
`terminal_notifications`	`boolean`	—	Enable terminal bell notifications on completion
`diff_style`	`"auto" \| "stacked"`	`auto`	Diff rendering: auto adapts to terminal width, stacked uses single column
`tint_strength`	`number`	`1.0`	Global tint opacity scale (0 to 1)

`compaction`

Session compaction automatically summarizes older messages when the context window fills up:

Field	Type	Default	Description
`max_words_before_compact`	`number`	`12000`	Word count threshold for auto-compaction
`provider`	`string`	—	Provider for the compaction model (must be set with `model`)
`model`	`string`	—	Model for compaction (must be set with `provider`)
`prompt`	`string`	—	Custom compaction prompt (replaces the default)

Related env vars: ZEROXZERO_DISABLE_AUTOCOMPACT, ZEROXZERO_DISABLE_PRUNE. Session sharing mode:

Value	Description
`"manual"`	Sharing available via commands and keybinds
`"auto"`	Sessions are shared automatically
`"disabled"`	All sharing is disabled

`formatter`

External formatter commands by language. Set to false to disable all formatters.

formatter:
  prettier:
    command: ['prettier', '--write']
    extensions: ['.ts', '.tsx', '.js', '.jsx', '.json']
  black:
    command: ['black', '-']
    extensions: ['.py']
    disabled: false
    environment:
      BLACK_LINE_LENGTH: '100'

Field	Type	Description
`command`	`string[]`	Formatter command and arguments
`extensions`	`string[]`	File extensions this formatter handles
`disabled`	`boolean`	Disable this formatter
`environment`	`Record<string, string>`	Environment variables

`lsp`

Language server configuration. Set to false to disable all LSP servers.

lsp:
  typescript:
    command: ['typescript-language-server', '--stdio']
    extensions: ['.ts', '.tsx']
  custom-server:
    command: ['my-lsp', '--stdio']
    extensions: ['.custom']
    disabled: false
    env:
      DEBUG: 'true'
    initialization:
      myOption: true

Field	Type	Description
`command`	`string[]`	LSP server command and arguments
`extensions`	`string[]`	File extensions (required for custom servers)
`disabled`	`boolean`	Disable this server
`env`	`Record<string, string>`	Environment variables
`initialization`	`Record<string, any>`	LSP initialization options

`prompt`

Override built-in reminder strings:

prompt:
  reminder:
    queued_user: 'The user has queued this message: {{message}}'
    max_steps: 'You have reached the maximum number of steps.'

`knowledge_base`

Project-specific knowledge snippets injected into all agents. These are short facts that help agents understand the project:

knowledge_base:
  - This repo uses Bun workspaces
  - Run tests with `bun test`
  - The API uses Hono framework

`small_model`

Model used for lightweight tasks like title generation:

small_model: openai/gpt-4.1-mini

`experimental`

Feature toggles for experimental functionality:

Field	Type	Description
`batch_tool`	`boolean`	Enable the batch tool
`mcp_timeout`	`number`	MCP request timeout in ms
`filewatcher`	`boolean`	Enable experimental file watcher
`disable_filewatcher`	`boolean`	Disable file watcher
`icon_discovery`	`boolean`	Enable icon discovery for projects
`exa`	`boolean`	Enable Exa search integration
`bash_default_timeout_ms`	`number`	Default bash tool timeout in ms
`output_token_max`	`number`	Maximum output tokens for LLM responses
`oxfmt`	`boolean`	Enable oxfmt formatter
`lsp_ty`	`boolean`	Enable ty LSP server
`lsp_tool`	`boolean`	Enable LSP diagnostics tool
`markdown`	`boolean`	Enable experimental markdown rendering
`enable_experimental_models`	`boolean`	Enable experimental model variants
`disable_paste_summary`	`boolean`	Disable paste summary
`openTelemetry`	`boolean`	Enable OpenTelemetry spans
`primary_tools`	`string[]`	Tools only available to primary agents
`continue_loop_on_deny`	`boolean`	Continue agent loop when a tool call is denied

Config interpolation

Config text supports:

{env:VAR_NAME}: inject environment variable value
{file:./relative/or/absolute/path}: inject file content

Notes:

Relative {file:...} paths resolve from the config file’s directory.
~ is supported in file references.
Commented references are ignored.

Environment variables

Frequently used flags:

ZEROXZERO_CONFIG: explicit config file path
ZEROXZERO_CONFIG_DIR: explicit extension directory (.zeroxzero-style)
ZEROXZERO_CONFIG_CONTENT: inline JSON config override
ZEROXZERO_DISABLE_PROJECT_CONFIG: disable project config loading
ZEROXZERO_PERMISSION: inline JSON permission override
ZEROXZERO_SERVER_USERNAME / ZEROXZERO_SERVER_PASSWORD: server basic auth
ZEROXZERO_AUTO_SHARE: auto-share override
ZEROXZERO_DISABLE_AUTOCOMPACT, ZEROXZERO_DISABLE_PRUNE: compaction overrides
ZEROXZERO_DISABLE_AUTOUPDATE: disable auto-update checks

There are additional experimental flags in packages/0x0/src/flag/flag.ts.

Troubleshooting

Show resolved config: 0x0 debug config
Show paths: 0x0 debug paths
List known projects: 0x0 debug scrap
Check models: 0x0 models --refresh
Check MCP status: 0x0 mcp list and 0x0 mcp auth list
Run without TUI: 0x0 run "diagnose this repo" --format json

Getting Started

Guides

Clients

Reference

Complete CLI Guide

0x0 CLI Guide

Installation

Core usage

Command reference

Configuration files

Global config

Per-project config

Provider config files

`.zeroxzero` extension directories

Config precedence

Global config YAML example

Per-project config YAML example

Recommended config strategy

Advanced configuration areas

`tui`

`compaction`

`formatter`

`lsp`

`prompt`

`knowledge_base`

`small_model`

`experimental`

Config interpolation

Environment variables

Troubleshooting

See also

Getting Started

Guides

Clients

Reference

​0x0 CLI Guide

​Installation

​Core usage

​Command reference

​Configuration files

​Global config

​Per-project config

​Provider config files

​.zeroxzero extension directories

​Config precedence

​Global config YAML example

​Per-project config YAML example

​Recommended config strategy

​Advanced configuration areas

​tui

​compaction

​share

​formatter

​lsp

​prompt

​knowledge_base

​small_model

​experimental

​Config interpolation

​Environment variables

​Troubleshooting

​See also

0x0 CLI Guide

Installation

Core usage

Command reference

Configuration files

Global config

Per-project config

Provider config files

`.zeroxzero` extension directories

Config precedence

Global config YAML example

Per-project config YAML example

Recommended config strategy

Advanced configuration areas

`tui`

`compaction`

`share`

`formatter`

`lsp`

`prompt`

`knowledge_base`

`small_model`

`experimental`

Config interpolation

Environment variables

Troubleshooting

See also