Configuration

towl uses a .towl.toml file in the project root for configuration. All fields have sensible defaults -- you only need to override what you want to change.

Config File

Create .towl.toml manually or run towl init:

[parsing]
file_extensions = ["rs", "toml", "json", "yaml", "yml", "sh", "bash"]
exclude_patterns = ["target/*", ".git/*"]
include_context_lines = 3

[github]
owner = "your-username"
repo = "your-repo"

Parsing Section

Field	Type	Default	Description
`file_extensions`	`string[]`	`["rs", "toml", "json", "yaml", "yml", "sh", "bash"]`	File extensions to scan
`exclude_patterns`	`string[]`	`["target/", ".git/"]`	Glob patterns to exclude
`include_context_lines`	`integer`	`3`	Number of surrounding lines to capture (1-50)
`comment_prefixes`	`string[]`	`["//", "^\\s#", "/\\", "^\\s\\"]`	Regex patterns for comment line detection
`todo_patterns`	`string[]`	See below	Regex patterns for TODO extraction
`function_patterns`	`string[]`	See below	Regex patterns for function context detection

Default TODO Patterns

todo_patterns = [
    "(?i)\\bTODO:\\s*(.*)",
    "(?i)\\bFIXME:\\s*(.*)",
    "(?i)\\bHACK:\\s*(.*)",
    "(?i)\\bNOTE:\\s*(.*)",
    "(?i)\\bBUG:\\s*(.*)",
]

All patterns are case-insensitive by default. Each pattern must contain a capture group (.*) for extracting the description text.

Default Function Patterns

function_patterns = [
    "^\\s*(pub\\s+)?fn\\s+(\\w+)",            # Rust
    "^\\s*def\\s+(\\w+)",                      # Python
    "^\\s*(async\\s+)?function\\s+(\\w+)",     # JavaScript
    "^\\s*(public|private|protected)?\\s*(static\\s+)?\\w+\\s+(\\w+)\\s*\\(",  # Java/C#
    "^\\s*func\\s+(\\w+)",                     # Go/Swift
]

Pattern Limits

Each pattern field is limited to 100 entries. Individual regex patterns are limited to 256 characters. These limits prevent denial-of-service via malicious configuration files.

GitHub Section

Field	Type	Default	Description
`owner`	`string`	Auto-detected from git remote	GitHub repository owner
`repo`	`string`	Auto-detected from git remote	GitHub repository name
`token`	--	--	Set via environment variable only
`rate_limit_delay_ms`	`integer`	`100`	Delay in ms between GitHub API calls

Note: The GitHub token is never stored in the config file. Use the TOWL_GITHUB_TOKEN environment variable.

LLM Section

Field	Type	Default	Description
`provider`	`string`	`claude`	LLM provider: `"claude"`, `"openai"`, `"claude-code"`, or `"codex"`
`model`	`string`	`claude-opus-4-6`	Model identifier
`base_url`	`string`	Provider default	Custom endpoint URL (for Ollama, vLLM, etc.)
`max_concurrent_analyses`	`integer`	`5`	Max concurrent LLM requests (1-20)
`max_analyse_count`	`integer`	`50`	Max TODOs to analyse per scan (1-500)
`max_tokens`	`integer`	`4096`	LLM response token limit
`command`	`string`	Auto (provider-dependent)	Override CLI binary path
`args`	`string[]`	Auto (provider-dependent)	Override CLI arguments

Note: The LLM API key is never stored in the config file. Use the TOWL_LLM_API_KEY environment variable. See AI Analysis for usage details.

Environment Variables

Seven environment variables override config file values:

Variable	Overrides	Description
`TOWL_GITHUB_TOKEN`	`github.token`	GitHub personal access token (stored as `SecretString`, masked in logs)
`TOWL_GITHUB_OWNER`	`github.owner`	GitHub repository owner
`TOWL_GITHUB_REPO`	`github.repo`	GitHub repository name
`TOWL_LLM_API_KEY`	`llm.api_key`	LLM API key (stored as `SecretString`, env-only)
`TOWL_LLM_PROVIDER`	`llm.provider`	LLM provider (`"claude"` or `"openai"`)
`TOWL_LLM_MODEL`	`llm.model`	LLM model identifier
`TOWL_LLM_BASE_URL`	`llm.base_url`	Custom LLM endpoint URL

Config Loading Order

Built-in defaults
.towl.toml file (or path specified with --path)
Environment variable overrides (TOWL_GITHUB_*, TOWL_LLM_*)

If no .towl.toml exists, defaults are used without error.

Viewing Active Configuration

towl config

Example output:

📋 Towl Configuration
┌─ Parsing
│  ├─ File Extensions: bash, json, rs, sh, toml, yaml, yml
│  ├─ Exclude Patterns: target/*, .git/*
│  ├─ Context Lines: 3
│  ├─ Comment Prefixes:
│  │  ├─ //
│  │  ├─ ^\s*#
│  │  ├─ /\*
│  │  └─ ^\s*\*
│  ├─ TODO Patterns:
│  │  ├─ (?i)\bTODO:\s*(.*)
│  │  ...
│  └─ Function Patterns:
│     ├─ ^\s*(pub\s+)?fn\s+(\w+)
│     ...
└─ GitHub
   ├─ Owner: glottologist
   ├─ Repo: towl
   └─ Token: not set

Keyboard shortcuts

towl Documentation