zero-cli.example.jsonc

{
  // Copy to zero-cli.jsonc (or .zero-cli/zero-cli.jsonc), then run `zero-cli trust`.
  "version": 2,
  // The single user-facing root. Other profiles are internal specialists.
  "defaultAgent": "build",
  // One effort toggle. Presets remain bounded by the agent and multiAgent
  // ceilings below; agents stop early when the task is complete.
  "workDepth": "medium",
  "permissionMode": "ask",

  // Provider profiles are reusable connection policies. Credentials stay out
  // of source control: apiKeyEnv contains a variable name, never the key.
  "providers": {
    "company-openai": {
      "type": "openai",
      "baseURL": "https://api.openai.com/v1",
      "apiKeyEnv": "COMPANY_OPENAI_API_KEY"
    },
    "kimi-code": {
      "type": "kimi",
      "apiKeyEnv": "KIMI_API_KEY"
    },
    "local": {
      "type": "openai-compatible",
      "baseURL": "http://127.0.0.1:11434/v1",
      "apiKeyEnv": "LOCAL_MODEL_API_KEY"
    }
  },

  // Codex-compatible skills are auto-discovered from .agents/skills after the
  // workspace is trusted. Entries may use this string shorthand or
  // { "path": "...", "enabled": true } for another trusted SKILL.md.
  // Agent allowlists decide which discovered/configured skills they may use.
  "skills": {
    // "release-notes": "./automation/release-notes/SKILL.md"
  },

  // MCP servers are started only after this project is trusted. Remote OAuth
  // tokens are stored privately outside the repository and managed with /mcp.
  "mcp": {
    "local-tools": {
      "type": "stdio",
      "command": "/absolute/path/to/mcp-server",
      "args": [],
      "cwd": "."
    },
    "remote-tools": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "oauth": true
    }
  },

  "webSearch": {
    "provider": "brave",
    "apiKeyEnv": "BRAVE_SEARCH_API_KEY",
    "safeSearch": "moderate"
  },

  // These keys are semantic model aliases used by agents and --model.
  "models": {
    "planner": {
      "provider": "company-openai",
      "model": "your-planning-model",
      "contextWindow": 200000,
      // Pricing is optional unless limits.maxCostUsd is enabled. Rates are USD
      // per one million tokens; replace these illustrative values.
      "pricing": {
        "inputPerMillionUsd": 2,
        "outputPerMillionUsd": 8,
        "cachedInputPerMillionUsd": 0.5
      },
      "supportedReasoningEfforts": ["default", "low", "medium", "high"],
      "supportedSpeeds": ["standard", "fast"],
      "reasoningEffort": "high",
      "speed": "standard",
      "capabilities": ["text", "tools", "structured-output"]
    },
    "coder": {
      "provider": "company-openai",
      "model": "your-coding-model",
      "contextWindow": 200000,
      "pricing": {
        "inputPerMillionUsd": 2,
        "outputPerMillionUsd": 8,
        "cachedInputPerMillionUsd": 0.5
      },
      "capabilities": ["text", "image", "file", "tools"]
    },
    "local-coder": {
      "provider": "local",
      "model": "your-local-model",
      "capabilities": ["text", "tools"]
    }
  },

  // The root handles work directly or routes bounded tasks to reusable
  // specialist profiles by deliverable. Delegate may select one of the
  // parent's canDelegateTo IDs; it cannot invent a model, tool set,
  // permission mode, workspace mode, or budget for a child. Same-root
  // shared-write children are serialized. git-worktree creates a detached
  // checkout from HEAD and returns its changes as a patch artifact; scratch
  // creates an empty temporary workspace. Isolated workspaces survive send
  // follow-ups and are removed when the runtime shuts down. Automatically
  // routed plan, analysis, and review work only uses explicit shared-readonly
  // profiles so it inspects the parent's live checkout, including uncommitted changes.
  "agents": {
    "plan": {
      "description": "Read-only planner",
      "model": "planner",
      "prompt": "Inspect the request and repository, then return a concrete plan without modifying files.",
      "tools": ["read", "find"],
      "skills": ["*"],
      "mcpServers": [],
      "accepts": ["plan"],
      "permissionMode": "read-only",
      "workspaceMode": "shared-readonly",
      "maxChildren": 0,
      "maxSteps": 100,
      "maxToolCalls": 500
    },
    "build": {
      "description": "General-purpose root orchestrator",
      "model": "coder",
      "prompt": "Inspect before editing, make the smallest coherent change, and verify it.",
      "tools": ["read", "write", "run", "find", "search", "delegate"],
      "skills": ["*"],
      "mcpServers": ["local-tools", "remote-tools"],
      "canDelegateTo": ["plan", "explore", "implement", "verify", "review"],
      "accepts": ["patch", "test_result"],
      "workspaceMode": "shared-write",
      "maxChildren": 64,
      "maxTokens": 200000,
      "timeoutMs": 28800000,
      "maxSteps": 100,
      "maxToolCalls": 500
    },
    "explore": {
      "description": "Find relevant code and explain existing behavior",
      "model": "coder",
      "prompt": "Investigate only the delegated task scope and report concise findings with exact paths.",
      "tools": ["read", "find"],
      "skills": ["*"],
      "mcpServers": [],
      "accepts": ["analysis"],
      "permissionMode": "read-only",
      "workspaceMode": "shared-readonly",
      "maxChildren": 0,
      "maxSteps": 100,
      "maxToolCalls": 500
    },
    "implement": {
      "description": "Implement one bounded change in an isolated checkout",
      "model": "coder",
      "prompt": "Implement only the delegated task, verify it, and return patch evidence.",
      "tools": ["read", "write", "find", "run", "search"],
      "skills": ["*"],
      "mcpServers": [],
      "accepts": ["patch"],
      "permissionMode": "accept-edits",
      "workspaceMode": "git-worktree",
      "maxChildren": 0,
      "maxSteps": 100,
      "maxToolCalls": 500
    },
    "verify": {
      "description": "Run bounded verification against the live workspace",
      "model": "coder",
      "prompt": "Run the most relevant checks without editing source files, then return exact command results.",
      "tools": ["read", "find", "run"],
      "skills": ["*"],
      "mcpServers": [],
      "accepts": ["test_result"],
      "permissionMode": "ask",
      "workspaceMode": "shared-write",
      "maxChildren": 0,
      "maxSteps": 100,
      "maxToolCalls": 500
    },
    "review": {
      "description": "Independent read-only reviewer",
      "model": "planner",
      "prompt": "Review correctness, regressions, security, and verification without modifying files.",
      "tools": ["read", "find"],
      "skills": ["*"],
      "mcpServers": [],
      "accepts": ["review"],
      "permissionMode": "read-only",
      "workspaceMode": "shared-readonly",
      "maxChildren": 0,
      "maxSteps": 100,
      "maxToolCalls": 500
    }
  },

  "workflows": {
    "feature": {
      "description": "Plan, implement, then review",
      "steps": ["plan", "build", { "agent": "review", "maxRetries": 1 }]
    }
  },

  // The runtime queues background children, injects compact completion events
  // into the parent/session, and runs at most maxConcurrent.
  // maxDepth/maxChildrenPerAgent/cancelChildrenWithParent are enforced by the
  // controller. defaultContext applies when spawn omits contextMode. maxRetries
  // limits explicit send/resume attempts after a failed child; it does not
  // retry automatically (workflow step retries above are independent).
  "multiAgent": {
    "maxDepth": 8,
    "maxConcurrent": 8,
    "maxChildrenPerAgent": 64,
    "defaultContext": "summary",
    "cancelChildrenWithParent": true,
    "maxRetries": 1
  },

  // /goal runs durable iterations of the normal root agent until every
  // acceptance criterion has evidence, the goal is blocked, or safety limits
  // stop it. Each iteration may use the configured subagents normally.
  "goals": {
    "enabled": true,
    "maxIterations": 64,
    "maxNoProgressIterations": 3,
    "iterationDelayMs": 0,
    "autoResume": true
    // "evaluatorModel": "fast"
  },

  // Each root or delegated run owns an isolated durable progress ledger. The
  // tool is omitted from flash-depth invocations even when enabled globally.
  "todos": {
    "enabled": true,
    "maxItems": 20
  },

  // Canonical history remains immutable. Near the selected model's safe input
  // limit, Zero CLI derives a structured checkpoint plus a recent verbatim tail,
  // then rehydrates current permissions, repository state, and child status.
  // Every parent and child run compacts independently.
  "context": {
    "fallbackWindowTokens": 128000,
    "compaction": {
      "enabled": true,
      // Optional agent profile used only to select the checkpoint model. The
      // runtime always uses its dedicated prompt with tools: []; omit this to
      // use the active run's model.
      // "agent": "compact",
      "triggerRatio": 0.8,
      "targetRatio": 0.45,
      "recentFraction": 0.15,
      "minimumRecentTurns": 2,
      // Compatibility preference retained for existing configurations. Token
      // pressure and minimumRecentTurns determine the safe atomic cutoff.
      "keepRecentTurns": 6,
      "maxSummaryTokens": 4096,
      "reservedOutputTokens": 8192,
      "safetyBufferTokens": 4096,
      "rebaseAfter": 4,
      "rebaseAfterValidationFailures": 2,
      "pruneToolOutputs": true
    }
  },

  "limits": {
    // Deprecated delegation aliases. `multiAgent` takes precedence when both
    // forms are present.
    "maxDepth": 8,
    "maxChildrenPerRun": 64,
    // Aggregate across the root agent, children, retries, workflow phases,
    // and compaction calls. maxCostUsd additionally requires pricing on every
    // model used by a configured agent.
    "maxCampaignTokens": 4000000,
    // "maxCostUsd": 25,
    "runTimeoutMs": 28800000,
    "toolTimeoutMs": 120000,
    "maxAttachmentBytes": 10485760
  }
}