Skip to content

configuration.md

Latest commit

 

History

History
297 lines (221 loc) · 9.96 KB

configuration.md

File metadata and controls

297 lines (221 loc) · 9.96 KB

Configuration

Architect stores its configuration in ~/.config/architect/ using two TOML files with distinct purposes:

File Purpose Managed by
config.toml User preferences (theme, font, grid size) User (via Cmd+,)
persistence.toml Runtime state (window position, font size, terminal cwds) Application

config.toml

User-editable preferences file. Changes take effect on next launch. Open it quickly with Cmd+,.

If the file doesn't exist, Architect creates a commented template on first run (written atomically).

Font Configuration

[font]
family = "SFNSMono"  # Font family name (default: SFNSMono on macOS)
size = 14            # Base font size in points (default: 14)

The font family must be installed on your system. Common choices:

  • SFNSMono (macOS system font, default)
  • MesloLGS NF (Nerd Font with icons)
  • JetBrains Mono
  • Fira Code

Grid Configuration

[grid]
font_scale = 1.0  # Font scale in grid view (0.5-3.0, default: 1.0)

The grid size is dynamic and adjusts automatically based on the number of terminals:

  • Press Cmd+N to add a new terminal after the currently focused one — the grid expands to accommodate it
  • Press Cmd+W to close a terminal — remaining terminals compact forward to fill gaps and the grid shrinks when possible; if it's the only terminal, it restarts in place (use Cmd+Q or the window close button to quit)
  • When only one terminal is spawned, the view stays in full-screen mode
  • Grid layout maintains columns >= rows (e.g., 1x1 → 2x1 → 2x2 → 3x2 → 3x3 → ...)
  • Maximum grid size is 12×12 (144 terminals)

Window Configuration

[window]
width = 1280    # Initial window width in pixels (default: 1280)
height = 720    # Initial window height in pixels (default: 720)
x = -1          # Initial X position (-1 = centered, default: -1)
y = -1          # Initial Y position (-1 = centered, default: -1)

Note: Runtime window position and size are saved to persistence.toml and take precedence over these values after the first launch.

Theme Configuration

[theme]
background = "#0E1116"  # Terminal background color
foreground = "#CDD6E0"  # Default text color
selection = "#1B2230"   # Selection highlight color
accent = "#61AFEF"      # Accent color (focused borders, UI elements)

Colors are specified in hexadecimal format (#RRGGBB or RRGGBB). The configured theme colors are reused across terminal chrome and overlay surfaces, including modal panels and their input fields.

Default Theme Colors

Setting Default Description
background #0E1116 Dark gray background
foreground #CDD6E0 Light gray text
selection #1B2230 Darker blue for selections
accent #61AFEF Blue accent for focus indicators

ANSI Palette

Customize the 16-color ANSI palette under [theme.palette]:

[theme.palette]
# Standard colors (0-7)
black = "#0E1116"
red = "#E06C75"
green = "#98C379"
yellow = "#D19A66"
blue = "#61AFEF"
magenta = "#C678DD"
cyan = "#56B6C2"
white = "#ABB2BF"

# Bright colors (8-15)
bright_black = "#5C6370"
bright_red = "#E06C75"
bright_green = "#98C379"
bright_yellow = "#E5C07B"
bright_blue = "#61AFEF"
bright_magenta = "#C678DD"
bright_cyan = "#56B6C2"
bright_white = "#CDD6E0"

Omitted colors fall back to the built-in One Dark-inspired palette.

UI Configuration

[ui]
show_hotkey_feedback = true  # Show hotkey hints overlay (default: true)
enable_animations = true     # Enable expand/collapse animations (default: true)

Rendering Configuration

[rendering]
vsync = true  # Enable vertical sync (default: true)

Disabling vsync may reduce input latency but can cause screen tearing.

Metrics Configuration

[metrics]
enabled = false  # Enable metrics collection overlay (default: false)

When enabled, press Cmd+Shift+M to toggle the metrics overlay in the bottom-right corner. The overlay displays:

  • Frames: Total rendered frame count
  • FPS: Frames per second
  • Glyph cache: Number of cached glyph textures
  • Glyph hit rate: Cache hit percentage (hits / total accesses)
  • Glyph hits/s: Glyph cache hits per second
  • Glyph misses/s: Glyph cache misses per second
  • Glyph evictions/s: Glyph cache evictions per second

Metrics collection has zero overhead when disabled (no allocations, null pointer checks compile away).

Logging Configuration

[logging]
min_level = "info"  # One of: err, warn, info, debug (case-insensitive)

Architect writes structured application logs to:

  • macOS: ~/Library/Logs/Architect/architect.log

Each log line uses local time with an explicit timezone offset (for example, 2026-03-08T14:23:00+01:00).

Logs rotate by size. When architect.log exceeds 10 MiB, it is archived to a timestamped file (for example, architect-20260306T143000Z.log) and a new active log file is created.

Setting Default Description
min_level "info" Minimum severity written to the log file. Accepts err, warn, info, or debug (case-insensitive). Unknown values fall back to info.

Event markers (startup/shutdown and grid/full view transitions) are always recorded at INFO level.

Worktree Configuration

[worktree]
directory = "~/.architect-worktrees"  # Base directory for new worktrees
init_command = "script/setup"         # Command to run after creating a worktree
Setting Default Description
directory ~/.architect-worktrees Base directory where new worktrees are created. Each repo gets a subdirectory mirroring its path relative to $HOME, and each worktree is a subdirectory within that. Supports ~ expansion. Relative paths are resolved against $HOME.
init_command (auto-detect) Shell command to run in the new worktree after creation. When not set, Architect automatically runs script/setup or .architect-init.sh if either exists and is executable.

New worktrees are created at <directory>/<repo-subpath>/<worktree-name>, where <repo-subpath> is the repo's path relative to $HOME. For example, if the repo is at ~/dev/myproject, creating a worktree called feature-x produces ~/.architect-worktrees/dev/myproject/feature-x.

Creating worktrees outside the repository tree prevents agents (Claude Code, Codex, etc.) from discovering the parent repository's configuration files when traversing up the directory tree.

Existing worktrees (including legacy ones under .architect/ inside the repo) remain visible in the worktree picker and can be switched to or removed normally.

Complete Example

# ~/.config/architect/config.toml

[font]
family = "JetBrains Mono"
size = 13

[grid]
font_scale = 0.9

[theme]
background = "#1E1E2E"
foreground = "#CDD6F4"
selection = "#45475A"
accent = "#89B4FA"

[theme.palette]
black = "#45475A"
red = "#F38BA8"
green = "#A6E3A1"
yellow = "#F9E2AF"
blue = "#89B4FA"
magenta = "#F5C2E7"
cyan = "#94E2D5"
white = "#BAC2DE"
bright_black = "#585B70"
bright_red = "#F38BA8"
bright_green = "#A6E3A1"
bright_yellow = "#F9E2AF"
bright_blue = "#89B4FA"
bright_magenta = "#F5C2E7"
bright_cyan = "#94E2D5"
bright_white = "#A6ADC8"

[ui]
show_hotkey_feedback = true
enable_animations = true

[rendering]
vsync = true

[metrics]
enabled = false

[logging]
min_level = "info"

[worktree]
# directory = "~/.architect-worktrees"
# init_command = "script/setup"

persistence.toml

Auto-managed runtime state. Do not edit manually unless troubleshooting.

Structure

font_size = 14

terminals = [
  "/Users/me/projects/app",
  "/Users/me/projects/lib",
  "/Users/me",
]

terminal_agent_types = ["claude", "", ""]
terminal_session_ids = ["550e8400-e29b-41d4-a716-446655440000", "", ""]

[window]
width = 1440
height = 900
x = 100
y = 50

[recent_folders]
"/Users/me/projects/app" = 15
"/Users/me/projects/lib" = 8
"/Users/me" = 3

Fields

Field Description
font_size Current font size (adjusted with Cmd++/Cmd+-)
terminals Working directories for each terminal (ordered by session index)
terminal_agent_types Agent type for each terminal slot ("claude", "codex", "gemini"), or an empty string ("") when absent. Present only when at least one terminal had a running agent at quit time.
terminal_session_ids Session UUID for each terminal slot, or an empty string ("") when absent. Written alongside terminal_agent_types when an agent session ID was captured at quit. On next launch, Architect writes the corresponding resume command (e.g., claude --resume <uuid>) to the terminal as soon as the shell is ready.
[window] Last window position and dimensions
[recent_folders] Directory visit counts (up to 10 entries, sorted by frequency for Cmd+O overlay)

On launch, Architect restores terminals to their saved working directories. The grid automatically resizes to fit the number of restored terminals. If a terminal had an AI agent running when Architect was last closed, the agent is automatically resumed.

persistence.toml is written atomically (temp file + replace), so updates never leave a partially written file. Architect updates it during runtime when state changes (window move/resize, font size, terminal cwd changes, terminal spawn/despawn) and performs a final save during shutdown.

Note: Terminal cwd persistence and agent session resumption are currently macOS-only.

Older persistence.toml files that used the [terminals] table or recent_folders array are migrated automatically. Files without terminal_agent_types / terminal_session_ids are loaded normally (no agent resumption for those terminals).

Resetting Configuration

Delete the configuration files to reset to defaults:

rm ~/.config/architect/config.toml      # Reset preferences
rm ~/.config/architect/persistence.toml # Reset runtime state

Or remove the entire directory:

rm -rf ~/.config/architect