[Feature] Config file support (.ghwt.toml/.ghwt.yaml)

[renekris]

Problem Statement

Configuration is fragmented across CLI flags and environment variables. No single config file to manage ALL ghwt settings. Users must set multiple environment variables or CLI flags for every invocation.

Affected Code

• config.py - Configuration management (partial)
• main.py - CLI option handling
• worktree_creator.py - WorktreeSettings usage
• github_fetcher.py - Timeout values

Proposed Solution

Add support for a comprehensive config file (.ghwt.json or .ghwt.yaml) that manages ALL settings in one place, with proper precedence: CLI > config file > env > defaults.

Configuration Categories

The config file should support all these settings:

1. Worktree Management

   • worktree_root - Root directory for worktrees
   • auto_cleanup - Auto-remove old worktrees after N days

2. Timeouts

   • gh_cli_timeout - GitHub CLI timeout (default: 30s)
   • workmux_timeout - workmux timeout (default: 60s)
   • file_write_timeout - File write timeout (default: 5s)

3. Branch Naming

   • branch_title_word_limit - Max words in branch name (default: 3)
   • branch_prefix_issue - Prefix for issue branches (default: "issue")
   • branch_prefix_pr - Prefix for PR branches (default: "pr")

4. Editor Integration

   • editor_command - Command to open editor (default: "shuvcode")
   • skip_editor - Skip auto-opening editor (bool)

5. Template Settings

   • template_path - Path to custom WT-TASK.md template
   • include_comments - Include issue/PR comments in WT-TASK.md (bool)

6. Logging

   • log_level - Debug, Info, Warning, Error (default: "info")
   • log_format - JSON or plain text

7. Folder Isolation (future)

   • isolate_to_worktree - Restrict agent to worktree only (bool)
   • allowed_paths - Additional paths agent can access (list)

Implementation Steps:

• Add pydantic>=2.0.0 or pydantic-settings>=2.0.0 to dependencies
• Implement config file search with precedence:
  • ~/.config/ghwt/config.json (global)
  • .ghwt.json or .ghwt.yaml (project in CWD)
• Create comprehensive GhwtConfig dataclass/pydantic model
• Implement config loading with proper precedence: CLI > file > env > defaults
• Add --config option to CLI to specify custom config file
• Add --print-config option to show effective configuration
• Add ghwt config init command to generate default config file
• Add ghwt config validate command to validate config file
• Update all components to use config instead of env/CLI args
• Create example .ghwt.json documentation
• Update README with config file usage and examples
• Add tests for config file loading and precedence
• Add tests for config validation

Example Config Files

JSON format (.ghwt.json):

{
  "$schema": "https://raw.githubusercontent.com/owner/ghwt/main/config-schema.json",
  "worktree_root": "~/projects/worktrees",
  "gh_cli_timeout": 30,
  "workmux_timeout": 60,
  "file_write_timeout": 5,
  "branch_title_word_limit": 3,
  "branch_prefix_issue": "issue",
  "branch_prefix_pr": "pr",
  "editor_command": "shuvcode",
  "skip_editor": false,
  "template_path": "./custom-wt-task.md",
  "include_comments": true,
  "log_level": "info",
  "log_format": "plain",
  "isolate_to_worktree": true,
  "allowed_paths": []
}

YAML format (.ghwt.yaml):

# ghwt configuration file
worktree_root: ~/projects/worktrees
timeouts:
  gh_cli: 30
  workmux: 60
  file_write: 5
branch:
  title_word_limit: 3
  prefix_issue: issue
  prefix_pr: pr
editor:
  command: shuvcode
  skip: false
template:
  path: ./custom-wt-task.md
  include_comments: true
logging:
  level: info
  format: plain
isolation:
  isolate_to_worktree: true
  allowed_paths: []

Alternative Approaches

• Use Dynaconf: Multi-format config (TOML/YAML/INI/JSON) with environment variable support
• Use pydantic-settings: Pythonic config management with multiple sources and validation
• Use click-config-file2: Click extension for config file support
• Keep TOML: Simpler than YAML, better than JSON for human editing

Recommendation: Use YAML (.ghwt.yaml) as primary format - more readable than JSON, supports comments, widely used in Python ecosystem, better for hierarchical configs.

Area

• Feature/Configuration

Estimated Effort

• Large (2-3d)

Acceptance Criteria

• ghwt reads ~/.config/ghwt/config.yaml (global)
• ghwt reads .ghwt.yaml in project directory
• Config precedence: CLI flags > config file > env vars > defaults
• Add --config option to specify custom config file path
• Add --print-config option to show effective configuration
• Add ghwt config init command to generate default config
• Add ghwt config validate command to validate config
• All settings manageable via config file (worktree_root, timeouts, branch naming, editor, template, logging, isolation)
• Document config file format with examples in README
• Add tests for config loading, precedence, and validation
• Support both .ghwt.yaml (primary) and .ghwt.json (fallback) formats

Related Issues

• Issue [Feature] Direct prompt passing to agent worktree window #6: [Feature] Direct prompt passing to agent worktree window - might need worktree isolation config