Configuration

Kumo reads a single config file at ~/.config/kumo/config.toml. The old flat key = value file at ~/.config/kumo/config (and the legacy ~/.kumo) still reads as a fallback, but config.toml wins when both exist.

# ~/.config/kumo/config.toml

ai-cmd = "claude --model sonnet"
update-check = true

[terminal]
shell = "/bin/zsh"

[keymap]
leader = "ctrl+b"

# Leader bindings are remappable: override a stock key or add a new one.
[keymap.bindings]
s = "split-vertical"   # now leader+s splits vertically
x = "close-pane"

[notifications]
position = "top-right"  # top-left | bottom-right | bottom-left | center | off
sound = true            # audible chime on blocked/finished transitions

[worktree]
shared-dirs = ["node_modules", ".cache"] # gitignored dirs shared by worktrees
base-ref = "origin/main" # optional base for task-oriented worktrees
expose-socket = true    # pass KUMO_SOCKET_PATH and KUMO_BIN_PATH to panes

[jira]
site = "https://your-company.atlassian.net"
email = "you@example.com"

Config builder

leader chord

key bindings

AI command

shell

sidebar

project (default): worktrees with inline agents, collapses inactive — branch dimmed, finder on leader+f · divided: stacked spaces + agents · tabs: classic two-tab

startup

agent notifications

status bar

click a zone to anchor the toast there

~/.config/kumo/config.toml

# ~/.config/kumo/config.toml
# Overrides only — every other option keeps its default.

[keymap.bindings]
s = "split-vertical"

Live-generated — only options that differ from the defaults are written, in canonical form (`[terminal] shell`, `[keymap] leader`).

The generator writes only what differs from the defaults, in canonical form. Paste the result into ~/.config/kumo/config.toml; the daemon reloads it automatically. kumo reload remains available for an explicit refresh.

Install the agent skill

ai-cmd chooses which AI CLI Kumo starts. Install Kumo's bundled skill in that agent as a separate, one-time step so it can discover panes, wait without polling, read terminal output, and coordinate other agents. Choose your agent and run the generated command:

Install for Codex

Personal skill · available in every project · ~/.agents/skills/kumo/SKILL.md

kumo agent skill --output ~/.agents/skills/kumo/SKILL.md

The skill is embedded in the kumo binary, so the installed instructions match your CLI version. Re-run the same command after updating Kumo to refresh it. kumo agent skill without --output prints the skill instead.

You can manage the same targets from MENU → settings → agents. Select an agent and press Enter (or click it) to install the skill; selecting an installed skill removes its SKILL.md. Update available means the file exists but its contents differ from the skill bundled with the running Kumo version—usually because Kumo was upgraded, but also possibly because the file was edited. The update action replaces that file with the bundled version.

Worktree isolation

The optional [worktree] section controls what new isolated worktrees share with the primary checkout:

Key	Description
`shared-dirs`	Relative, gitignored directories to link into each new worktree (for example `node_modules` or `.cache`). Absolute paths and paths containing `..` are ignored. Missing, non-directory, or non-gitignored sources are skipped with a warning.
`base-ref`	Optional Git ref used as the base for task-oriented worktrees. Without it, Kumo discovers `origin/HEAD`, then common `main`/`master` refs, and finally the current commit. An explicit `--from` still wins.
`expose-socket`	When `true` (the default), panes receive `KUMO_SOCKET_PATH` and `KUMO_BIN_PATH` so an agent can drive its own Kumo session.

For files that should be copied rather than shared, add a .worktreeinclude file at the repository root. It uses the same pattern syntax as .gitignore, including *, **, ?, character ranges, comments, root-anchored patterns, and ! negations. Matching files must also be ignored by Git. For example:

# Local configuration copied into each isolated checkout
/.env
app/**/.env
!app/fixtures/**
.vscode/settings.json

These paths are copied when kumo worktree create --ai creates a checkout.

Jira Cloud

Set [jira].site and [jira].email, then expose an Atlassian API token as KUMO_JIRA_API_TOKEN to the Kumo daemon. KUMO_JIRA_SITE and KUMO_JIRA_EMAIL can override the file settings. Tokens are intentionally not read from config.toml. The Jira worktree tab and worktree create --jira use Jira Cloud REST API v3 to load the issue summary and derive the branch; the linked issue key, URL, and title are stored with the worktree metadata.

The current 0.7 flow starts an agent when --agent is supplied, but does not send a task automatically. After the agent is ready, submit work explicitly with kumo agent prompt; automatic task submission is planned for 0.7.1.

Reference

Prop

Type

File locations

Overrides follow the usual conventions:

Location	Path / override
Config	`~/.config/kumo/config.toml` — override with `KUMO_CONFIG_DIR` or `XDG_CONFIG_HOME`
Runtime state	`~/.local/state/kumo/` — override with `KUMO_STATE_DIR` or `XDG_STATE_HOME`
IPC socket	`$XDG_RUNTIME_DIR/kumo`

Live reload

The daemon watches the canonical, flat, and legacy config files plus agent-detection/*.toml, then applies the same reload path automatically. kumo reload (or MENU → reload) triggers it explicitly. Reload applies shell, ai-cmd, leader, and keymap.bindings live to panes spawned from then on. new-cwd, [notifications] position, and [notifications] sound apply instantly. MENU → config opens the config file in an editor pane inside the session ($VISUAL → $EDITOR → vi).