Configuration
Every key of ~/.config/komrad/config.toml with its built-in default. Write only the keys you are changing; an unknown key is an error.
Top level#
| Key | Default | Description |
|---|---|---|
default_harness | "claude" | Which agent CLI a new agent runs when neither the agent nor its workflow names one. It has to be a harness this binary implements, so it is one of the names under [harness] below. |
auto_setup | false | Whether 'komrad open' sets up a workflow for the git checkout it is run in, with a worktree for each agent and an orchestrator standing by, when no workflow covers that directory yet. |
vim_mode | false | Edit the panel's text fields the way vim does. A form's field opens in insert mode, esc goes to normal mode, and a second esc closes it. The filter, search and rename lines close on esc, and ctrl+f puts one in normal mode, after which esc works as it does in a form. |
shell | "" | The shell komrad starts agents, workflow scripts and the panel's terminal in, as an absolute path. It has to be a POSIX shell such as zsh, bash or sh, since komrad launches every agent through it. Empty takes $SHELL, and /bin/sh when that is unset too. |
[harness.claude]#
| Key | Default | Description |
|---|---|---|
flags | "" | Flags appended to every agent's command line for this CLI, ahead of the flags that agent carries itself. |
trust_launch_dirs | false | Records each agent's directory as trusted in this CLI's own config when on, before launching it. The CLI asks whether a directory is trusted the first time it runs there and waits for an answer, which it reads only from that file, so an agent in a fresh worktree otherwise starts blocked and shows here as waiting. Turning this on edits that file on your behalf. |
[harness.codex]#
| Key | Default | Description |
|---|---|---|
flags | "" | Flags appended to every agent's command line for this CLI, ahead of the flags that agent carries itself. |
trust_launch_dirs | false | Records each agent's directory as trusted in this CLI's own config when on, before launching it. The CLI asks whether a directory is trusted the first time it runs there and waits for an answer, which it reads only from that file, so an agent in a fresh worktree otherwise starts blocked and shows here as waiting. Turning this on edits that file on your behalf. |
[usage]#
Limits how many agents may run at once.
| Key | Default | Description |
|---|---|---|
max_agents | 50 | The number of unarchived agents this engine may run at once. Past it, komrad refuses a create. The default is well above what anyone opens by hand and low enough to catch a caller in a loop. |
[writer]#
What every writer launches with when its workflow leaves a setting empty for writers.
| Key | Default | Description |
|---|---|---|
harness | "" | The harness an agent in this role runs. Empty takes default_harness. |
flags | "" | The flags an agent in this role launches with when its workflow names neither a harness nor flags for the role. |
context_file | "" | A file whose text komrad adds to the system prompt of every agent in this role, after the global context and before the workflow's. Read at each launch. Empty adds none. |
auto_compaction | 250000 | The conversation size in tokens an agent is held under, summarizing its history a little before it gets there. Lower costs less per turn and forgets more. 0 leaves the agent CLI's own default, and a value the CLI will not take is moved to the nearest one it will. |
[reviewer]#
What every reviewer launches with and is held to when its workflow leaves a setting empty for reviewers.
| Key | Default | Description |
|---|---|---|
harness | "" | The harness an agent in this role runs. Empty takes default_harness. |
flags | "" | The flags an agent in this role launches with when its workflow names neither a harness nor flags for the role. |
context_file | "" | A file whose text komrad adds to the system prompt of every agent in this role, after the global context and before the workflow's. Read at each launch. Empty adds none. |
auto_compaction | 250000 | The conversation size in tokens an agent is held under, summarizing its history a little before it gets there. Lower costs less per turn and forgets more. 0 leaves the agent CLI's own default, and a value the CLI will not take is moved to the nearest one it will. |
max_per_task | 3 | The number of live reviewers one task may hold at once. Reviewers read their task's checkout, so this is deliberately far lower than max_agents. |
archive_on_approval | true | Archives a reviewer once it releases an approval when on. Turn it off to keep approved reviewers in the sidebar until you archive them yourself. |
[orchestrator]#
What every orchestrator launches with and is held to when its workflow leaves a setting empty for its orchestrator.
| Key | Default | Description |
|---|---|---|
harness | "" | The harness an agent in this role runs. Empty takes default_harness. |
flags | "" | The flags an agent in this role launches with when its workflow names neither a harness nor flags for the role. |
context_file | "" | A file whose text komrad adds to the system prompt of every agent in this role, after the global context and before the workflow's. Read at each launch. Empty adds none. |
auto_compaction | 150000 | The conversation size in tokens an agent is held under, summarizing its history a little before it gets there. Lower costs less per turn and forgets more. 0 leaves the agent CLI's own default, and a value the CLI will not take is moved to the nearest one it will. |
max_tasks | 0 | The number of live tasks one orchestrator may have started at once. 0 leaves max_agents as the only cap. |
[layout]#
Sets how much of the window the panel's sidebar, the stage beside it, and the info pane each take, and which side of the stage the info pane opens on.
| Key | Default | Description |
|---|---|---|
sidebar_width | 47 | The width, in columns, the panel's sidebar opens at. Dragging the divider afterwards moves it, and the panel follows. |
info_side | "below" | Which side of the stage the info pane opens on, "below" or "above". That pane is where the server log and an editor are drawn. |
info_height | 0.4 | The height the info pane opens at, either a share of the stage's height below one or a whole number of rows. The default is tall enough to read a log in without pushing the agent above it off the screen. |
details_height | 9 | The number of lines the details under the list draw, either a share of the sidebar's height below one or a whole number of lines. The marks the hovered row is carrying are spelled out in that same room, ahead of the fields. The chrome around them is added on top, and the two together never take more than half the sidebar's height. Once the details hold the keys they grow past this to show the whole record, as far as the sidebar allows. |
[keybindings]#
Panel keybindings, scoped to the screen each binding acts in.
[keybindings.agents]#
The agents list, the panel's main screen.
| Key | Default | Description |
|---|---|---|
rename | ["r"] | Rename the hovered agent, or the slug of the hovered task. |
[keybindings.archive]#
The archive screen.
| Key | Default | Description |
|---|---|---|
rename | ["r"] | Rename the agent or live workflow under the cursor, typed over its row. |
[keybindings.archive_menu]#
The archive menu, nested under the menu on the hovered row of the archive.
| Key | Default | Description |
|---|---|---|
archive | ["a"] | Archive the agent, task, workflow or schedule, or every chosen task. |
delete | ["d"] | Destroy the row for good, with its transcript or its run history, archiving a live task first, which takes its agents, documents, reviews and worktree with it. On a worktree on the storage list it deletes the directory, through the task delete when an archived task answers for it. Nothing undoes it, so it asks first. |
restore | ["r"] | Put the row back in the panel. |
restore_open | ["o"] | Put the agent back in the panel and open it, which relaunches its conversation in a pane and takes you to it. The entry is gray on an agent that never got as far as starting. |
clear | ["c"] | Deletes every unused worktree. That covers every directory whose agent is archived, through the agent delete and its hooks, and every directory agents don't answer for. A directory with a live agent in it is never deleted. The entry is only on the system view's storage list, and is gray when every worktree is in use. |
shrink | ["s"] | Shrink the worktree of an archived task, or of every chosen one. Shrinking deletes the gitignored dependency and build directories that sit beside the file that rebuilds them, in a background job. The entry is gray when nothing it covers has anything to shrink. |
[keybindings.clipboard]#
The key that copies what the cursor is on, shared by every screen that copies.
| Key | Default | Description |
|---|---|---|
copy | ["y"] | Copy the field, log line or message the cursor is on to the system clipboard, as it was written. |
[keybindings.documents]#
The documents view, which lists every document agents have written, and the document types.
[keybindings.document_menu]#
The menu on the hovered document, over the documents view's own entries.
| Key | Default | Description |
|---|---|---|
edit | ["e"] | Open the document in your editor, in place of the text drawn beside the list. Quitting the editor, or picking the entry again to close it, saves what it has written. |
rename | ["r"] | Rename the document, typing over its name in the list. |
new | ["c"] | Write a new document for the agent whose documents are listed, from a form. The entry is only on the documents view opened from an agent. |
delete | ["d"] | Delete the document and every earlier version of it, once you confirm. |
[keybindings.document_types_menu]#
The menu on the document type under the cursor of the documents view.
[keybindings.filter]#
The filter over whichever list is on screen, shared by every screen that draws one. The key that opens it is "/" and is not configured.
| Key | Default | Description |
|---|---|---|
next_match | ["n"] | Move the cursor to the next row matching the search, wrapping at the end of the list. |
prev_match | ["N"] | Move the cursor to the previous row matching the search. |
[keybindings.help]#
The key that draws the legend under a list, shared by every screen for the same reason navigation is.
| Key | Default | Description |
|---|---|---|
toggle | ["?"] | Toggle for the keybindings |
[keybindings.git]#
The git menu, nested under the menu on the hovered row, and the actions inside it.
| Key | Default | Description |
|---|---|---|
forge | ["f"] | Open the forge menu to the right of this one, for acting on the hovered task's pull request. |
push | ["p"] | Send the hovered task's branch to origin, which asks first and says how many commits go up, whether origin's copy is overwritten after a rebase, and what stays uncommitted. |
abort | ["x"] | Undo the rebase, am, merge, cherry-pick or revert part-way through the hovered task's worktree, which asks first. The entry names the kind and is off when nothing is in progress. |
rebase | ["r"] | Bring the hovered task's worktree up to date on the latest base, which asks first and says what it would do to the branch and to the files. |
rebase_onto_base | ["R"] | Re-target the hovered child onto the workflow's base branch, rebasing only its own commits, which asks first. The entry is off for a task without a parent. |
pick_fork_point | ["s"] | Pick the fork point of the hovered child, the commit its own commits sit on, once a rewrite of its branch has orphaned it. |
[keybindings.forge]#
The forge menu, nested under the git menu, which acts on the hovered task's pull request.
| Key | Default | Description |
|---|---|---|
open_pull_request | ["o"] | Open the hovered task's current pull request in your browser: the newest one opened from its branch that is not finished, else the newest finished one. The entry says so rather than acting on a task with none. |
copy_pull_request_url | ["y"] | Copy the address of the hovered task's current pull request to your clipboard. |
edit | ["e"] | Change the title and description of the hovered task's pull request, in a form that opens on what the forge holds now. |
toggle_draft | ["d"] | Mark the hovered task's pull request a draft, or ready for review when it is one. |
request_rereview | ["v"] | Ask past reviewers of the hovered task's pull request, picked from a list, to review it again. |
approve | ["A"] | Approve the hovered task's pull request as komrad's credential, or withdraw that approval when it stands. The entry is off when the forge would not take an approval, as from the author. |
merge | ["m"] | Merge the pull request and leave the task where it is. |
merge_archive | ["a"] | Merge the pull request, then archive the task once the forge has merged it. |
merge_delete | ["D"] | Merge the pull request, then archive and delete the task once the forge has merged it, taking what you checked in the merge form. |
auto_merge | ["u"] | Have the forge merge the pull request on its own once its checks and reviews pass, or stop it when it is already waiting to. |
merge_rebase | ["r"] | Merge the pull request on the forge, then bring the task's worktree up to date on the base, which now holds its work. |
[keybindings.format_menu]#
The format menu, nested under the menu on the logs screen.
[keybindings.jump_list]#
The jump list, shared by every screen that keeps one of the places its reader jumped from.
| Key | Default | Description |
|---|---|---|
back | ["ctrl+o"] | Go back to where you were before the last jump, the way Vim's ctrl+o walks its jump list. |
forward | ["ctrl+i"] | Go forward again through the places the jump list walked back from, the way Vim's ctrl+i does. A terminal tells ctrl+i from tab only when it sends extended keys. |
[keybindings.jump_menu]#
The jump menu, nested under the menu on a task, a document or a worktree.
| Key | Default | Description |
|---|---|---|
agent | ["a"] | Land on the agent, on the agents list or in the archive. |
task | ["t"] | Land on the task, on the agents list or in the archive. |
worktree | ["w"] | Land on the agent's worktree on the system view's storage list. |
documents | ["d"] | Open the documents of the agent the jump menu was opened on. |
[keybindings.lsp]#
The language servers over a diff's code, shared by every screen that asks them about it.
| Key | Default | Description |
|---|---|---|
hover | ["K"] | Ask the language server over the worktree what the code under the cursor is, and show its answer beside the cursor. |
[keybindings.messages]#
The messages komrad pushed, read in the main pane.
| Key | Default | Description |
|---|---|---|
open | ["ctrl+g"] | Open every message in the main pane, and close it again. |
dismiss | ["d"] | Dismiss the message under the cursor. |
dismiss_all | ["D"] | Dismiss every message. |
[keybindings.nav]#
Navigation, shared by every menu so movement is the same everywhere.
| Key | Default | Description |
|---|---|---|
bottom | ["G"] | Jump to the last row. |
down | ["j"] | Move the cursor down. |
page_down | ["ctrl+d"] | Move the cursor down a chunk of rows, stopping on the last one. |
page_up | ["ctrl+u"] | Move the cursor up a chunk of rows, stopping on the first one. |
top | ["g"] | Jump to the first row, pressed twice the way vim's gg is. |
up | ["k"] | Move the cursor up. |
[keybindings.quickfix]#
The quickfix list under a diff, shared by every screen that draws one.
| Key | Default | Description |
|---|---|---|
toggle | ["Q"] | Open the quickfix list and move into it. Inside the list, close it. |
[keybindings.review]#
The review screen, which draws a task's diff in the stage and its pull request, comments, files and guide in the sidebar's tabs.
| Key | Default | Description |
|---|---|---|
request_guide | ["u"] | On the guide tab of a task with no guide, ask the writer to write one. From the menu on a guide, ask the writer to bring it up to date. |
[keybindings.review_comments]#
The keys on a review thread, in the comments tab or on a line from the diff's menu.
| Key | Default | Description |
|---|---|---|
accept | ["A"] | On a thread in the comments tab, pass its held comment from the forge on to the writer, copied as your own words and released at once. A comment is held when its author cannot push to the repository, and the writer reads nothing in its thread until the comment opening it is accepted. |
answer | ["a"] | On a thread in the comments tab, show only the change that answered it, from the work as it stood just before the writer's addressed reply to the work that reply carried, with only that thread drawn. The menu's back entry returns to the diff or the comments where you left them. |
compose | ["c"] | On a thread in the comments tab, reply in it. From the diff's menu, open a thread on a line that has none, or the menu of the thread on a line that has one. |
forge_compose | ["C"] | On a forge thread in the comments tab, reply in it on the forge. |
jump | ["o"] | On a thread in the comments tab, show its original location in the diff it was written against, with the cursor on it and only that thread drawn. The menu's back entry returns to the diff or the comments where you left them. |
open_on_forge | ["b"] | On a forge thread in the comments tab, open its first comment on the forge in your browser. |
resolve | ["r"] | On a thread in the comments tab, resolve it without deleting it, or reopen it once resolved. On a forge thread it resolves or reopens the thread on the forge. |
[keybindings.review_files]#
The keys on a file in the review's file tree.
| Key | Default | Description |
|---|---|---|
toggle_viewed | ["space"] | From the menu, fold away the file the cursor is in once you have read it, or open it again. A file the writer writes to afterwards comes back on its own. |
[keybindings.review_folders]#
The keys on a folder in the review's file tree.
| Key | Default | Description |
|---|---|---|
toggle_folder | ["o"] | On the file tree, open the folder the cursor rests on, or close it when it is open. On the pull request tab, open the review of the stacked task under the cursor, or fold the pull request while the cursor is on it. |
toggle_viewed | ["space"] | From the menu, fold away every file under the folder the cursor rests on, or open them all again once every one of them is viewed. |
[keybindings.column]#
The keys the mouse wheel presses over the panel, shared by every screen.
| Key | Default | Description |
|---|---|---|
scroll_down | ["ctrl+n"] | Scroll down. |
scroll_up | ["ctrl+p"] | Scroll up. |
[keybindings.schedules]#
The schedules screen.
| Key | Default | Description |
|---|---|---|
rename | ["r"] | Rename the schedule under the cursor, typed over its row. |
[keybindings.schedule_menu]#
The menu on the hovered schedule.
[keybindings.status_check_logs]#
The logs of the status checks, read beside the list of their checks and steps.
| Key | Default | Description |
|---|---|---|
toggle_group | ["o"] | On the log, open the group of lines the cursor is in, or close it when it is open. |
[keybindings.system_menu]#
The system menu, nested under the menu on an agent or a task in the agents list or the archive.
[keybindings.selection]#
Choosing several rows at once, shared by every list that takes a selection.
[keybindings.menu]#
The menu on the hovered row, which lists the screens that belong to it and the menus nested under it.
| Key | Default | Description |
|---|---|---|
open | ["space"] | Opens the menu, which shows the hovered row's entries, or the chosen tasks', over the screen's own. The key opens nothing on a screen with neither. |
review | ["r"] | Open the review of the task's diff. The entry is gray on a task without a worktree, and in the archive. |
logs | ["l"] | Open the logs of the hovered agent, or of the hovered task and its agents. On the review it opens the task's logs on the hovered language server, or the logs of the hovered status check on the pull request tab. |
documents | ["D"] | Open the documents of the hovered agent, or of the hovered task and its agents. |
back | ["q"] | Leave the review, documents or logs for the row they were opened from. |
status_checks | ["x"] | Open the status checks run on the task's pull request. |
terminal | ["t"] | Open a shell in the pane below the stage, rooted at the hovered task's or workflow's directory, or hand the keyboard to the one already rooted there. The entry is gray in the archive and where there is no directory. |
git | ["g"] | Open the git menu to the right of this one, for rebasing or pushing the task's branch, with its pull request in the forge menu nested inside. |
jump | ["J"] | Open the jump menu to the right of this one, for landing on the hovered row's agent or task, its worktree or its documents. |
system | ["s"] | Open the system menu to the right of this one, for landing on the hovered agent, or the hovered task's writer, on the memory, storage or tokens of the system view. The entry is on a row of the agents list or the archive. |
archive | ["a"] | Open the archive menu to the right of this one, for archiving or deleting the hovered task or every chosen task, for archiving the hovered agent, workflow or schedule, for restoring or deleting a row of the archive, or for deleting worktrees. |
retry | ["R"] | Retry the launch of an agent that failed to create, opening a form where the flags can be corrected before confirming. The entry is only on such an agent. |
edit_row | ["E"] | Edit the hovered workflow, or the hovered task's title, goal and notes. |
notes | ["n"] | Swap the pane beside the list between the hovered task's goal and notes and its writer's pane. Escape puts the writer's pane back too. The entry is only on a task. |
restart | ["o"] | Restart the hovered task's writer, or the hovered workflow's orchestrator, on a new conversation, from a form asking for a note to it. The entry does nothing on a task with no live writer. On the review it restarts the hovered language server. |
dormant | ["z"] | Make the hovered agent, the hovered task's writer or the hovered workflow's orchestrator dormant, closing its pane and keeping its conversation, or resume it when it is not running. The entry is left off archived agents. |
adopt | ["A"] | Put an agent on a branch that already exists, in the hovered workflow. |
new_agent | ["c"] | Start a new task on the hovered workflow. On the hovered task it starts a reviewer of its writer, or a writer in the task's checkout when it has none, and it is not offered once the worktree was removed. The entry is only on the agents list. |
new_workflow | ["w"] | Create a workflow. The entry is only on a workflow in the agents list. |
restore | ["u"] | Restore the hovered workflow on the deleted list with its archived agents. The agents on a task whose worktree was deleted stay archived. |
delete | ["d"] | Delete the hovered row of the deleted list, or every chosen row, once you confirm. |
format | ["f"] | Open the format menu to the right of this one, for switching the server log between raw and compact lines. The entry is only on the logs screen. |
view | ["v"] | Open the view menu to the right of this one, for reading the diff again, wrapping its lines, and checking which of the diff, the sidebar and the writer's pane are shown. The entry is only on the review. |
[keybindings.view_menu]#
The view menu, nested under the menu on the review, which reads the diff again, wraps its lines, and checks what stands beside it.
[keybindings.review_forge_menu]#
The forge menu, nested under the menu on the review, which acts on the line under the cursor on the pull request, pushes the task's branch and holds the pull request's own entries.
| Key | Default | Description |
|---|---|---|
open | ["f"] | Open the forge menu to the right of the menu on the review, for commenting on the line under the cursor on the pull request or copying its link, pushing the task's branch, and acting on its pull request. |
comment | ["c"] | Write a new comment on the line under the cursor, posted on the pull request where anyone can read it. |
copy_line_url | ["l"] | Copy the forge's address of the line under the cursor to your clipboard, pinned to the pull request's head commit, or its base commit for a deleted line. A line the forge's copy differs on has no address until the change is pushed. |
[keybindings.tabs]#
The row of tabs a screen draws over its list, and the key that hands it the cursor.
| Key | Default | Description |
|---|---|---|
focus | ["f"] | Hand the keys to the row of tabs over the list; escape hands them back. On the review's comments tab, hand the keys to its authors row instead, where enter hides or shows the author's threads. |
[keybindings.kinds]#
The row of kinds a screen listing more than one kind of resource draws over its tabs.
| Key | Default | Description |
|---|---|---|
focus | ["F"] | Hand the keys to the row of kinds, where tab and shift+tab switch the kind listed; escape hands them back. On the review's comments tab, hand the keys to its filter row instead, and on the diff, step that row while it is drawn. |
[keybindings.pages]#
The row of pages a screen listing one kind on more than one page draws under its kinds.
| Key | Default | Description |
|---|---|---|
focus | ["P"] | Hand the keys to the row of pages, where tab and shift+tab switch the page listed; escape hands them back. |
[keybindings.views]#
The switcher at the top of the panel, which moves between the agents, schedules, documents and system views from any of them.
[keybindings.workflows]#
The bindings that create and change workflows, from the agents list.
| Key | Default | Description |
|---|---|---|
rename | ["r"] | Rename the workflow under the cursor. |
[diff]#
Sets how the panel draws a diff.
| Key | Default | Description |
|---|---|---|
wrap | true | Wrap a line wider than the pane onto the lines under it rather than cutting it off. The wrap key turns this off and on while reading. |
theme | "terminal" | The theme code in a diff is coloured in, either the name of one komrad bundles, such as kanagawa or terminal, or the path to a theme file. A theme file gives each tree-sitter capture, such as keyword or variable.member, a table of fg, bg, bold and italic. |
[glyphs]#
The icons the panel draws, grouped by where each one is drawn. Every icon is one character from the approved set, the Nerd Fonts octicons and a few named characters. The chrome the layout is drawn with, such as the status bars, dividers and rules, is fixed and not configured here.
| Key | Default | Description |
|---|---|---|
loader | "braille" | The spinner drawn while something is loading, one of braille, arcs or ascii. |
[glyphs.row]#
The repo column of the sidebar, which says where an agent's own checkout stands.
| Key | Default | Description |
|---|---|---|
worktree | "" | An agent with a checkout of its own, drawn in a warning colour while a rebase is stopped in it, and a worktree on the storage list that holds work its base lacks. |
worktree_gone | "" | An agent whose checkout no longer exists. |
[glyphs.pull_request]#
The forge column of the sidebar, which says where the pull request from an agent's branch stands.
| Key | Default | Description |
|---|---|---|
open | "" | An open pull request, and an approved one that cannot merge yet. |
changes_requested | "" | A pull request a reviewer has asked for changes on. |
draft | "" | A draft pull request. |
approved | "" | A pull request the forge would merge now. |
merged | "" | A merged pull request. |
closed | "" | A pull request closed without merging. |
failing | "" | A pull request with a failing check. |
conflicting | "" | A pull request that no longer merges cleanly. |
[glyphs.marks]#
The marks drawn after a row's name in the sidebar and beside what they say in the details.
| Key | Default | Description |
|---|---|---|
failed_script | "" | A script komrad fired for the agent failed and its log is unread. |
mail | "" | Mail is waiting that the agent has not read. |
schedule | "" | A schedule launches into the workflow, and the title over the schedules list. |
document | "" | The agent has written documents for a person. |
guide | "" | An agent has written a guide to the task's change. |
auto_merge | "" | The forge will merge the pull request on its own once its checks and reviews pass. |
reviewer_comments | "" | Beside the count of comments reviewer agents left on the agent's work. |
person_comments | "" | Beside the count of comments you left on the agent's work. |
forge_comments | "" | Beside the count of comments copied from the forge onto the agent's work. |
reviewer | "" | Before the name of a reviewer agent under its task. |
[glyphs.lists]#
The titles over the panel's lists, and the prompt and cursor they draw.
[glyphs.review]#
The marks on the review screen's threads and files, and on how far a comment has got.
| Key | Default | Description |
|---|---|---|
unread | "●" | A thread holding something you have not read. |
read | "○" | A thread nobody has resolved, with nothing new in it. |
settled | "✓" | A thread that has been resolved. |
unsent | "◇" | A thread holding a comment nobody has sent yet. |
forge | "◆" | A thread mirrored from the pull request on the forge. |
current | "▸" | The row of the file tree beside the diff that the cursor is in. |
folder_open | "" | A folder of the file tree beside the diff that shows the files inside it. |
folder_closed | "" | A folder of the file tree beside the diff that hides the files inside it. |
delivered | "✓" | A comment the agent has been given. |
[glyphs.messages]#
The messages the panel shows, one for each kind.
[glyphs.schedules]#
The schedules list, one for a schedule that runs and one for a schedule that is paused.
[glyphs.status_checks]#
The status checks list and their logs, one for a check that passed, one for a check that failed, one for a check that was skipped, one for a check komrad stopped reading before it finished, and one each for an open and a closed group of log lines.
| Key | Default | Description |
|---|---|---|
passing | "" | A check that passed. |
failing | "" | A check that ended any other way. |
skipped | "" | A check that was skipped or ended neutral. |
unknown | "" | A check komrad stopped reading before it finished, so its result is not known. |
group_open | "" | A group of lines in a check's log that shows the lines inside it. |
group_closed | "" | A group of lines in a check's log that hides the lines inside it. |
[palette]#
The colours the panel draws in, one for each part a colour plays. Each is a terminal colour number from 0 to 255, which your terminal's theme decides the look of, or a hex code like "#1e3a5f".
| Key | Default | Description |
|---|---|---|
primary | "4" | Focus, titles and whatever holds the keys. |
secondary | "6" | A second accent for what is set apart from the primary chrome, such as diff hunk headers and inline code. |
muted | "8" | Text that matters less than what is around it. |
success | "10" | Something finished or approved. |
warning | "11" | Something that needs your attention. |
danger | "9" | Something failed or is gone. |
user_me | "12" | The colour of text you wrote. |
user_agent | "13" | The colour of text an agent wrote. |
user_reviewer | "14" | The colour of text a reviewer agent wrote. |
user_github | "3" | The colour of text that came from GitHub. |
merged | "5" | A merged pull request. |
highlight | "208" | The colour of text picked out for you to act on, such as a search match. |
inverse | "0" | Text drawn on a filled bar. |
[palette.diff_added]#
The background of a line a diff adds.
[palette.diff_deleted]#
The background of a line a diff deletes.
[palette.diff_added_word]#
The background of the words a changed line added.
[palette.diff_deleted_word]#
The background of the words a changed line deleted.
[palette.selection]#
The background of the row under the cursor or taken into a selection.
[palette.selection_dim]#
The background of the cursor's row while the keys are elsewhere.
[palette.match]#
The background of a search match in a diff.
[palette.mode]#
The colour of each mode the panel is in, drawn as the label at the foot of the sidebar.
[hooks]#
Sets where komrad finds the scripts a workflow hangs on a moment in its agents' lives, and how long each may run.
| Key | Default | Description |
|---|---|---|
dir | "" | The directory for hooks, which holds one executable file per hook, named after the hook. A hook is a script or program komrad runs at a moment a workflow names it against, in the agent's own directory, with agent info in KOMRAD_AGENT as JSON and the moment in KOMRAD_TRIGGER. Default is ~/.config/komrad/hooks. |
timeout | "1m" | The longest a hook may run before komrad stops it and counts it as failed, as a Go duration such as "30s" or "5m". A hook's own #KOMRAD timeout can ask for less, never more, and a hook that asks for "none" gets this. A duration komrad cannot read, or one that is not positive, is refused. |
[language_servers]#
Sets where komrad finds the language servers a review asks about code.
| Key | Default | Description |
|---|---|---|
dir | "" | The directory for language servers, which holds one TOML file per language server, named after it, such as gopls.toml. komrad runs only the language servers with a file here, and reads the directory again each time a review asks about code. A file for a language server with a default config sets only the fields it changes, and a file for any other needs cmd, filetypes and root_markers. Default is ~/.config/komrad/language-servers. |
[worktrees]#
Sets where a workflow's generated worktree provisioner creates its worktrees.
| Key | Default | Description |
|---|---|---|
dir | "" | Directory that holds generated worktrees, one subdirectory per agent. Left empty this is ~/.local/state/komrad/worktrees. |
[git]#
Controls how komrad reads the git checkouts its agents work in.
| Key | Default | Description |
|---|---|---|
ssh_hosts | [] | SSH hosts that stand in for a forge's web host, each written as "ssh_host=web_host", such as "ssh.gitlab.example.com=gitlab.example.com". A remote on the SSH host is then matched to the forge connected for the web host. Write host names only, without a port, scheme or user. Public aliases such as ssh.github.com and altssh.gitlab.com are already known. |
[forge]#
Controls how komrad reads the review threads on the pull requests its agents open.
| Key | Default | Description |
|---|---|---|
bot_names | [] | Logins whose review comments are left out of the threads mirrored onto an agent, such as a CI bot or a code review App. A thread whose every comment is from one of them is not mirrored at all. Names ignore case. |
max_check_log_bytes | 2097152 | The largest check log komrad keeps, in bytes. Komrad drops a log past it, and the panel links to it on the forge instead. Komrad refuses a negative size. The default is more than three times the largest log sampled across real repositories. |
[github_app]#
The GitHub App an engine fetches and pushes as.
| Key | Default | Description |
|---|---|---|
app_id | "" | The App's own id, from its settings page. Left empty the engine has no GitHub identity and git is left to whatever credentials the account already has, which on a machine nobody logs into is none. |
installation_id | "" | The installation the token is for, which scopes it to the repositories the App was installed on rather than to everything it could reach. GitHub writes it as a number, and it appears in the URL of the installation's own settings page. |
private_key_path | "" | The PEM the App was created with. On a deployed engine, komrad fetches this into a tmpfs at boot rather than writing it to disk, so the key does not outlive the machine. |
[context]#
The standing text every agent is started with, whatever workflow it is in.
| Key | Default | Description |
|---|---|---|
file | "" | The file holding global context, read at each launch. Left empty this is ~/.config/komrad/context.md, but will not trigger a failure if left blank. |
[mail]#
Controls how komrad delivers mail between agents.
| Key | Default | Description |
|---|---|---|
delivery_deadline | "3h" | The time mail stays deliverable, as a Go duration such as "3h" or "45m". Komrad neither delivers nor shows mail past it, and keeps the row as a record that it never arrived. A duration komrad cannot read, or one that is not positive, is refused. The default is long enough that an agent left alone over lunch still gets its mail. |
max_exchange | 40 | The amount of mail two agents may write each other before komrad refuses a send between them. It counts the pair in both directions over every thread, so opening a new subject is not a way around it. When a send is refused komrad marks a row for attention and tells the recipient its mail was stopped, so an exchange that is cut off does not leave the other side waiting on a reply that will never arrive. A negative limit is refused. The default is more than twice the longest exchange the panel has recorded finishing. |
quiet_task_after | "15m" | How long every agent on a task can stay quiet before komrad mails the agent that created the task's writer, as a Go duration such as "15m". Komrad mails once per quiet stretch, and never for a task that is parked or waiting on komrad. "0" turns the check off. |
[performance]#
How much of the machine komrad may take, and what it frees to stay inside it.
[performance.memory]#
When komrad archives merged tasks and makes idle agents dormant.
| Key | Default | Description |
|---|---|---|
limit | "0" | The most memory komrad and its agents may hold for longer than five seconds, as a size such as "12GiB". Past it, komrad makes agents dormant, those holding more than their share first, then idle ones, and it does so at once past the limit plus a typical resting agent's footprint. "0" sets no limit. |
merged_task_max_age | "24h" | The longest a task stays live once its last pull request merged and its agents stopped working, as a Go duration such as "24h". "0" turns this off. |
idle_agent_max_age | "2h" | The longest an agent sits idle before komrad makes it dormant, as a Go duration such as "2h". Mail resumes it, and an agent quiet this long comes off the resume list. "0" turns this off. |
[performance.storage]#
How much disk space komrad may take, and when komrad shrinks or deletes the worktrees of archived tasks.
| Key | Default | Description |
|---|---|---|
limit | "100GiB" | The most disk space komrad's state, cache and worktrees may take, as a size such as "100GiB". Past it, komrad shrinks the worktrees of archived tasks, then deletes them, keeping their records. "0" sets no limit. |
archived_worktree_max_age | "72h" | The longest a task stays archived before komrad deletes its worktree, keeping its records, as a Go duration such as "72h". "0" turns this off. |
archived_worktree_min_age | "1h" | The shortest a task stays archived before komrad may shrink or delete its worktree to get under its limit. |
disk_space_check_interval | "10m" | How often komrad measures its disk space. |
[performance.turn_retries]#
How komrad retries turns ended by failures outside the agent's work.
[secrets]#
Controls how komrad finds the keys it keeps out of its database.
| Key | Default | Description |
|---|---|---|
skipped_rules | ["generic-api-key"] | The gitleaks rules komrad skips when it looks for keys, by rule id. Komrad refuses an id gitleaks does not have. The default skips generic-api-key, which matches far more page tokens and ids than keys. |
[log]#
The logs the server and the panel write, and how much of them komrad keeps.
| Key | Default | Description |
|---|---|---|
level | "info" | The amount komrad writes, one of debug, info, warn, or error. At info, failures are written at error and everything else at debug, so the file stays empty while the server works. |
max_size_mb | 64 | The size in megabytes a log file grows to before komrad starts a new one. A number at or below zero takes the default. |
max_files | 4 | How many old log files komrad keeps beside each current one, deleting the oldest past it. A number at or below zero takes the default. |
[log.export]#
Sends every line komrad writes to an OpenTelemetry collector as well as to its files.
| Key | Default | Description |
|---|---|---|
endpoint | "" | The collector's URL, such as http://localhost:4318. Komrad adds /v1/logs when the URL names no path, and sends to the URL as written when it does. Left empty, komrad sends nothing. |
headers | {} | Headers sent with every export, such as a backend's API key. A value can read an environment variable as ${NAME}. |
[debug]#
Puts komrad into debug mode which records additional information used to help diagnose issues.
| Key | Default | Description |
|---|---|---|
frames | false | Keeps the pane capture behind each reading of an agent under the cache directory when on. |
frame_history | 500 | The number of frames komrad keeps for one agent before it drops the oldest. A number at or below zero takes the default. The default keeps about 15 minutes of frames, enough to replicate most issues with reading an agent. |
[debug.pprof]#
Go's pprof profiler, served by the server and the panel.
[debug.pprof.server]#
The server, which runs the agents and answers the API.
[debug.pprof.panel]#
The panel, which draws the screen and talks to the server.
[sign_in]#
The identity provider people sign in to this engine with, and the listener their requests reach it on.
| Key | Default | Description |
|---|---|---|
issuer | "" | The provider's issuer, like https://accounts.google.com, which every ID token it signs names. Left empty, along with client_id, the engine doesn't take signed-in requests. |
client_id | "" | The id the owner registered komrad under at the provider, which every ID token for komrad names as its audience. |
client_secret | "" | The secret some providers, such as Google, hand a desktop app beside its id. Every copy of komrad carries it, so it protects nothing, and 'komrad login' reads it from the engine. |
addr | "127.0.0.1:8788" | The address the public listener serves signed-in requests on. It has to be a loopback host, since a web server on the same machine carries the network's requests to it. |
[connection]#
Which komrad this is, by its database, its address, its tmux socket and its cache.
| Key | Default | Description |
|---|---|---|
database_url | "" | The Postgres komrad keeps every agent, workflow, schedule and transcript in, reached as this engine's own login, which is what keeps its rows apart from every other engine's. 'komrad engine ensure' creates the login and prints this url. Left empty this is the default engine's login on the embedded Postgres under state_dir. Whenever this reaches the socket under state_dir, the server runs the embedded Postgres and starts it again when it exits. It can read its password from an environment variable written as ${NAME}, as in postgres://komrad:${KOMRAD_DB_PASSWORD}@db.internal:5432/komrad. |
owner_database_url | "" | The login that owns the schema, used only by 'komrad migrate' and the 'komrad engine' commands. Left empty this is database_url, or the embedded Postgres's owner while database_url reaches it. It can read its password from an environment variable written as ${NAME}. |
readonly_database_url | "" | The least-privilege login the MCP query tools connect as. Left empty this is database_url with the engine's reader login, which is its own login with _reader on the end and the same password. It can read its password from an environment variable written as ${NAME}. |
addr | "127.0.0.1:8787" | The address the server listens on, which the panel, the CLI and the MCP endpoint all reach it at. Change it to run two komrads on one machine. It has to be a loopback host, since the api has no auth and its writes spawn agents. |
tmux_socket | "komrad" | The tmux socket komrad runs its own server on. Nothing in your normal tmux sees that server, which is why 'tmux -L komrad ls' is how you look at it directly. |
cache_dir | "" | The directory where komrad keeps what it generates, such as the server log, the built-in scripts it writes out on every start, and the temp files a harness passes a prompt through. Left empty this is ~/Library/Caches/komrad on a Mac and ~/.cache/komrad on Linux. Everything under it is komrad's to delete and rewrite, so nothing of yours belongs here. |
state_dir | "" | The directory where komrad keeps its own files about agents, such as generated worktrees, released reviews and forge credentials. Left empty this is ~/.local/state/komrad. It holds credentials and is komrad's to manage, so nothing of yours belongs here. |
url | "" | The https address the engine is served on, like https://komrad.example.com. Left empty the engine is local and an agent's terminal is shown by moving its own pane into the panel. It may be plain http when its host is this machine. |