#3 - Configuration system — TOML loading & defaults - charles/peon

claude-desktop commented

2026-04-16 11:28:04 +00:00

Collaborator

User story

As a user launching forge-agent for the first time, I want the application to load configuration from ~/.config/forge-agent/config.toml (creating a sensible default if absent), so that I can customize provider paths, terminal mode, git signature, and keybindings.

Acceptance criteria

Config structs

AppConfig top-level struct with sections: general, providers, terminal, git, keybindings
GeneralConfig with data_dir (default ~/.local/share/forge-agent)
ProvidersConfig with claude_code_path and codex_path (both optional, auto-detected if empty)
TerminalConfig with mode enum (Embedded, Kitty, Foot, Auto) and EmbeddedTerminalConfig (font_family, font_size, scrollback_lines)
GitConfig with commit_name, commit_email, auto_checkpoint: bool
keybindings as HashMap<String, String> for user overrides

Loading logic (`load_config()`)

Reads from ~/.config/forge-agent/config.toml if it exists
Creates config dir + writes default config if file is absent
Default config embedded via include_str! from a default_config.toml file
Returns typed AppConfig or a clear error on parse failure
data_dir path with ~ is expanded to actual home directory

Default config file

default_config.toml matches the template in spec §13 exactly

Tests

Test: loading default config from embedded string parses without error
Test: missing optional fields get correct defaults
Test: invalid TOML produces a clear error message

Out of scope

Settings UI (frontend story)
Runtime config reloading (post-v1)

References

Spec §13 (Configuration)

Dependencies

Blocked by: none
Blocks: #9, #10, #11, #13, #17, #18
Branch off: main
Full graph: #21

## User story As a **user launching forge-agent for the first time**, I want the application to load configuration from `~/.config/forge-agent/config.toml` (creating a sensible default if absent), so that I can customize provider paths, terminal mode, git signature, and keybindings. ## Acceptance criteria ### Config structs - [ ] `AppConfig` top-level struct with sections: `general`, `providers`, `terminal`, `git`, `keybindings` - [ ] `GeneralConfig` with `data_dir` (default `~/.local/share/forge-agent`) - [ ] `ProvidersConfig` with `claude_code_path` and `codex_path` (both optional, auto-detected if empty) - [ ] `TerminalConfig` with `mode` enum (`Embedded`, `Kitty`, `Foot`, `Auto`) and `EmbeddedTerminalConfig` (font_family, font_size, scrollback_lines) - [ ] `GitConfig` with `commit_name`, `commit_email`, `auto_checkpoint: bool` - [ ] `keybindings` as `HashMap<String, String>` for user overrides ### Loading logic (`load_config()`) - [ ] Reads from `~/.config/forge-agent/config.toml` if it exists - [ ] Creates config dir + writes default config if file is absent - [ ] Default config embedded via `include_str!` from a `default_config.toml` file - [ ] Returns typed `AppConfig` or a clear error on parse failure - [ ] `data_dir` path with `~` is expanded to actual home directory ### Default config file - [ ] `default_config.toml` matches the template in spec §13 exactly ### Tests - [ ] Test: loading default config from embedded string parses without error - [ ] Test: missing optional fields get correct defaults - [ ] Test: invalid TOML produces a clear error message ## Out of scope - Settings UI (frontend story) - Runtime config reloading (post-v1) ## References - Spec §13 (Configuration) ## Dependencies - **Blocked by:** none - **Blocks:** #9, #10, #11, #13, #17, #18 - **Branch off:** `main` - **Full graph:** #21

claude-desktop added this to the v0.1.0 milestone

2026-04-16 11:28:04 +00:00

claude-desktop added the

area:config

type:user-story

labels

2026-04-16 11:28:04 +00:00

claude-desktop referenced this issue

2026-04-16 20:22:35 +00:00

v0.1.0 dependency tree and implementation order #21

claude-desktop referenced this issue

2026-04-16 20:25:46 +00:00