Everything in config.toml

kamaji follows the XDG base directory spec, honoring $XDG_CONFIG_HOME and $XDG_DATA_HOME if set. The config file is created with defaults on first run, so there's nothing to set up by hand.

The pid/addr files fall back to $XDG_CACHE_HOME, then ~/.cache, when $XDG_RUNTIME_DIR is unset. They let the TUI and CLI find — or avoid double-spawning — a running kamajid daemon.

This is the file kamaji writes on first run. Copy it, then tweak the bits you care about — the headline ones being default_agent and worktree_base.

default_agent = "claude"
worktree_base = "{root}/../kamaji-worktrees"
base_branch = "auto"
zellij_bar = "auto"
theme = "catppuccin"

[daemon]
bind = "127.0.0.1:8755"
log_format = "human"
log_level = "info"
web_theme = "auto"

[auto_review]
enabled = true
poll_interval_secs = 5

[auto_review.patterns]
codex = []
copilot = []

[agents.claude]
with_prompt = ["claude", "{prompt}"]
no_prompt = ["claude"]
resume = ["claude", "--continue"]

[agents.codex]
with_prompt = ["codex", "{prompt}"]
no_prompt = ["codex"]
resume = ["codex", "resume", "--last"]

[agents.copilot]
with_prompt = ["copilot", "-i", "{prompt}"]
no_prompt = ["copilot", "-i"]
resume = ["copilot", "--continue"]copy

default_agent default "claude"

The AI agent pre-selected when you create a new ticket. The value must match one of the [agents.<name>] sections below — out of the box that's claude, codex, or copilot. You can still pick a different agent per ticket in the create form; this just sets the default.

worktree_base default "{root}/../kamaji-worktrees"

Where kamaji creates the git worktree for each ticket. {root} expands to the project's root directory, so the default puts worktrees in a sibling folder alongside — not inside — your main working tree, keeping them out of your repo. Each worktree is named kamaji-<id>-<slug>. Point this anywhere you like, e.g. "/tmp/kamaji-worktrees" or "{root}/.worktrees".

base_branch default "auto"

The branch new ticket branches are created from. "auto" detects the repo's default branch (origin/HEAD), falling back to the current HEAD. Set an explicit name like "main" or "develop" to override.

zellij_bar default "auto"

The bar style for spawned zellij sessions. "auto" matches your zellij default_layout (compact → compact bar, otherwise tab-bar + status-bar). Force a style with "compact", "default", or "none" (no bars at all).

theme default "catppuccin"

The board colorscheme: "catppuccin", "tokyonight", "gruvbox", "nord", or "default" (uses your terminal's own 16 colors). You can switch live from the board with t — the choice is saved back here. Unknown names fall back to catppuccin.

The [daemon] table configures kamajid — the background daemon that owns the database, serves the browser board, and streams updates to both front-ends. All keys are optional. Changes take effect on the next daemon start — see restarting after config changes.

daemon.bind default "127.0.0.1:8755"

The address the daemon binds the browser board and HTTP/SSE API on. The terminal proxy — which streams agent terminals into the browser board — always binds the next port up, so the default puts it on :8756.

daemon.log_format default "human"

Daemon log format: "human" for readable lines, or "json" for structured logs you can ship somewhere.

daemon.log_level default "info"

The daemon's log filter. Overridable at runtime with the KAMAJID_LOG environment variable.

daemon.web_theme default "auto"

Colorscheme for the browser zellij-web sessions. "auto" respects your own zellij config — kamaji injects nothing. "match" pulls sessions toward the board's palette: it forces the built-in catppuccin-mocha theme on zellij's chrome and applies the board palette to the browser terminal. Any other value is a zellij theme name to force on the chrome. Forcing a theme is session-wide (it also recolors the TUI view) and takes effect for sessions created after a daemon restart.

The daemon runs a poll loop that watches in-progress agent sessions and moves a ticket to Review when its agent goes idle (waiting for input). Detection polls each session's screen and matches per-agent idle patterns; the move is broadcast over SSE so both front-ends update on their own. A later manual move clears the auto-review provenance.

auto_review.enabled default true

Set false to keep all moves manual — tickets then stay in In Progress until you move them yourself.

auto_review.poll_interval_secs default 5

How often, in seconds, the daemon polls each in-progress session to check whether its agent has gone idle.

auto_review.patterns default {}

Extra idle-detection patterns per agent, if the built-in defaults miss your setup — e.g. [auto_review.patterns] with codex = ["…"]. Patterns are matched against the session's screen contents.

Each [agents.<name>] section defines how kamaji launches that CLI. Commands are passed directly as argv — there is no shell, so no quoting or globbing surprises. Add or edit a section to support any other agent CLI, then reference its name from default_agent or pick it per ticket.

with_prompt

The argv used when the ticket has an initial prompt. {prompt} is replaced with the prompt text — for example ["claude", "{prompt}"] launches claude with the prompt as its first argument.

no_prompt

The argv used when the ticket has no initial prompt — kamaji just opens the agent, e.g. ["claude"].

resume

The argv used to resume a conversation in a session that survived a reboot, e.g. ["claude", "--continue"]. If omitted, kamaji derives a default from the binary (<bin> --continue, or codex resume --last). The agent picks up its previous conversation rather than replaying the original prompt.

Want a different CLI? Add a section like [agents.aider] with its own with_prompt / no_prompt / resume arrays, set default_agent = "aider", and you're done.