Paintress CLI Configuration

Configuration is loaded from multiple locations with project-level priority (no merging between levels).

Configuration Locations

Configuration Files

config.toml (Global)

Main configuration file for model, display, browser, and subagents.

[general]
# Model configuration (required)
# Format: "provider:model_name"
model = "anthropic:claude-sonnet-4-5"

# Model settings preset or custom dict
# Presets: anthropic_default, openai_default, google_default
model_settings = "anthropic_default"

# Model config for context management
# Presets: claude_200k, claude_1m, gpt5_270k, gemini_1m
model_cfg = "claude_200k"

# Maximum requests per session
max_requests = 1000

[env]
# Environment variable overrides for API keys
# ANTHROPIC_API_KEY = "sk-ant-..."

[display]
code_theme = "dark"           # "dark" or "light"
max_tool_result_lines = 5
max_arg_length = 100
show_token_usage = true
show_elapsed_time = true

[browser]
# cdp_url = "auto"            # null, "auto", or explicit URL
browser_image = "zenika/alpine-chrome:latest"
browser_timeout = 30

[subagents]
disabled = []                 # Subagents to disable by name
# [subagents.overrides.explorer]
# model = "openai:gpt-4o"

tools.toml (Project)

Project-level tool permissions in .paintress/tools.toml:

[tools]
# Tools requiring user approval before execution
need_approval = ["shell", "replace"]

Common patterns:

• [] - No approval needed (trust all tools)
• ["shell"] - Approve shell commands only
• ["shell", "replace", "edit"] - Approve all code modifications

mcp.json

MCP server configurations:

{
  "servers": {
    "my-server": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@some/mcp-server"],
      "env": {}
    }
  }
}

Custom Slash Commands

Define custom commands in config.toml:

[commands.deploy]
description = "Deploy to production"
mode = "act"                  # Optional: "act" or "plan"
prompt = """
Please help me deploy to production...
"""

Built-in commands: /init, /commit, /review

Subagent Configuration

Create markdown files in ~/.config/youware-labs/paintress-cli/subagents/:

---
name: my-subagent
description: Brief description shown when selecting tools
instruction: |
  When to use this subagent and what to provide
tools:
  - grep
  - view
optional_tools:
  - shell
model: inherit
---

You are a specialist in [domain].

## Process
1. Step one
2. Step two

Configuration Fields

Tool Availability Rules

• Required tools (tools): Subagent disabled if ANY unavailable
• Optional tools (optional_tools): Included only if available
• No tools specified: Inherits all parent tools

Builtin Presets

Skills Directory

Skills are loaded from (highest priority last):

1. Built-in: paintress_cli/skills/ (package bundled)
2. Global: ~/.config/youware-labs/paintress-cli/skills/
3. Project: .paintress/skills/

Environment Variables

TUI settings can be overridden via PAINTRESS_* environment variables:

• PAINTRESSCODETHEME
• PAINTRESSSHOWTOKEN_USAGE
• PAINTRESSCDPURL
• PAINTRESSSESSIONDIR

Quick Setup

Run paintress setup to initialize global configuration with defaults.