Paintress CLI Configuration

Name: cli-config
Rating: 92
Author: youware-labs

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

Configuration Locations

Level	Location	Priority
Global	`~/.config/youware-labs/paintress-cli/`	Default
Project	`.paintress/`	Overrides global

Configuration Files

config.toml (Global)

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

toml

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

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:

json

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

Custom Slash Commands

Define custom commands in config.toml:

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

markdown

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

Field	Required	Description
`name`	Yes	Unique identifier, becomes the tool name
`description`	Yes	Shown to model when selecting tools
`instruction`	No	Injected into parent's system prompt
`tools`	No	Required tools - ALL must be available
`optional_tools`	No	Optional tools - included if available
`model`	No	`"inherit"` or model name

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

Preset	Purpose	Required Tools
`debugger`	Root cause analysis	glob, grep, view, ls
`explorer`	Codebase navigation	glob, grep, view, ls
`code-reviewer`	Code quality review	glob, grep, view, ls
`searcher`	Web research	search

Skills Directory

Skills are loaded from (highest priority last):

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

Environment Variables

TUI settings can be overridden via PAINTRESS_* environment variables:

•PAINTRESS_CODE_THEME
•PAINTRESS_SHOW_TOKEN_USAGE
•PAINTRESS_CDP_URL
•PAINTRESS_SESSION_DIR

Quick Setup

Run paintress setup to initialize global configuration with defaults.