Configuration

Configuration

One TOML file configures the terminal menu. Edit it by hand or with agentctl config --edit.

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)
permission_mode = "auto"         # "auto" (default) or "bypassPermissions" (opt in to --dangerously-skip-permissions)

# ─── 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 --permission-mode auto"
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"'

# ─── 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.
• Permissions: Claude starts and resumes with --permission-mode auto. Set permission_mode = "bypassPermissions" to use --dangerously-skip-permissions instead (Resume + built-in claude tool; an explicit [[tool]] runs is used verbatim).
• A colliding [[ide]].key on a reserved key is dropped with a warning, never a crash.
• An old config's [gui] table is ignored (the menu-bar GUI was removed in 0.11.0).