Configuration

Configuration

One TOML file is shared by the terminal and the GUI. Edit it by hand, with agentctl config --edit, or in the GUI's Settings — all three write the same file.

Location

Resolved in this order (first hit wins):

$AGENTCTL_CONFIG
$XDG_CONFIG_HOME/agentctl/config.toml
~/.config/agentctl/config.toml

agentctl config --setup seeds a starter; --edit opens it in $EDITOR; --path prints the resolved path. ~ and allow-listed $VARs expand in path values.

Shape

default_tool = "claude"          # which tool is preselected in New (informational)

# ─── dir groups ── each is a section in New; `path` is scanned one level deep,
#     sorted by `z` frecency (falls back to mtime).
[[group]]
name  = "Work"
path  = "~/code/work"
color = "#6C91BF"

# ─── tools ── each generates a launcher; `runs` is a shell command run in the chosen dir.
[[tool]]
name  = "claude"
runs  = "claude --dangerously-skip-permissions"
label = " ⚡ Projects "
color = "#6C91BF"

[[tool]]
name  = "cdx"
runs  = "codex --dangerously-bypass-approvals-and-sandbox"
label = " ✦ Codex "
color = "#A855F7"

# ─── IDEs ── each binds an fzf-style ^key: opens the editor, then launches the tool.
#     `cmd` runs via the shell with $dir = the selected absolute path.
#     Reserved keys (cannot be reused): ctrl-f ctrl-p ctrl-t ctrl-n  (and enter).
[[ide]]
key   = "ctrl-v"
label = "code"
cmd   = 'code "$dir"'

# ─── GUI / terminal ──
[gui]
terminal = "default"   # "default" (system) | Terminal | iTerm | Ghostty | Warp | kitty | WezTerm | cmux | custom
# launch_command = 'open -a "iTerm" {{script}}'   # only for terminal = "custom"; {{script}} / {{cmd}} / {{dir}}
# hotkey = "cmd+shift+m"                            # global shortcut to open the GUI window

# ─── theme (optional) ──
# [theme]
# accent = "#FF9F43"

Notes

• Tool names claude / cdx are just labels for the Claude / Codex launchers — rename them freely; they are not shell commands.
• The shell variable is lowercase $dir in runs / IDE cmd; commands run via ${SHELL:-/bin/zsh} -c.
• --dangerously-skip-permissions is in the default Claude command because this is a launcher for your own machine. Change runs to drop it.
• A colliding [[ide]].key on a reserved key is dropped with a warning, never a crash.
• The GUI hotkey is easiest to set in Settings — click the recorder field and press the combo. See GUI.