Configuration

Configure Agent Dash behavior

Agent Dash reads its configuration from ~/.config/agent-dash/config.toml or ~/.config/agent-dash/config.json. Both formats use the same keys.

If both files exist, config.toml is used and config.json is ignored. If neither exists, defaults apply. Changes are picked up live, including creating or removing either file.

Options

The same configuration as JSON:

command

The command used to start a new session (c). Resuming a closed session runs it with --resume <session id> appended. Defaults to "claude".

modes

Optional. Named alternatives to command, set as a [[modes]] array (TOML) or a modes array (JSON). Each entry needs a name and a command. With at least one mode, the new-session dialog (c) gets a Mode row right under Folder; leave it unset and the row is hidden.

The first mode is always default, which runs the top-level command; yours follow in config order as 1, 2, and so on. The dialog starts on default every time. With Mode focused (Tab), press its number (0 to 9) to choose it, or use ←/→ or the arrow keys and Ctrl+n/Ctrl+p to step through the list below, which shows each mode's command. Enter starts the session with the chosen mode's command, also when a worktree is created. Resuming a closed session always uses command.

worktree

Optional. Shell commands that create git worktrees, set under a worktree table (TOML) or object (JSON). With create set, the new-session dialog (c) gets a Worktree checkbox; leave it unset and the checkbox is hidden.

With the checkbox on, Name and Base take branch names, and the list at the bottom of the dialog suggests branches for whichever field has focus (local branches for Name, local and remote for Base, most recently committed first). Pick from the list like zsh's menu completion: the arrow keys or Ctrl+n/Ctrl+p write the highlighted suggestion into the field, and moving back up past the first one restores what the field held before (what you typed, or the prefilled Base). The list is filtered by what you typed, so it stays put while you cycle. Tab only moves to the next field and Enter always creates the session from what the fields contain. A line under the fields says what the name will do:

• blank: a random new branch, like stellar-ptarmigan, from Base
• not a local branch: a new branch from Base
• a local branch that already has a worktree: the session opens in that worktree and no command runs (Base is ignored)
• a local branch without a worktree: runs checkout (Base is ignored)

Base starts as the folder's current branch. The checkbox starts as you left it the last time you created a session.

Commands run with sh -c in the chosen folder, which is the repository root when the folder is inside a git repository. The placeholders are replaced with the values you entered, already shell-quoted, so don't add quotes around them. Any other {{...}} placeholder, including {{base}} in checkout, is an error.

Agent Dash then finds the worktree through git worktree list, so the command must leave a worktree checked out on the branch called {{name}}. The new session starts in that worktree and is named after it. The commands run in the background, so slow hooks don't freeze the UI; a failure shows the last line of its stderr.

layout

Controls the pane layout direction.

theme

"dark" (default) or "light". The AGENT_DASH_THEME environment variable (light, anything else means dark) overrides it.

sharedState

When true, which groups are collapsed is shared by every Agent Dash instance. By default it is kept per tmux client. View settings (S) and the session list itself are always shared.

autoTrackSessions

When true (default), every Claude session found running in a tmux pane is added to the session list. When false, only sessions you start with c are added automatically; other running Claude panes stay out of the list. Sessions already in the list keep updating either way: they still resume, archive when closed, and get the unread mark. Use agent-dash import to add existing sessions by hand.

defaultTmuxSession

Closing a live session (a to archive it, or x) exits Claude Code and removes its tmux pane. When that pane was the last one in its tmux session, tmux would detach any client attached to it. Agent Dash moves those clients to another session first: the one named here if it exists, otherwise the session you attached to most recently. With no other session, the clients are left alone and tmux detaches them. Unset by default.

previewScrollMode

Controls how scrolling works in the Claude Code preview pane. Set it as previewScrollMode under the claudeCode table (TOML) or object (JSON).

Data Storage