Slash commands
Commands available from the GPU chat composer.
Full notes from the app
Type / to see the autocomplete menu, including /commands and /parent. Built-in names and aliases come from the same registrations used for dispatch. Typing an alias such as /settings or /thinking finds its primary command without duplicating the bare-slash list. Built-in names and aliases take precedence over skills, Markdown commands and plugins. Tab completes without running; Enter submits a fully typed name or alias on the first press. Every submitted slash command leaves an entry in the current chat view, followed by local feedback, dispatch status, or its result. Short replies and errors stay in scrollback instead of disappearing as toasts. Opening a picker is reported as opening it, not as completing its action. Commands that run a prompt or skill save their invocation as a receipt beside the expanded user input; other command entries never start or stop a model turn. These display-only receipts survive transcript reloads but are never added to model context. Private /note text is omitted from its receipt.
67 entries · kcode 0.6.5097
| Command | Arguments | What it does |
|---|---|---|
| Other commands | ||
| ! | <shell command> | Run a shell command directly, without an agent turn. Uses the same session shell cwd and exported environment as the agent's bash tool. One user command can run at a time; chat stays available. A shell card shows live combined stdout/stderr, elapsed time, and exit status. Enter/Send sends hidden stdin, EOF ends input, and Stop cancels the script and its child process groups. Esc from shell controls returns to chat; Ctrl-C there stops the shell rather than quitting. Input is not saved in chat, though programs can print what they receive. Pending images stay attached to the composer. Output is a bounded tail; Copy output copies what is shown. A completed run leaves a display-only receipt; the latest run is replayed on reconnect, but shell scrollback is not durable. Closing the session stops its shell command. Full-screen terminal applications are not supported. See /jobs |
| /doctor | [global] | Run advisory local health checks for the current open session, or app-wide checks with /doctor global. The app context menu and command palette offer Health check… for global checks; a live session's context menu checks that session. Reports stay outside the agent transcript. Restored stopped sessions wait until live for their automatic check; explicit checks explain how to resume or use app-wide checks. A failed collection shows recovery guidance, not finding counts or empty report filters. Recheck is explicit; no network probes or automatic repairs. A missing model provider alone raises no report, since the empty grid and every composer already say a provider is needed; an opened report still lists it. Details opens a report, and Hide details or Escape takes it back to its one-line summary. Each check line names the file, setting, agent or server it looked at, as in "~/.kcode/config.toml: The file isn't there. It is optional.", and identical lines show once with their count (×3); an agent or model choice left to its caller passes, as an unset setting does. A report is a snapshot: adding, changing or removing a plugin does not rerun it, so its header says when it was checked (checked 8:15 PM), press Recheck for a current one. The details list scrolls, with a scrollbar when it holds more than fits. A command, skill or plugin output style whose file can't be read or parsed is named (content.load), as an agent (agent.load) and a theme (theme.load) are, and so is a folder of theirs that is no folder, can't be opened or holds a broken link, and a folder in command_dirs or skill_dirs that isn't there, and so is an agent whose permission_mode is ignored (agent.permission-mode). A trusted project that declares hooks while hooks_enabled is off gets a review finding (hook.off) naming the Project hooks switch. A startup check names the component and the setting behind it, as in "Config timers (eventsource_timer.crons): It isn't in use." Dismiss hides the report for this launch; Ignore persists until relevant evidence changes. The panel omits build hashes and internal diagnostic identifiers; Copy retains support metadata and local paths but no credentials.See /debug |
| /reload | client|daemon | Restart half the app on a rebuilt binary without losing sessions. /reload daemon has the daemon hand its live sessions to a freshly spawned successor (a takeover file next to the socket; the successor retries the singleton flock and rehydrates each session from its durable transcript) and exit: the client rides its reconnect supervisor, tiles mute briefly, and an open turn ends interrupted (the panel settles it and says so) and its open permission prompt or question closes, since the turn that showed it is gone, and the turn's wait, activity line and subagent rows clear (the prompt stayed and its answer reached nothing, and the next turn's working strip showed the old wait or activity line). /reload client spawns a successor of the app process and quits; the daemon's idle grace covers the gap and the fresh client's first Hello rebuilds every tile from daemon-side workspace state, and a permission prompt or question still waiting shows again, as do a running turn's activity line and the session's subagent rows. Bare /reload prints usage.See /quit /exit |
| /autocompact | [<n>|off|reset] | Set an absolute context-token budget for this session. The automatic compaction trigger is the smaller of this budget and compaction.auto_compact_threshold (85%) of the effective input budget, checked at every step of a turn and at the end of it. When the live context reaches the trigger, kcode compacts in the session's configured mode; after a pass the trigger re-arms only once the context has grown a tenth of the trigger past what the pass left, so two passes never run back to back on one model; a switch to a model with a smaller trigger drops that wait. <n> is 50000, or a 50k/1.5m suffix. Defaults to the configured compaction.auto_compact_tokens (300,000 tokens: on by default so a 1M-window model's distant percentage trigger isn't the only one). No-args names the budget in force and where it comes from: this session's own, or the configured one; off (or none/0) turns the budget off for this session, the configured one too, so only the percentage trigger applies; reset (or clear/default) drops the session's own and returns to the configured budget. Every form is answered in the chat. Persisted per session like /model and /effort, so it survives --resume and a daemon restart. GPU build only. Aliases: /auto-compact, /auto_compact.See /compact |
| /promote | [name] [location] | Promote a scratch session to a real project. A scratch session is one started with no folder (⌘N → Enter on the picker's scratch row, or SpawnSession { scratch: true }): the daemon roots it at a fresh temp dir ($TMPDIR/kcode-scratch-<id>/), which macOS clears of files left untouched for three days, and its tile shows the label scratch. Deleting a scratch session removes its folder once no session is left in it, unless the folder holds anything besides kcode's own project database (a file, a /share export) which stays. /promote turns it into a project: bare /promote opens a one-line editor taking name [location] (a bare name lands under ~/code; otherwise the rest of the line after the name is the location, spaces included, and ~ or a relative location reads from the home folder; the name is one folder name, so a name with a /, or . or .., is refused), /promote <name> [location] skips the editor. The daemon moves the scratch folder to <location>/<name>/, which must be missing or empty, whole or not at all: on one disk in one step, and to another disk by copying it first (links stay links and are never followed, a socket or device stops it) and removing the scratch folder only once the copy is complete, so a move that fails leaves the scratch folder as it was. It then points every session in the scratch folder at its new place: the session, its forks, a session opened in a subfolder and a worktree session made off it, at its moved checkout, and points git's links between the repository and its worktree checkouts at their new places, as git worktree repair does; the trust given to the scratch folder, a folder in it or a checkout follows it, and so do the turn records /undo reads, so /undo in the new folder undoes a turn from before the move; it relabels them to name, and copies the session record into <name>/.kcode/sessions/ so a promoted project is self-contained; the reply names a copy that failed. Each of them that was running stops before the move and starts again in the new folder, so its shell, language servers, plugins and project storage follow it; its /loops and timers carry on, while its shell's cd and variables start fresh. Other sessions keep working during the move; one in the scratch folder is refused input, a fork, a new session, a ! command, an /agent run or a /share there until the move ends, and a move that fails starts them again in the scratch folder. Refused with a notice while a turn is running in any session in the scratch folder, or in a folder that holds the destination (promote between turns) and while a ! command, a background shell command, a subagent (an /agent run, a plugin's or the agent's own) or a /share export runs in one of the scratch folder's sessions, naming each: stop them from /jobs or let them finish. The move waits for the folder's semantic index to stop writing into it. Not a scratch session → a notice, no-op.See /fork /rename |
| /parent | Jump to this session's parent, the session that forked it or spawned it as a worktree worker. A fork comes from /fork or fork_session, a worker from spawn_worktree_session. The parent link is the session's persisted origin, read off the registry, so it survives a daemon restart. A live parent is brought onto the grid and opened; a stopped one is resumed and opens once it is running again (the same jump as a notification row click). A root session has no parent and the command says so, and so does a session whose parent was deleted: it names the gone parent and opens nothing. The child also wears an origin badge in the switcher (⑂ fork or ⚙ worker beside its ⎇ branch) so a session that belongs to a root agent is identifiable at a glance. GPU build only.See /fork /worktree | |
| /undo | [list] | Undo the session's last turn. kcode records the project when each turn starts and again when it ends, and a bare /undo reverts only the files that differ between the two: each goes back as the turn found it, permissions included, and a file the turn made is removed. A symlink the turn deleted or re-pointed is made again and one it made is removed: the link, never what it points at. When the project folder is a git checkout's top folder (a worktree or the main checkout) /undo also moves the branch back past the commits the turn made and puts the staging area back as the turn found it, so what the turn committed or staged is undone too; a branch the turn switched to keeps its commits, and HEAD goes back to the branch it was on. A change made while the turn ran counts as the turn's (its shell commands, another session's shell commands and your own edits alike) except a write by another session's file tools. /undo leaves alone, and names in its reply: a file changed again after the turn, a file another session's file tools wrote while the turn ran (a session on a folder inside or above this one included) a path kcode did not record at one end of the turn, a file it could not read, one over snapshot.large_file_threshold_mb, or a file or folder the project's ignore files or snapshot.additional_excludes left out, such as a first build's target folder; a path left out at both ends is not compared, and a file one of those stands in the way of. It leaves git alone, and says so, when the branch or staging area changed after the turn, when git is in the middle of a merge or rebase, or when the turn began in the middle of one. Version-control folders such as .git, kcode's data dir, the notes in the project's .notes/ folder and kcode's own files in a .kcode folder (its database, worktree checkouts, build folders, skill state and /share exports) are never touched; the rest of a .kcode folder, such as its config, rules, commands and agents, is reverted like any other file. While a turn runs in any session of this project folder or of a folder inside or above it, or a merge lands in it, /undo refuses and names what is running. A turn with no end record (kcode stopped mid-turn) cannot be told apart from later changes, so /undo lists every change made since that turn began in a confirmation before reverting them. When kcode cannot record a turn's start, the chat says so as the turn begins; the next /undo stops at that turn and names it, and the one after passes it. A turn kcode can no longer undo: the store has lost a file as the turn found it, or the turn's records can't be read, is named the same way, with why, and the next /undo passes it. Repeated undos walk back turn by turn, passing turns that changed nothing: each reverts this session's newest turn no earlier undo reverted, so the first undo after a new turn undoes that turn, as far back as the turns snapshot.retention_count keeps. The reply lists the files restored and removed, then the paths kept (a kept folder with a trailing /) each list cut after eight lines with a count of the rest, with a short diff of what came back, and names where the branch went back to. list shows the session's ten newest turns, when each ran, its prompt's first line or command, and how many files it changed and whether it moved the branch: marking the undone ones, the ones /undo can't undo with why, and the ones kcode did not record. Any other argument undoes nothing: the reply names what /undo takes. A session in a folder that is not a project: your home folder, a folder above it, /, or the folder that holds kcode's data dir. Keeps no turn records, so /undo there says why there is nothing to undo. There is no /redo: undo means exactly "undo the last turn". |
| /upgrade | Check for a newer kcode now and download it. A newer release is downloaded in the background, checked to be a build of this kcode signed by the same developer, and kept ready; the answer (kcode 0.6.0 is downloaded. Restart kcode to use it., that kcode is up to date, or why the check failed) stays in this chat, and the notification center gets an ↑ Update row. Restarting kcode puts the update in place: the row's Install update, the palette's Restart to update, or quitting kcode and opening it again. An install you can't replace (an app in a folder your user can't write) gets the download page instead. A debug or dev-release build answers that it doesn't update itself. The palette's Check for updates row does the same check, answering in the focused session's chat, or in a toast when no session is focused.See kcode upgrade updater.automatic | |
| /jump | Scroll the transcript to an earlier message in this conversation. Opens a type-to-filter overlay (↑/↓ to move, Enter to jump, Esc to cancel) listing this session's user and assistant messages, not the commands you ran or kcode's own notices; each row shows the author and a one-line preview (a message that opens with a code block previews its first line of code), the timestamp on the right, and choosing one scrolls that message to the top of the view and selects it. A no-op when the conversation has no messages yet. A client-side navigation command intercepted in the GPU panel, never sent to the agent. Also on the command palette as 'Jump to message…'. GPU build only. See /control | |
| /rename | <title> | reset | Set a display title for this session (shown in the switcher, the grid HUD, and leading the chat status bar). reset or clear on its own clears it; a title that starts with either word, such as clear skies, is set as written. A session's title is the project directory unless explicitly set here: there is no auto-generated title. Related: /fork.See /fork |
| /share | [jsonl|markdown|md] | Export this session's canonical history to disk. No-args writes both JSONL + Markdown to <project>/.kcode/sessions/<start date>-<session-id>.{jsonl,md}, the start date as your Mac's calendar reads it: for a worktree session, the base project's, so they outlive its checkout; jsonl or markdown (md) writes one of them to the same file, so a later export replaces the earlier one, and any other word is refused with the formats /share takes. In a git repository git ignores the folder the exports go to, so git add -A never commits a conversation. Alias: /export. Markdown preserves the original conversation, reasoning, rich tool results and images even after compaction; model-only summary and restore bodies are omitted. Long replies remain continuous Markdown in chat and export: internal storage chunks do not split image links or code fences into separate messages. JSONL schema 2 is the typed archive: a session header with a fixed history watermark, followed by history records, including context checkpoints. Exports read bounded pages and replace the destination only after success. The export runs in the background, so other sessions keep working; two exports of one session run in the order requested, and /share is refused while a /promote moves the session's folder. Separately from this on-demand command, every session is also auto-exported to ~/.kcode/exports/<session-id>.jsonl, refreshed at each turn boundary (session_daemon.auto_export). |
| /stats | Open the focused session's stats dashboard as an overlay. It shows a header (model · session title · its badge when it has one, as in /stats all · age · turns · rounds), a KPI strip (cost, tokens in/out, cache read/write, thinking) with a line under it naming the calls the cost leaves out, two sparklines (tokens per turn and context occupancy % per turn), a tool section (runs · ok · failed plus a bar chart of the top tools), a per-model token and cost list, an activity line (compactions, how many times the agent kept going after a round and how many times it ended the turn, memory recalls), and the files the session changed, the latest 12 with how many there are in all (71 files changed · the latest 12 shown): the ones its file tools wrote (fs_write, fs_edit, apply_patch), and in a project every file its turns changed some other way (a shell command, a build, a git checkout) as the turn records /undo uses found them, less what another session's file tools wrote. The cost is what the session's calls cost at the live models.dev prices of the provider each call went to, to four decimal places: $0.0412+ when some calls have no price (the catalog does not price their model), — when none has one, included when a subscription (a ChatGPT sign-in, Kimi For Coding) covered every call; the line under the strip says how many calls have no price or were on a subscription. A call an older build recorded keeps the figure it was recorded with, and reads as priced when that figure is above zero. The daemon folds the durable token and cost spine from the charge ledger (all-time) and merges the live counters it accumulates from the session's turn/control streams (turns, rounds, tools, trends: reset when the session stops), streaming a fresh snapshot on subscribe and at each of that session's turn boundaries while the overlay is open. A client-side command intercepted in the GPU panel, never sent to the agent. Also summoned by Cmd-Shift-S and the command palette's 'Session stats'. ↑/↓ scroll a line, PageUp/PageDown a viewport, Home/End jump to the ends. Dismiss with Escape or by clicking the dimmed backdrop; while the dashboard is open the grid behind it takes no pointer input. With no session focused, Cmd-Shift-S opens the /stats all cross-session dashboard instead; Enter on one of its rows lands here. In the headless (-p) build there is no overlay: /stats prints this session's dashboard summary as a text reply, tokens, what the calls cost, turns, then one line per call with its cost (no price or on a subscription when it has none).See /stats all /cost /control | |
| /stats all | Open the cross-session stats dashboard as an overlay over the grid. One row per session the registry knows, across every project: a liveness dot (working/finished/idle/looping/needs-input/error/stopped, in the same status colours as the tile glow: a looping session wears the working colour, and a session whose turn finished while you were elsewhere wears green until you open it), the session title, then its badge when it has one (a worktree session's branch ⎇ kcode/<name>, ⑂ fork or ⚙ worker: the badge the Cmd-K switcher shows; an untitled worktree session is otherwise titled with its base's project name), its model, and six figures under a captions row. Turns (the live turn count; a stopped session shows a dash), tokens in, tokens out, cost (what the session's calls cost, to the cent: $1.40, $1.40+ when some calls have no price, — when none has one, included when a subscription covered every call), live context %, and when it was last active (a live session's latest event, a stopped session's newest charge). In a narrow window the same information stacks under the session title instead of squeezing it out. Rows sort needs-input → errored → working → finished → idle → stopped, newest activity first within a state, so the session that needs you is at the top. The header sums the totals (sessions · live · in · out · spent), then, on a line of its own, names the calls the cost leaves out (2 calls with no price, 5 calls on a subscription). Keyboard: ↑/↓ move the selection (it follows its session across a refresh), Enter opens the selected session's own /stats dashboard in place, PageUp/PageDown/Home/End scroll. Mouse: a click on a row brings that session forward; a live session gets a tile and opens (maximized, or selected in the Sidebar and Tabbed layouts), a stopped one is resumed (behind the project-trust gate) and opens once it is running again, and closes the dashboard, the same jump a notification row makes. The daemon aggregates every session's charges from the shared user-scope cost ledger, adds each live session's turn count and each session's newest charge time, and streams a fresh snapshot on subscribe and at each turn boundary while the overlay is open; the client joins it to the session registry to render. Also the app menu's and the command palette's 'Stats', and what Cmd-Shift-S opens when no session is focused. Dismiss with Escape or by clicking the dimmed backdrop.See /stats /cost | |
| /browser | Show the session's browser tile in Mission Control: the headed half of kcode's browser. The tile streams the session's headless Chrome-family browser live (screencast frames as textures, with the page URL/title in a chrome row) and is click-through: clicking the page forwards a real mouse click at that point, so you can follow links and press buttons yourself while the agent drives the same browser with its browser_* tools. One browser per session, spawned on first use and ended with the session, or when kcode quits, its throwaway profile deleted; one that exits on its own is started again on next use. Closing the tile never kills the browser, it just closes your viewport (the agent keeps working headless). It runs on a fresh ephemeral profile, whose cookies and storage never outlive the session, unless browser_host.profile names a saved profile, which keeps them across sessions. The agent's navigations to web pages, clicks and fills run without a prompt, so a site you sign in to here is one the agent can act on too. First-class tile: solver layout, miniatures, and attention glow all apply. Requires a Chrome-family browser installed (Chrome, Chromium, Edge, Brave, Arc): otherwise the tile says so. Issue it from the session whose browser you want to watch. It opens the tile right after the session's and puts it in view: a maximized session (or one opened from the grid) splits into the chat and the browser side by side, the keyboard staying in the chat; in the Sidebar and Tabbed layouts the browser's row or tab is selected, and its ✕ closes it. The chat says where the tile went, or, with all 256 of Mission Control's tiles taken, that it opened none. Typed again while the browser is in view, /browser closes the tile; typed while the tile is open but out of view, it shows it again rather than closing it. Cmd-Shift-] / Cmd-Shift-[ reach the browser tile from a maximized session. macOS only for now.See /debug /files | |
| /cost | Show a one-line summary of the current session's cost and tokens. It reads like $0.0412 spent · 1.2M in / 40.0K out across 12 calls: what its calls cost, then the tokens in and out across every call it has made. Each call is priced from the live models.dev catalog at the prices of the provider it went to. Calls the figure leaves out are named, not counted as free: $0.0412 spent · 3 calls with no price · … when the catalog does not price a call's model (cost unknown · … when it prices none of them), and … · 12 calls on a subscription for calls a ChatGPT sign-in or Kimi For Coding covered.See /stats | |
| /effort | [minimal|low|medium|high|xhigh|max|default] | Set the session's reasoning effort. Without an override, kcode uses the current model's highest supported level; switching models recomputes it. An explicit session choice wins over default_effort in config, which wins over that automatic choice. No-args opens a picker of accepted levels plus Use default, whose hint names the resolved level; it opens on the session's current choice, marked ●, so Enter keeps it. Named levels come from the provider's models.dev entry; legacy Anthropic token-budget levels are limited to those that fit the model's output ceiling. Models without a supported control receive no effort parameter. Explicit choices are clamped to the nearest accepted level at or below the request (or the model's minimum). /effort default clears the session override; off, none, and reset remain aliases for clearing, not disabling reasoning. The session override persists across resume; a session without one takes the default effort in force when it comes back. The chat status bar always shows the effort in effect as ⚡ <level> after the model: the session's choice, else the default, else the model's highest level, as the model takes it, and shows none for a model without an effort control.See /model |
| /output-style | [name] | Pick the agent's output style: the tone/format instructions appended to the system prompt. No-args opens a picker over the styles the session's project can use, read when it opens: the built-ins plus any plugin-bundled ones (<plugin>/output-styles/*.md) its policy.toml does not block, each row showing its style's description, and opens on the style new sessions get, which is marked; when the saved name matches no style, the default row is marked and says so. A plugin's style file kcode can't read or parse is left out, and /doctor names it (content.load). An arg sets directly: the name matches in any case, and one that matches no style is refused with the list of styles there are. Persists to default_output_style and relays a live SetDefaultOutputStyle to the daemon, so sessions spawned from then on use it without a restart (the prompt is built once per session; live sessions keep theirs). Alias: /output_style.See #output-styles |
| /cot | [on|off|toggle] | Show or hide the model's reasoning text. When ON, reasoning streams in live as the model thinks and settles into an expanded fold (rendered as faded Markdown, so code and lists inside it stay readable). Codex reasoning-summary parts remain separate paragraphs instead of running together. Live and finished reasoning keep the same indent, rail and wrapping. Click the Thought header to collapse or expand; drag over the body to select and copy text, including while it streams. Collapse any fold and every later fold in the session stays collapsed (a sticky preference). When OFF, only the reasoning text is hidden: the live ✦ Thinking… indicator still shows (and the reply still streams), so a long reasoning phase never reads as a frozen turn. A client-side display toggle that persists per session: restored on --resume, overriding the session_panels.chat.show_thinking config default; a session that never toggles it uses that default. Aliases: /think, /thinking. |
| /think | [on|off|toggle] | Alias for /cot. Toggles reasoning visibility.See /cot |
| /thinking | [on|off|toggle] | Alias for /cot. Toggles reasoning visibility.See /cot |
| /show-tools | [on|off|toggle] | Show or hide tool-call bubbles (name + args + result) in the chat pane. View-only: agent still invokes tools either way. A client-side display toggle, seeded from the session_panels.chat.show_tools config default (not persisted per session: unlike /cot). Default is on. Alias: /show_tools.See /cot /tools |
| /show-control | [on|off|toggle] | Show or hide control-plane status lines as dim rows in the chat panel. They are the injected <cp:*> channel messages, such as the per-turn permission context. Hidden by default. A client-side display toggle: applied locally to the panel, never sent to the agent. GPU build only. Alias: /show_control.See /cot /show-tools #channels |
| /timestamps | [on|off|toggle] | Show or hide dim right-aligned timestamps on chat messages. Shown by default, matching opencode. A reply's time appears with its text, not while the model is still thinking. Times are written as 12-hour with an AM/PM marker. Every rendered time in the app goes through one shared vocabulary (message headers, the notification center, and the /stats and /debug “as of” footers), so no two surfaces can disagree. A client-side display toggle: applied locally to the panel, never sent to the agent. GPU build only. Aliases: /show-timestamps, /show_timestamps.See /cot /show-tools /show-control |
| /add-dir | <path> | Grant the agent access to a directory outside the project root. Access covers the directory itself and everything under it, whether a tool reaches it by the path as typed or, through a symlink, by the folder it leads to. The path is the rest of the line as typed, so it may hold spaces. Alias: /add_dir. Persisted in permission rules; when kcode can't save the rule, the access holds for this session only and the reply says so. File tools may read and write there; a shell command may read there, and still needs permission to write. A read outside the project needs no grant unless it reaches a secret location (permissions.secret_paths), so the grant matters most for writes and for reading such a location.See #permissions |
| /add_dir | <path> | Alias for /add-dir. Grants a path outside the project root.See /add-dir |
| /tools | List every tool registered with the agent, grouped by where it came from. kcode's own are under Built into kcode, then each plugin's and each MCP server's under a heading naming it and its scope (From the user plugin hello, From the project MCP server files) each group sorted by name, each tool with its description. A plugin tool that takes a built-in tool's name (through shadows) shows under its plugin, so it can't pass for kcode's own.See #tools | |
| /init | [<focus>] | Scan the repository and write a compact project-context file so future kcode sessions ramp up fast. It is the equivalent of Claude Code's and opencode's /init. The agent reads the highest-value sources (README, manifests, build/test/lint/CI config, existing instruction files), extracts the hard-earned facts an agent would otherwise guess wrong (exact dev commands, how to run a single test, monorepo boundaries, real entrypoints, toolchain quirks), and writes them to AGENTS.md at the repo root, then makes CLAUDE.md a symlink to it (ln -sf AGENTS.md CLAUDE.md) so both filenames read one source of truth and can never drift. An existing AGENTS.md is improved in place; a real (non-symlink) CLAUDE.md is folded into AGENTS.md and then replaced with the symlink. /init <focus> passes a focus or constraint into the prompt (substituted at $ARGUMENTS, like a user markdown command). A bundled command, listed by /commands and user-overridable. A setup action, so it is agent_invocable: false: the agent cannot fire it via run_command.See /skills /agents |
| /commit | [<args>] | Commit the current work with a message in the repo's style. The agent reviews the diff, stages deliberately (never git add -A, never secrets), and writes the message; text after the name follows the instructions as a new paragraph. A bundled command: the command body becomes the agent prompt and runs as a normal turn. Listed by /commands, overridable by your own commit.md under a commands dir (user commands win the name), and invocable by the agent via run_command (it sets agent_invocable: true).See /review /init |
| /review | [<args>] | Review the current changes and report findings by severity. It reviews the working diff or a given range; text after the name (a range, a path) follows the instructions as a new paragraph. A bundled command: the command body becomes the agent prompt and runs as a normal turn. Listed by /commands, user-overridable, and agent_invocable: false by default (an expensive self-check you can opt into via your own overriding review.md).See /security-review /commit |
| /security-review | [<args>] | Security-review the pending changes. It looks for injection, secret leakage, unsafe file/process/network handling, and permission-boundary violations in the diff; text after the name follows the instructions as a new paragraph. A bundled command: the command body becomes the agent prompt and runs as a normal turn. Listed by /commands, user-overridable, and agent_invocable: false by default.See /review /agents |
| /mcp | List the connected MCP servers, then the ones that are not connected and why. The connected ones are the MCP-runtime subset of loaded plugins, with name and source; the others are under Not connected, as /plugins lists them. Servers are declared in <project>/.mcp.json (Claude-Code-compatible: command/args/env for stdio, type+url (+ optional headers for API keys/auth) for http/sse) or ~/.kcode/mcp.json, and connect when a session spawns: a toast over the session then lists each one with its tool count, or why it isn't connected; a plugin.toml with kind = "Mcp" also works. A daemon round-trip reading the session's live plugin stack. GPU build only.See /plugins #plugins | |
| /files | Open the focused session's live project tree as an overlay. It is a gitignore-respecting listing of the project root, directories first (each sorted case-insensitively), every file carrying its git working-tree badge (✏️ modified, ✨ added, 🗑️ deleted, ❓ untracked, ➡️ renamed) over a faintly status-tinted row, plus a file-type icon. The daemon walks the tree and streams a fresh snapshot on subscribe, at each turn boundary, and on any debounced filesystem change, so it stays live while open. Click a directory to expand or collapse it. A file is actionable only when its configured opener or macOS file association is available; unsupported files have no pointer or opening feedback. A supported click shows Opening with the app name after the launcher starts, and a failed launch shows an error (see session_panels.files.editor). Long trees scroll inside the card, with the keyboard selection kept in view. ↑/↓ move the selection through the tree and Enter activates the selected row (opening a file, toggling a directory) the keyboard twin of a click. A client-side command intercepted in the GPU panel, never sent to the agent. Dismiss with Escape. GPU build only.See /diff /control | |
| /tasks | Open the focused session's task checklist as an overlay over the grid. It shows one row per task: a bracketed status marker ([✓] done and [ ] to do in muted grey, [•] in progress in amber) and the task's subject, in the order the agent listed them, under a header summarising the counts (task count · N done · N in progress · N to do); the in-progress task also shows its present-tense caption (the tool's activeForm) beside it; otherwise, a task that waits on unfinished tasks names them beside it (waits on …). Click a task to open its detail view: its subject, id and status, the unfinished tasks it waits on, and its markdown body (the tool's body); ← goes back to the checklist. This is the live, persistent view of the task tool's list (the same session-scoped tasks store /jobs' sibling reads): the daemon streams a fresh snapshot on subscribe and at each turn boundary while the overlay is open, so it tracks the agent's task writes live. A client-side command intercepted in the GPU panel, never sent to the agent. Also toggled by Cmd-T. ↑/↓ scroll a line, PageUp/PageDown a viewport, and Home/End jump to the ends when the checklist or a detail body outgrows the card. Dismiss with Escape (or Cmd-T again). GPU build only.See /jobs task | |
| /notes | Open the focused session's project notes as an overlay. It lists every note filed in <project>/.notes/, most recently saved or edited first, each row showing its title (the note's first line), a one-line preview of the rest, and how long ago it was last saved. Notes are your own scratch space for ideas that come mid-turn (a thought for the model later) so nothing here ever reaches the agent on its own. Search by title or body in a normal text field with cursor movement, selection, paste and undo. ↑/↓ or a click selects a note; Enter on a row, double-click or Edit opens it in the note composer (the file name stays fixed on edit). Tab/Shift-Tab cycle through search, New note, the list, Edit, Insert and Delete. Arrows also move between the list and buttons; Left/Right leave search only at a text edge with no selection. The focused control has an outline, and Enter/Space activates its action. Hidden note actions are skipped when there are no matching notes, while New note stays reachable. Inserting is explicit: the Insert into composer button or ⌘Enter appends the selected note after a blank line under the existing prompt, never overwriting or submitting it, and the note stays filed. Delete / ⌃D deletes after a confirmation; New note / ⌃N starts a blank new note, never an edit of the parked draft. Cmd-I resumes a parked draft instead. Escape clears search first, then closes. The selected note stays in view during keyboard navigation and follows the same note across a refresh. Notes are markdown files named YYYYMMDD-HHMMSS-<first-line-slug>.md, body only, no frontmatter: read or edit them with any tool. Before every save in a Git repository, kcode lists /.notes/ in the repository's .git/info/exclude, never a file in the project, and even when a .gitignore rule already ignores the folder, since another branch's may not, and a toast says when it added the line. It then checks that Git ignores the folder, reading the rules as the git command line does. If a .gitignore rule lets .notes/ back in, or the line cannot be written, the note is not saved and the draft stays available; notes already tracked by Git must be removed from the index before private saves are allowed. The .notes/ directory and note files must not be symlinks. Outside Git, nothing is written but the note. /undo never touches a note: a turn's records leave out the project's .notes/. Client-side: the GPU client reads and writes the files itself; the daemon never sees a note. Also toggled by Cmd-Shift-I and the command palette's 'Notes…'. GPU build only.See /note Cmd-Shift-I Cmd-I | |
| /note | [text] | Jot a project note without leaving the prompt. /note <text> files the text as a new note in <project>/.notes/ straight away (one-shot quick capture for an idea that arrives mid-turn) and a toast names it. Bare /note switches the composer into the note composer instead (the same thing Cmd-I does): the prompt you had typed is stashed, the rail and a NOTE chip turn the warning hue, Enter files the note and returns you to the prompt with your stash restored only after saving succeeds; failures keep the draft. Cmd-Alt-I files the current prompt directly for later and clears it after success. Shift-Enter inserts a newline, and Escape (or Cmd-I again) backs out keeping the draft for the next time you open it. A note never enters the prompt history and never reaches the model: browse, push, edit, or delete them with /notes. Client-side, intercepted in the GPU panel. GPU build only.See /notes Cmd-I |
| /jobs | [kill <id>] | Open the focused session's background-jobs overlay, a live list of its running shell commands and subagents. The list covers auto-backgrounded bash runs, shell_spawns and live subagents, and a shell command that has finished while a background job it started still runs, its row reading finished, 1 background job still running and its Stop killing those jobs: gathered live from the shell-host exec registry and the subagent registry at query time (nothing is stored, so the list can never go stale). Each row shows its kind tag (bash / subagent), the command, or the subagent's name and the rounds it has run so far, how long it has been running, and a labelled Stop button (a bash row kills the exec: a watched command's exit notice then tells the agent the user stopped it and starts no turn; a subagent row trips the child's cancel token, and a permission prompt or question the subagent was waiting on closes). The daemon streams a fresh snapshot on subscribe and on each transition that can change the set (a turn boundary, a subagent transition, a shell command ending (it exited, was killed or was lost to a shell-host restart) or a background job a finished command left ending), so the overlay tracks live and a finished job's row drops out as soon as the job has ended. A stopped row leaves once its command or subagent has ended, not when Stop is pressed; a background command started during a turn shows at the next of these snapshots. The session's tile also carries an always-on jobs card above the composer with the same rows (it subscribes on attach), so the work is visible without opening anything. Each card row has a Hide and a ✕ that stops the job, and the card has Hide all while it shows two or more: a hidden job keeps running and stays in this overlay, the card's header counts it (1 background job · 2 hidden, listed in /jobs), and the card forgets the hide once the job ends or the window reloads; the overlay is the fuller, keyboard-scrollable view. /jobs kill <id> stops one from the composer instead of opening the overlay: a shell command by its whole id (e3), a subagent by its id or the start of it; an id that names no running job, or the start of more than one subagent's id, kills nothing and says so. A client-side command intercepted in the GPU panel, never sent to the agent. Dismiss with Escape (or click the scrim). GPU build only.See /tasks |
| /control | Open the focused session's control-plane (<cp:*>) timeline as an overlay. It shows the session/turn/round breadcrumb, a counter summary, one colour-coded row per emission (system→agent and agent→system, drops in error colour), and the last continuation decision as a footer. The daemon replays the accumulated control history on attach, so it matches the transcript; live events stream in. ↑/↓ scroll a line, PageUp/PageDown a viewport, and Home/End jump to the ends of a long history. A client-side command intercepted in the GPU panel, never sent to the agent. Dismiss with Escape. GPU build only.See #channels /show-control | |
| /notifications | Open the notification center, a drawer that slides in from the right over the grid. It lists the durable, cross-project notification log newest-first: one stacked entry per notification, with its category and local time above a full-width message. Read categories are muted; unread categories use their theme's status colour: △ Needs input, ✗ Error, ✓ Completed, ◆ Agent message (the agent's notify), ◇ Plugin and ◇ Skill (a plugin's or a script skill's own notice, its name first), ⚠ Hook (a project hook that won't run, is held until you trust it, stopped, or skipped a fire: the hook named first), ⚠ Plugin problem (a plugin folder that failed to load, an MCP server that is not connected, a tool a plugin went without, or a plugin the project's policy blocks or requires: one entry per problem, the plugin named first), ⚠ Kept checkout (a subagent's checkout that held work when the subagent's process ended before it could clean up, after a crash or a kill; kcode keeps it at its next start, and the entry names the checkout and the project whose /worktree adopt opens it), ⚠ Account (a reminder that the free trial ends in three days, then tomorrow, or that a payment failed: each posted once; Enter or a click opens your kcode.sh account page), ↑ Update (kcode 0.6.0 is downloaded. Restart kcode to use it., posted once per update; Enter, a click or its Install update restarts kcode into it (after a confirmation that names any working session, since the restart halts its turn) and your sessions come back once kcode starts again; for an install that can't replace itself the row opens the download page instead), and ✦ What's new (one entry per unseen release-notes bullet, posted once per build). A needs-input, error or completed entry names its session by its title or, until you name it, by your first message in it (up to 60 characters), so two sessions of one project read apart. Names in a message (a session's, a hook's, a plugin's, a tool's, a command in a what's-new entry) are set as inline code is in the chat, in the monospaced font on a faint fill; a desktop banner shows them as plain words. Spacing and dividers separate entries; the drawer fits narrow windows without squeezing messages into columns. The log is one global stream across every session (unlike the per-session /control timeline) and survives restarts (the daemon replays it on attach). A glowing seam always paints the window's right edge: with unread notifications it shows the colour of the highest-severity unread (error over needs-input over a hook, plugin-problem or kept-checkout warning over done) at full intensity, with a small tab in that colour counting the unread notifications (99+ past 99), and with nothing unread it drops to a faint accent line with no tab rather than disappearing; the seam is the tray's only pointer affordance, so it never goes away. The seam is a live affordance, not just an indicator: clicking it or its tab opens the notification center (the mouse counterpart to Cmd-Shift-N). A new notification also shows for about five seconds as a card in the window's top-right corner, its session's name (or kcode for an app-level row) over its message, edged in the row's colour, then slides right, into the seam; the pointer resting on the card keeps it up. A click on the card does what a click on its row does: it opens the session, or for an update restarts kcode into it (asking first while a session works) or opens the download page. No card shows for a completed turn, a what's-new, kept-checkout or account row, for a notification from the session you are in, while the drawer is open, while the kcode window is not in front (the desktop banner speaks then), for the rows a window gets as it starts, or for a repeat of a row still unread. Notifications are marked read by visiting their originating session, having it open to work in (maximized, or selected in Sidebar and Tabbed) while the kcode window is active, however you got there: a click, ⌘⇧] / ⌘⇧[, ⌘1–9 or a jump; one that arrives while you are in its session is read at once, and selecting a tile in the grid is not a visit (not by opening the drawer) except the what's-new, kept-checkout, account and update rows, which belong to no session: opening the drawer is what marks them read, Enter or a click on a what's-new or kept-checkout row jumps nowhere, and on an account row it opens your kcode.sh account page. Clicking a notification row jumps to the session that raised it: bringing it back onto the grid (or resuming it if it had stopped) and opening it, maximized or, in the Sidebar and Tabbed layouts, selected, then closes the drawer. ↑/↓ move the selection through the rows and Enter jumps to the selected notification's session, the keyboard twin of that click. A plugin's or script skill's notice can offer a slash command (kcode.notify's command): its row carries a Run /<command> button, and r runs the selected row's; the command runs in the session that raised the notice, once a stopped one has resumed, and that session opens; its card carries the same button. When the kcode window is not focused, a needs-input, error, done, agent, plugin, skill, hook, plugin-problem, kept-checkout or update notification also escalates to a macOS desktop banner: tagged to its session, or titled kcode for a kept checkout or an update, whose banner brings the window forward (a what's-new or account row never escalates: they wait in the drawer); returning to that session (focusing its tile) clears its banner. The Dock icon counts the unread needs-input and error notifications, and loses the count once they are read. OS banners require kcode running as the installed kcode.app (see scripts/bundle-mac.sh) and are governed by macOS notification settings; a bare/unbundled binary posts none. Also summoned by Cmd-Shift-N, the command palette's 'Notifications…', and the context menu's Notifications. Each row also carries a trailing ✕ that dismisses just that notification, and the fixed drawer header carries Clear all (disabled when empty) and a close button; a fixed footer shows the keyboard shortcuts: clearing removes the rows from the durable log for every client (the daemon broadcasts the removed ids); the keyboard twins are x / Delete (dismiss the selected row) and Shift-X (clear all). Deleting a session also removes its notifications, so no row is left pointing at a session that is gone; a launch clears any such rows left from before. The rows scroll: a long log scrolls inside the drawer instead of clipping at its bottom, the keyboard selection stays on the same notification as new ones arrive, follows the adjacent entry after dismissal, and scrolls into view as ↑/↓ move it. PageUp / PageDown / Home / End page the list. A client-side overlay, never sent to the agent. Dismiss with Escape or by clicking the dimmed backdrop. GPU build only.See /control #channels | |
| /procs | Open a live overlay of the machine's dev-relevant processes: builds, servers, databases, watchers. One row per process: a kind chip (build in amber, server in accent, database/watcher muted, and other, muted, for the unmatched processes procs.show_all lists), the process label + pid, the LISTEN ports a server holds (e.g.:5432), and the attribution column (short working directory, else the parent pid) so two same-named builds never read as one, a build you run in a terminal shows next to one the agent runs. The daemon scans the process table with proc-classify and classifies each process by name, command line and behaviour (a node holding a LISTEN socket is a server, not a build; a cargo watch run is a watcher); only the dev-relevant dozen surface, the rest are filtered at the lib: procs.show_all keeps them as other rows after the classified ones, the way to read the name or command line a new [[procs.watch]] rule should match. Off by default: the overlay exists only while open, and the daemon polls on a cadence (procs.poll_ms, default 2000) only while someone watches, closing (Escape) cancels the poll to zero work. The watch table is user-extensible via [[procs.watch]] config blocks (match / kind / label) layered over the built-in defaults. A client-side command intercepted in the GPU panel, never sent to the agent. ↑/↓ scroll a line, PageUp/PageDown a viewport, Home/End jump to the ends. See /jobs /stats /debug | |
| Session | ||
| /help | [<name>] | Show the slash-command list, each command with its arguments and a one-line description. Each line is the first sentence of the command's entry in this manual. /help <name> explains one thing: a command, a config key, a keyboard shortcut, a tool, a channel, whatever the manual names, in every section that names it (/help theme shows the /theme command and the theme config key; the leading / and the case do not matter). The answer is the entry's facts (arguments, type and default, the shortcut's context, …), its description and its related names; a name the manual does not know gets the near names instead. The ⌘P palette lists every slash command too, described from the manual, and its Open user manual row opens this whole manual in your browser.See Cmd-P |
| /version | Print the exact running build as a notice in the chat. It names the version (major.minor with a monotonic build number as the patch: the git commit count, so it increments every commit), the git commit it was built from (with a -dirty suffix when the working tree had uncommitted changes at build time), the UTC build time, the target triple + cargo profile, and the rustc version. The same identity surfaces in the status-bar footer's compact tag (v<major>.<minor>.<build> · <commit>, left out when a narrow tile has no room for it), via kcode --version, and at the top of kcode doctor, so a stale installed binary is distinguishable from a fresh one at a glance (the build number moves every commit; a bare semver version would read the same across builds). GPU build only. | |
| /quit | Exit kcode entirely (closes the window and all sessions). While any session is working (its turn or its subagents running) a confirmation names them first; quitting halts their work, and the sessions stay resumable from the switcher or with --resume. See /exit | |
| /exit | Close this session: its agent stops and its tile leaves the grid. There is no detach that keeps an agent running off the grid, and no separate /stop. Closing a session that is still working (its turn or its subagents running, which the close stops) shows a confirmation first (a centred modal, Cancel highlighted by default); an idle one closes at once. The session stays resumable from the switcher (Cmd-K) or with --resume, except a worktree session whose checkout has no changes or new commits: closing it deletes the session with its checkout and branch, and a toast says so (worktree.auto_remove_clean, on by default). The tile's close gesture, the context menu's Close and the palette's 'Close session' do the same; use /quit to leave kcode.See /quit | |
| /clear | Clear the current chat display without exiting the session or changing saved or model history. The /clear invocation and its confirmation remain visible. Earlier rows stay hidden through later history updates and reconnects in this panel; reopening the session can show the saved history again. See /compact | |
| /feedback | <message> | Send a feedback message to the kcode team. The message is the rest of the line as typed, line breaks kept. The daemon sends it to kcode.sh's API with the running build's identity (version, build id, OS version) and, once this Mac is signed up, its device token, so the team knows whose account it came from; a Mac that isn't signed up sends it without one. A sent message answers "Feedback sent." A failure answers with the reason. Nothing is stored locally. On each of your first three app launches, a tip in the first session you open names this command. GPU build only. See /version |
| /export | [jsonl|markdown|md] | Alias for /share.See /share |
| /resume | [session-id] | Resume a stopped session by its id: its agent starts again and the session opens. It opens maximized, or selected in the Sidebar and Tabbed layouts, in the tile it already has at once, or in a new one once it is running. The id of a session that is already running opens it. In a project you haven't trusted, the trust dialog shows first. With no id, it opens the session switcher (⌘K), where you pick the session to resume. From the command line: kcode --resume <id> or kcode --continue-last (see Command line). |
| /debug | Open the daemon-wide live debug window as an overlay. It shows process vitals (version, pid, uptime, socket, data dir, live/known sessions, connections, subscriptions), then one card per live session, leading with the why-is-it-waiting section: the in-flight turn's live elapsed time, every parked permission prompt (tool · agent · how long) and parked question, the session's subagents (kind · status · rounds · error), and the last-activity age in the header, so a wedged session is diagnosable from the first lines, then identity + overrides (model/effort/goal/permission mode), busy + restart counts, context occupancy with a fill meter + the last turn's tokens (the share and its two counts are of the input budget, with the window beside them, or of the window when the turn reported no budget), the live counters (turns + provider rounds, the last turn's wall time, tool ok/failed rate, compaction runs), the recent continuation-cascade trail (the last few continue/stop decisions with rule names and reasons), armed prompt loops with fire counts, the agent loop's own state (in-flight turn/round, doom-loop run length + threshold, request-envelope overhead, armed subsystems), shell-host child status, LSP servers (configured + spawned), and the loaded plugins; then the project hook stacks and the watcher rows (the skill, command, and style and theme watchers' armed state; a worktree operation in flight: <path> row per checkout operation still running). The client adds its own frame-interval readout in the header, and a memory section charts the daemon's and the client's own process memory over the last hour side by side: the physical footprint (Activity Monitor's figure; RSS where a platform has no footprint), sampled every 5 s from launch whether or not the window is open, with each process's rss, its peak since launch (the kernel's own count, so a spike between two samples still shows; where a platform has none, the largest sample, labelled just peak), drift over the window, thread and fd counts, and for the client the live decoded-texture ledger (count, bytes). While a process holds graphics memory marked reclaimable (memory macOS may take back when it runs short, which the footprint leaves out) its chart draws a second line in the muted text colour, the footprint with that memory, and the two newest figures carry their line's colour. Off by default: the overlay exists only while open, and the daemon builds and pushes a fresh snapshot on subscribe and then once per second (session_daemon.debug_push_ms) only while someone watches, closing the window (Escape) cancels the tick to zero work. A client-side command intercepted in the GPU panel (any focused session's input opens the one daemon-wide window), never sent to the agent. Clients without the overlay get the same snapshot as a text reply. ↑/↓ scroll a line, PageUp/PageDown a viewport, Home/End jump to the ends.See /stats /control /doctor | |
| Memory and context | ||
| /compact | [from <n>] [snip|summary|auto] [instructions…] | Compact this session's model context now, freeing context-window space without erasing saved chat history. Original replies, reasoning, tool results and images remain available after restart; scroll back or choose Older to load earlier pages. Browsing history never adds those records back to a provider request. Older turns are summarised by a dedicated summarizer pass using the compaction template: a structured, anchored summary (Objective / Important Details / Work State{Completed,Active,Blocked} / Next Move / Relevant Files) that merges with any previous summary instead of re-summarising it. A successful save atomically selects the summary and retained messages for the model. Summary and file/skill restore bodies are model-only: chat and Markdown export keep the originals instead; the most recent turn is kept verbatim, but at most a quarter of the compaction trigger of it (compaction.preserve_recent_turns / preserve_recent_fraction), a longer last turn is cut at the earliest step whose tail fits, and the last step is always kept. Tool calls and results feed the summary (truncated at 2000 chars each with an omission marker); images become [Attached image] lines. The prompt template is user-editable: <project>/.kcode/compaction-template.md overrides ~/.kcode/compaction-template.md in a trusted project (materialised from the compiled default on first use), with {{conversation}} and {{previous_summary}} slots. A trailing free-text argument steers the summary (e.g. /compact focus on the schema migration; its line breaks are kept): it is appended to the summarizer prompt as an emphasis block; the strategy token stays optional (/compact summary focus on… also works). The strategy words and from match in any case (/compact Snip, /compact From 2); a first word that looks like one of them misspelled (snipp, form) compacts nothing, and the reply names the word it looks like and how to focus a summary on what you typed (/compact summary snipp). from <n> makes it a partial compaction: everything before the n-th user turn is compacted (summary replaces it), that turn and later kept verbatim regardless of the preserve window. Like /context, it measures against the session's model first, so a /model switch since the last turn counts, and it declines with the reason when no provider can serve that model. Bare /compact (no strategy token) is explicit intent and always compacts; only /compact auto keeps the automatic gate, and when it stands down the reply names why (below the trigger, re-arming after the last pass, the circuit breaker is open) with the measured count against the trigger. The lifecycle is marked in the transcript: a 'Compacting context…' bubble posts at the start (and the tile shows Working for the duration), a 'Context compacted (strategy): before → after tokens (N messages summarized, M recent kept)' bubble posts at completion, a manual /compact adds a line saying where the tokens left are (the system prompt and tools, the summary, the recent messages, restored files and skills), and an autocompaction posts the same completion bubble, all persistent transcript bubbles routed via a dedicated CommandReplyKind::Compaction, not toasts. The status line's token/context count corrects to the post-compaction figure immediately on completion (the daemon pushes a corrected usage report), rather than holding the pre-compaction number until the next turn. While compaction runs, the working strip names the observed phase (Preparing / Writing summary / Pruning / Saving) with the elapsed time and the token reclaim being won (reclaiming 312k → 96.5k): a compact inline readout, not a separate bar. Progress covers manual, automatic, and overflow compaction and returns when the window reconnects. Overflow compaction also answers a request the provider refused as too large (an HTTP 413): it replaces images with short notes, oldest first, until the request is half the size, summarizes when that is not enough, and retries once; the completion bubble names the images it cleared. Esc cancels before saving and keeps the original history; once Saving begins, kcode waits for the database write to finish and reports its outcome. Other sessions remain responsive while manual compaction runs. Completion, cancellation, failure, and disconnect clear the indicator. Every outcome leaves its line in the chat, so a /compact that did nothing, failed or was cancelled says why (no history yet, a from turn that does not exist, below the trigger); a pass that ran and freed nothing says whether every message is in the recent turns it keeps, everything older is already in the summary, or no old tool output or image is left to clear, and how full the context is. The summarizer cannot consume messages queued for the main turn. It uses its own text-transformation prompt and preserves quoted protocol tags literally. Missing template sections or an output-limit cutoff fail the pass without replacing context. Automatic failures show the reason; after repeated failures the notice says automatic compaction is paused and offers /compact to retry. After a compaction the summary reaches the model once, as the first message of the model projection; the system prompt is unchanged.See /clear |
| /context | Show how the session's context window is used. It lists the model window: the window of the model the session's next turn runs on, even before the first turn or right after a /model switch (mid-turn, the model that turn runs on); when no provider can serve that model, the reply says the window isn't known and why rather than guessing one, the input budget (the window less the tokens kept for the reply and a safety margin), the fixed request overhead (system prompt + tool schemas, as the agent loop's RequestEnvelope measured them last turn: split into its two parts), the active model projection bucketed by role (not all saved display history) (user / assistant / tool results / system, plus an image count when any are in play), total used as a share of the input budget and the tokens remaining in it (the chat footer's share, so the two agree) and the token count at which the session compacts automatically, with what sets it (this session's /autocompact budget, the configured budget, or the percentage of the input budget) and, right after a pass, the re-armed count the next pass waits for. Every number comes from the same measurement path the compaction trigger and <cp:context-usage> emission use, so the report can't disagree with the loop's own arithmetic. Daemon-computed for the live session and rendered as an info reply in the chat. Per-session by design: the cross-session roll-up is /stats.See /compact /autocompact /stats | |
| /memory | [save | search <query> | delete <name> | consolidate [on|off|status]] [scope=user|project|all] | Inspect and curate the memory store (the human counterpart to the agent's memory_* tools). Bare /memory (or /memory list) lists every stored memory, kind (user/feedback/project/reference), name, description, plus a (project)/conf/via annotation when a row diverges from the defaults, and ends with a footer teaching the sub-actions; with none stored it says how to save one. /memory save opens a GPU form (kind + scope selects, name/description text fields and a body text-area, real text inputs: a caret, cursor keys, selection, ⌘V, ⌘Z; Tab/⇧Tab and ↑/↓ move between fields (inside the body Tab indents, and ↑/↓ move between its rows and hop off only from its first/last row), ←/→ cycle a select, Enter or the Save button submits, ⇧Enter is a newline in the body) that upserts the memory by name. /memory search <query> recalls matching memories ranked by relevance × confidence × recency, each hit showing its score and the date it was written. /memory delete <name> forgets one; a name no memory has is reported as missing rather than forgotten, with the command for the other scope when a memory there has that name. The session's agent is told of a save or delete made here at its next turn, as it is of its own; a search is yours alone and tells it nothing. /memory consolidate runs the background consolidator now: it distils durable facts from your recent sessions into new memories (provenance-guarded, stamped as consolidator-sourced), surfacing on the /control timeline as a memory-consolidator subagent; /memory consolidate on|off turns the automatic runner on/off (persists memory_consolidator.enabled + relays it live) and says which way it switched, and /memory consolidate status shows whether it is on. search/delete accept a trailing scope=user|project|all token (search spans both by default and, given a scope, shows that scope's best matches; delete defaults to the user store). A daemon round-trip. GPU build only.See /tasks memory_save memory_search |
| Agents | ||
| /fork | Branch a copy of this session at the current point. The new session starts with the same transcript and diverges from here, inheriting the source's /model, /effort, and /autocompact overrides (a fork continues the conversation). Spawned live in a new tile; with every one of Mission Control's 256 tiles taken it forks nothing and says why. A fork of a worktree session works in the same checkout, which kcode keeps until the fork is deleted. The agent has a twin: its fork_session tool forks with an optional title + first instruction, rate-capped by session_daemon.agent_fork_max_per_window.See /rename /share | |
| /subagent | [clear] | Configure the per-session pool of models subagents draw from. No-args opens the Helper models picker over every provider you have a key for; a model several providers list has a row under each, the pool keeps the one you check as <provider>:<model>, and subagent rows show the model by its name. Search supports normal editing, selection, paste and undo. Tab switches search/list; Down moves from search into the results. In the list, Space or a row click toggles a model, ←/→ or its effort badge cycles reasoning effort (inherit · minimal · low · medium · high). Enter or the Apply button saves. Escape closes without applying. When a spawn names no model and its agent kind declares none, one pool entry is picked at random per spawn, so a multi-model pool mixes vendors across subagents. The pool persists on the session row (survives --resume and daemon restarts) and applies live: the next spawn picks from it. /subagent clear (or confirming an empty pool) resets to the default: subagents inherit the session's own model + effort. /subagents is an alias. Also on the ⌘P palette as "Subagent pool…" (Session group) so the pool is reachable without remembering the slash command. GPU build only.See /agent /model /effort |
| /agents | Open this session's live subagent list as a floating panel. It lists every child spawned via spawn_subagent/spawn_subagent_async, in spawn order, under a header that counts them by state ('5 agents · 1 running · 2 done · 1 failed · 1 cancelled': a child stopped with Esc or a Stop button counts as cancelled, never as failed): status glyph (… spawned · ▶ running · ✓ done · ✗ failed · ⊘ cancelled, a cancelled one muted like a done one), kind and the name its parent gave it (general (engine), as the chat's live rows and /jobs name it), the rounds it has run, counted as it runs (a stopped or failed child's too), elapsed/duration, the error summary on a failed row, and the kept worktree path + branch for a worktree-isolated child that left changes, failed and stopped rows included. Client-side only (like /tasks): the daemon reads the session's subagent registry and streams a snapshot each time a child's row changes, while the panel is open (SubscribeSubagents/Subagents); Esc or the scrim closes it and unsubscribes. A running child's elapsed time counts up. ↑/↓ select a row, ↩ opens the selected child's tile and closes the panel, and PageUp/PageDown and Home/End scroll the list. Clear finished (⇧X), shown once a child has ended, drops the done, failed and cancelled children from the list; running ones stay. The chat's live rows, at the end of the transcript, list the children in the same order and name each the same way. A row's progress line leads with what the child says it is doing (its turn summary, or the word on a retried call) then its tool and token counts ('Reading the readme · 2 tools · 400 tokens'); the session's working strip shows only the session agent's own lines. A child waiting on a permission answer shows ⏸ and 'waiting on permission · bash · 1m 30s' in place of its progress. A click on a live row, on the name in a spawn or await card, or on a row of this panel (which then closes) shows that subagent in the session's read-only subagent tile beside the chat: its saved conversation shows as the chat shows its own, under the facts its row here shows, and a card in it shows that subagent's own subagents the same way. A session has one subagent tile, so opening another subagent swaps it into that tile. The ✕ in the tile's header closes it and only the view: the subagent runs on, and /jobs stops it; the tile also stays after the subagent ends and closes with its session. Its permission asks are still answered in the chat, and a subagent with no saved conversation reads 'This subagent has no saved conversation.' When Mission Control already holds as many tiles as it can and the session has no subagent tile yet, a toast says to close one first. A finished child that produced a closing reply (the advisor's advice, or any subagent's final message) shows a one-line summary of it on its settled row instead of a bare "done", so the conclusion reads inline in the transcript, not only in the tool result below. A finished row goes when a turn ends; before that, its ✕ removes it, and once two or more have finished a Clear finished line under the rows removes them all: in every window showing the session. A running row has no ✕: it stays, its spinner turning, until its subagent ends, even after the turn that started it, and every row goes when the session stops.See /tasks /control | |
| /agent | [<kind> <prompt...>] | Spawn an agent kind with an initial prompt; spawned agents stream into the chat pane. No-args opens the agent-kind picker: built-ins, your markdown kinds from ~/.kcode/agents/ and <project>/.kcode/agents/, plus any plugin-bundled kinds (<plugin>/agents/*.md), each with its description, and picking one prefills /agent <kind> in the input for the prompt. The prompt is the rest of the line after the kind, line breaks kept, and images in the composer go with it. The agent runs on the kind's model, else a pick from the /subagent pool, else the session's model, and a model no connected provider serves is refused before it starts. Its finish reaches the session's agent at its next round, in a <cp:subagent> notice that says the user started it and carries the task and the result. Stopping the session stops the agent. The session shows as working while the agent runs and goes idle when it ends, so the Mac stays awake for it. Bare /agents is a different command: it opens this session's live subagent panel.See #agents /agents |
| Worktrees and files | ||
| /worktree | new <name> · list · remove · adopt [branch|path] · merge [slug] [commit] · update [slug] | First-class worktree sessions. new <name> [start-point] spawns a session bound to a fresh checkout of the current project at .kcode/worktrees/<name> on branch kcode/<name>, created at the base's HEAD, or at <start-point> (a commit hash full or unambiguous-short, branch, or tag, resolved on the base repo) when given: use it to reproduce a bug at a known commit, continue stale work, or bisect. The session's tools root there, the switcher groups it under the base project with a ⎇ branch badge, and /files shows the branch in its header. Until you name it, the session's tile (its Sidebar row, its tab, and the grid's window-edge label) carries the same badge after the project name (kcode · ⎇ kcode/<name>), so it no longer reads the same as its base session. A worktree session tiles on creation, new, adopt, and the agent's spawn_worktree_session all bring the worker onto the Mission Control grid as soon as it goes live, without stealing focus from the session you ran it from (with all 256 of Mission Control's tiles taken, new and adopt open nothing and say why, and a worker the agent starts waits, named in a warning, for the next tile a close frees), and the grid autogroups it: every worktree tile and its base session land in one named cluster (the drag-to-gather wash + the project's label), minted on first use and persisted like a manual group (a relaunch keeps it, name and all), so a project's tiles sit together (its plain sessions first, then its worktrees in the order they opened) without you gathering them. Dragging a tile out of the wash, or Ungroup, opts it out of the autogroup for the rest of its life (a relaunch remembers it) and a tile you put in another group stays there; a deliberate choice wins over the automation; a project with no worktree session open is never clustered, however many sessions it has, and neither is a lone tile: a cluster needs two of the project's tiles. Once the cluster no longer holds a worktree session and one other tile (you closed, deleted or dragged out the last worktree, or dropped it into another group) kcode takes the cluster apart and the tiles left go back to ungrouped; a cluster you renamed or added a tile to is yours, and stays. At creation the checkout is seeded from the base's .worktreeinclude: a gitignore-syntax file naming which gitignored files to copy in (.env, local certs: the files git can't populate; a matched ignored directory copies as a whole tree; .git never copies, and from .kcode only kcode's own files stay out (the project database, sessions, checkouts) so .kcode/config.toml or .kcode/rules/ can be named). The worktree also gets a stable isolation slot (lowest free ≥ 1 per project, the base is 0) driving the [worktree.env] template overlay injected into its shell: see worktree.env. It builds in a Cargo build folder of its own, .kcode/target/<name> in the base project, so neither checkout's build can use crates compiled from the other's files; the folder goes with the checkout. Bare /worktree lists this project's worktree sessions as text. list opens the live worktree panel, a floating overlay of every worktree session in the project of the session it was opened in, which its header names (kcode · 2 worktrees · 1 working), driven off the live session registry (no daemon round-trip): each row carries a status dot (the dot the session wears in /stats all and the ⌘K switcher: a looping session in the working colour), a status word (working / needs input / error / finished / looping / stopped; none for an idle row), the ⎇ branch badge, the live context-occupancy %, and when it was last active (the time today, Yesterday, or a date), sorted as /stats all sorts: needs-input rows first, then errored, working, finished, idle (looping among them) and stopped ones, each group most recently active first. A row click (or ↑/↓ + Enter) jumps to that session: brings it onto the grid and opens it, or resumes a stopped one and opens it once it is running again, mirroring the notification-drawer row action. Dismiss with Esc; the panel reseeds every tick so progress moves live, and the selection stays on its session when the rows re-sort. remove shows a confirmation, then deletes this session's checkout + branch together with the session and its conversation, and a toast names what went; it is fail-closed: uncommitted changes keep it, and so do commits on its branch that the base's branch doesn't have (what counts as a change: see worktree.auto_remove_clean); the refusal names the branches and says how to land the commits with /worktree merge <slug> in the base session, or to discard them. When the project's folder is gone (deleted, moved or on a drive that isn't mounted) remove deletes the session and leaves its checkout and branch as they are, and the toast says so; closing such a session keeps it, and the toast names the missing folder. remove, merge and closing a clean worktree session never delete a checkout another session works in, a fork of the worktree session, or a session opened there: each keeps it and names those sessions, a close in a toast; and while kcode deletes a checkout, no session, ! command or /agent run starts in it. Closing a worktree session whose checkout has no changes or new commits deletes the session with its checkout and branch, and a toast names what went (worktree.auto_remove_clean). adopt opens an existing checkout as a session: bare /worktree adopt picks from the base repo's linked worktrees that have no session yet and no running subagent working in them (hand-made git worktree add trees, kept subagent worktrees, and the checkout of a subagent whose process ended), adopt <branch|path> targets one (the rest of the line, as typed, is the target, so a path may hold spaces; a relative path reads from the session's own folder, its checkout in a worktree session, and ~ from your home folder), the daemon validates it is a linked worktree of this repo, derives a slug from the directory name, gives the checkout its project's grant (a checkout of a project never trusted opens untrusted), and spawns the session rooted at the checkout (never moved; a detached HEAD is refused, and so are a checkout a running subagent is using and one whose folder is gone; while kcode settles an ended subagent's checkout at launch, the adopt and the picker wait for it). The /agents panel's kept-worktree rows carry an Open as session chip driving the same path. merge lands a sibling worktree's branch in the current session's tree: preflights both trees clean and runs the merge as a turn of the receiving session, so /undo reverts it, and so it is refused by name while a turn, an /undo or another merge runs in the receiving project folder (then squash-merges by default) add commit for a true two-parent merge commit. Bare /worktree merge picks from this project's worktree sessions. A clean landing emits <cp:worktree-merged> (diffstat + the worker's final report) into the receiving transcript and removes the worktree, its branch, and its session. Conflicts raise a modal: hand to the agent (the receiving session's agent gets the conflict list, shown in its chat as a one-line kcode notice that opens to the full text, and commits the resolution) or abort (tree restored, worktree kept). update rebases a worktree's branch onto the base's latest commit (bare form inside a worktree session updates that worktree) as a turn of the worktree session, so /undo there reverts it, and so it is refused by name while a turn, an /undo or a merge runs in the worktree; conflicts take the same modal but a hand-off drives the worktree session's agent (git rebase --continue). An abort chosen while a turn or another operation runs in the tree is refused by name and the question stays open to answer again; with no window to answer, the merge or update aborts at once and the reply says whether the tree was restored. A merge, update or remove refused for uncommitted work names up to three changed files and counts the rest. Checkout creation, removal (its clean check too), merge, update and adoption (its picker too) run off the daemon's owner task, so every other session keeps streaming while they run; one operation per checkout at a time: a second request on a busy checkout, and a resume of its session, are refused by name until it finishes. |
| /diff | Show the working-tree diff of the session's project root as a diff block in the chat. It is the whole uncommitted delta: git diff HEAD plus untracked files. A daemon round-trip backed by git-engine's working_tree_patch; reports a clean tree when there are no changes. GPU build only.See /tasks /files | |
| Settings and permissions | ||
| /permissions | [default|accept-edits|auto|plan|reset] | Open the permissions editor: choose the session's mode (default | accept-edits | auto | plan), or manage its allow/deny rules. Click Add rule or press A to open a real pattern field with selection, paste and undo. Patterns include bash(npm *), path(src/**), url(github.com/*) or tool(web_fetch); combine with && . A path(…) pattern judges a file tool's path, each file a patch writes, and each path a shell command names: its file arguments, a redirect's file, the folder it runs in and each folder a cd in it moves to, so a deny rule on **/.env refuses cat .env as it refuses fs_read of the file. A path rule's allow doesn't run a shell command, and tool(bash) && path(…) denies a path to shell commands alone. A path(…) pattern that doesn't start with / names paths from the project (src/** names src/main.rs there) and nothing outside it; one that starts with ~ names paths from the home folder instead, so ~/.aws/** names the files in ~/.aws. A url(…) pattern names one host, matched whole (*.example.com covers example.com and every host under it), with an optional port (localhost:8080) and path, where * in the path matches anything. Tab/Shift-Tab moves between pattern, decision and scope; arrows change decision/scope; Enter or Add rule saves. Normal letters never act as shortcuts while adding. In the list, arrows select; Delete or D marks that exact rule for removal, Enter/Y confirms, Escape cancels. A saved rule kcode can't read (its pattern no longer parses, or the saved entry is not a rule) lists after the others with the reason; it has no effect, and Delete removes it. In a session in a folder that is not a project: the home folder, a folder above it, /, or the folder that holds the data folder, a project rule holds for that session only, and lists with the scope session, since there is no project store. A rule kcode can't save still holds for this session only: the reply says so, and the rule lists with the scope session. Clicking a mode button selects it; Enter on the mode row cycles it. An argument sets the mode directly; reset restores the configured permissions.default_mode.See #permissions |
| /model | [model-id | provider:model-id | reset] | Switch the per-session model. No-args opens a fuzzy-filter picker over the models of every supported provider, grouped by provider: the providers you have a key for first (the six native vendors (Anthropic, OpenAI, Fireworks, DeepSeek, Kimi, MiniMax) lead, then the keyed OpenAI-compatible vendors), then every provider you have no key for under its own Provider · no key section, each folded, each opening to that provider's whole catalogue; a key is not a precondition for seeing what a provider offers. When you have keys across several providers the sections are collapsible: every provider section starts folded except the one your session's current model belongs to (so you open to a short list at your own provider rather than a long flat scroll); a session with no model yet opens with every section folded, unless just one provider has a key, whose section stays open, each folded header shows a ▸ Provider (N) hidden-count you click to expand (▾), or reach from the keyboard: ↑/↓ walks section headers as well as rows and Enter on a header expands/folds it (the picker opens on your session's current model, else on the first row it shows, so a folded header above is one or two ↑ away), and typing a query reveals matches across every section regardless of fold state. A single keyed provider is never folded. A model several providers list has a row under each, and a pick runs on the provider it was picked under: the picker writes the model as <provider>:<model>, and the session's model shows by its name. Each row shows its context window, and within a provider the newest models come first, by release date; the picker opens wide so a row's provider stays readable. The picker's footer names every key it takes, ↑ ↓ Select, ↩ This session, ⌘↩ Default, ⌘D Favorite: ⏎ sets the highlighted model as this session's override for the next turn; ⌘⏎ does that and makes it the persistent default every new session boots on (the default_model config key: a live SetDefaultModel to the daemon plus a config.toml write, mirroring Settings › General › Default model), so you can promote a model to the default without leaving the picker. Favourites: ⌘D stars the highlighted model, floating it to a top ★ Favorites section that always stays expanded, persisted to session_presenter.favorite_models, shared by this picker and Settings › General › Default model, so the models you switch between are always one row from the top. ⌘D on a starred row un-stars it; a favourite the catalogue no longer lists simply drops from the section. The runtime keeps a client per keyed provider, so you switch across vendors without a relaunch. Choosing a model under a · no key header opens that provider's key prompt right there: the same masked key prompt Settings › Providers uses, or for OpenAI the ChatGPT sign-in choice with "Enter an API key" as one of its options, and applies the model the moment the key lands (the daemon activates a new key without a restart); Esc on the prompt changes nothing. With a ChatGPT sign-in, OpenAI's section lists the models ChatGPT's server lists for that account, in the server's order; a model the server refuses explains itself, naming the plan and what to choose instead. Pass a model id to set directly, <provider>:<model> (such as groq:llama-3.3-70b-versatile) names the provider, and a bare id runs on the first connected provider that lists it, the native vendors first; an id that only an unkeyed provider lists opens the key prompt the same way; a bare id that OpenAI's catalogue has but a ChatGPT sign-in's server doesn't list says why and changes nothing, while openai:<id> goes to the server to decide; reset/clear clears the override: the session goes back to its default model, or to none when there is no default. A session that never chose a model runs on the default and follows it: resumed after the default changed, it runs on the new one. A message sent from a session with no model, once a provider is connected, opens this picker instead of failing: the message stays in the composer and is sent on the model you pick, and Esc leaves it there. /models is an alias. Keys can also be added ahead of time in Settings (⌘,) › Providers. (GPU build; the model list is read client-side from the models.dev catalogue, which the daemon keeps live: it re-fetches models.dev on a TTL and pushes the fresh catalogue to every client, on attach and whenever it changes, so models released after your build appear in the picker without an update or restart; offline you keep the built-in snapshot.) Alias: /models.See /effort /settings |
| /theme | [name] | Switch the theme. No-args opens the theme picker: a type-to-filter overlay (↑/↓ to move, Enter to choose, Esc to cancel; it opens on the active theme, marked ●, so Enter keeps it) over the discovered themes (bundled kcode-dark / kcode-light / kcode-high-contrast / the mode-following kcode / one-dark / dracula / tokyo-night / github-light / solarized-light plus any ~/.kcode/themes/*.ron|*.json, then any plugin-bundled <plugin>/themes/*.ron|*.json); an arg sets directly. Choosing one installs it live across every tile and persists it as theme in config.toml. A theme file kcode can't load is listed last with its problem (the line and column, and the field it meant for a misspelt one) and can't be chosen; a warning names it when it is found, and /doctor lists it (theme.load). While the file of the theme the window shows is broken, the window keeps the version it last loaded; a deleted one falls back to kcode-dark. Also reachable from the command palette's 'Switch theme…' and the context menu's Theme action.See #themes |
| /settings | Open the fullscreen settings page: generic, non-session app config in a sidebar + panes layout, raised over the grid. A Basic | Advanced switch above the sidebar (⌘1 / ⌘2, or a click) picks which settings the page shows: Basic holds the ones most people change or change often, the personal touches among them (fonts, theme, backdrop, smears), and Advanced holds the rest; each setting shows in one view only. A section with settings in both views ends its Basic list with a link row (14 more Chat settings in Advanced →) and starts its Advanced list with one back (← 2 more Chat settings in Basic); Enter or a click follows it. Account, the Theme designer, Plugins and Providers show only in Basic, Tools only in Advanced. A search covers both views and heads each hit's section with its view (General · Advanced). While a search is up the switch marks the view of the section shown, and ⌘1 / ⌘2 move to that view's first hit. A text setting left empty says what that means, such as (text colour). General (Directory picker, Settings navigation, Motion frame rate and Chat frame rate in its Advanced view): Default model + Default effort + window Layout (Grid/Tabbed/Sidebar) + Directory picker + Settings navigation + Theme + Grid columns + Zoom + UI font + Mono font + Chat and Composer font sizes + Animations + Working animation + Motion frame rate + Chat frame rate + Tile opacity + Tile blur + the backdrop rows (Backdrop (Shader/Image/Video/Off, the one thing that paints behind the grid) then its style, wordmark, reacts-to-activity, per-tile light, and the background image and video) + the notification triggers (Notify: needs input / errors / turn complete, the notification-center gates, each toggled live via a daemon relay) + the /files Editor and Image opener commands (a command line, edited in the text-editor overlay); Account: the kcode.sh account this Mac is signed up to, its status (the license notice, such as the trial's days left, or Active), name, email, plan (the subscription with its period, state and renewal, a complimentary plan, or the free trial's end: the same words kcode license status prints), Macs in use of the account's limit and the last check-in, with buttons: Open on kcode.sh (the account page: billing, invoices, Macs, your product analytics answer), Subscribe on a Monthly and a Yearly plan row (shown only while the account has no running subscription; each opens that plan's checkout in the browser), Check now (checks the license with kcode.sh at once; reads Checking… until the answer, then a toast says it checked in or why not), Sign out (after a confirm: this Mac leaves the account, gives back its place, and kcode stops until it signs up again) and Contact support; a build that needs no license says so; Memory: Memory auto-recall (the per-turn memory.auto_recall gate, off by default: the toggle persists to config.toml AND relays live through the daemon's generic ApplySettings settings relay, so running sessions honour it at their next turn), with the other memory settings in its Advanced view; Command files and Skill files (Advanced view): Command dirs and Skill dirs (comma-separated path lists, edited in the text-editor overlay); Project hooks (Advanced view): the hooks_enabled switch; Providers: a searchable list of every keyable LLM provider with its connection status, type to filter, click or Enter a row to connect it. An OAuth-capable provider (OpenAI today) opens a sign-in method choice: Browser sign-in (the ChatGPT authorize page opens; a localhost callback completes it), Device code (a code to type at the shown page), or Enter an API key. A ChatGPT sign-in reaches the models ChatGPT lists for the account with no API key, and the model pickers offer those, in ChatGPT's order; its result names the plan and warns when a Free or Go plan may not serve every model, and a model ChatGPT refuses names the plan and the options. An API key reaches the OpenAI API's models, billed per token; a sign-in's tokens are stored in ~/.kcode/auth.toml mode 0600 and refreshed automatically; a finished sign-in shows a toast with the result, and a failed one keeps the dialog up with the reason and Try again / Close; neither needs a session open; every other provider opens the masked API-key prompt directly (paste with ⌘V, saved to auth.toml); Plugins: first, under Drafts, the plugins a plugin wrote for you with kcode.plugins.stage, each marked awaiting review or can't install, Enter one for its detail: who wrote it and when, its kind, folder, permissions and events, what it replaces (your own plugin of its name, whose settings, secrets and switch stay), what needs your approval or why it can't install, a row per file with its size that opens the file in your editor, Install… (the install review: who wrote it, what it replaces, its files, permissions and events, and what needs your approval, whose approval installs the files you reviewed into your plugins folder; a draft rewritten since is refused) and Discard draft… (deletes its files after a confirm); then the installed-plugin inventory (built-in, user, project, and linked scopes: version, runtime kind, source path, permissions, declared events, loads once for the app on an app plugin, off/missing marks, a 1 tool not added mark in the warning colour on a plugin the focused session loaded without a tool, plus policy notices) with per-plugin management, Enter a row for its detail: an Enabled toggle (a disabled_plugins list entry, written to config.toml and applied at once: open sessions drop or gain the plugin's tools, hooks, commands, skills, agents and output styles, and the window its themes, an output style already in an open session's system prompt stays until that session restarts, and the row of a plugin that gives one says so), a settings form generated from the plugin's declared [settings] schema (each row named from its key, as max_lines_per_inject reads Max lines per inject, with the setting's whole description under it, and not set on the right while it has no value; booleans toggle and enums cycle in place; strings and numbers open a typed editor; other values persist under [plugins.<name>] and relay live the same way; a secret opens a masked prompt that saves it to ~/.kcode/auth.toml, its row shows only set or not set, and ⌫ removes a saved one), the source path, the declared permissions (a scoped one with the files or hosts it covers, fs.read (**/*.md) or fs.read (the whole project)) the hosts your [plugin_grants.<name>] net_http lets it fetch from, and the declared [events] table, what the plugin adds to the focused session (its tools, commands, skills, agent kinds, output styles and themes, then in the warning colour its files that did not load and each tool it went without and why, or that the session has not loaded it: left out for an app plugin, which adds nothing to a session), a per-plugin activity tail whose long lines wrap (the kcode.log record, plus load/unload markers and contained handler errors, polled from the focused session about once a second while the detail is open; an app plugin's comes from its one copy, with or without a session open, and reads "nothing recorded since kcode started" until it has some), and Remove (a managed plugin's folder is deleted from disk after a confirm modal; a linked plugin just clears its config entry: the folder is never touched; a built-in has no Remove, since kcode manages it). The list ends with "+ Add plugin from folder…": the in-app directory browser links any folder holding a plugin.toml (recorded as [plugin_links] <name>, loaded from where it lives and hot-reloaded in place, its commands, skills, agents, output styles and themes included; a link whose path stops existing rows as missing with a loud notice, never a silent skip). A plugin whose declared capabilities hit the install-review soft wall (a broad fs.write or one into a git folder, a private-network/loopback host, the input-transform / tool-gate intercept powers, replace-builtin, prompt, "sessions.open", exec, answer-waits, presence, "history.read", "history.read-all", "plugins.stage", "sessions.all" or jobs) does not install on the first click, a confirm modal lists the exact dangerous capabilities and only an explicit "Install anyway" records the link (ordinary plugins install without the prompt); Tools: one switch per tool of kcode's own, by name, each with the first sentence of what it does, turning one off writes it to disabled_tools and relays it to the daemon, so every session's next turn leaves it out (a plugin's or MCP server's tools are not listed; turn those off with their plugin); Theme designer: recolour every colour token of the active theme and save the result as your own theme, a 'Save as' name row, Save / Reset-to-base action rows, then grouped swatch + hex rows (Core, Diff, Effects, Syntax, click or Enter a row to open its editor, which drops a palette popover: three swatch rows (vivid hues, muted pastels, a neutral ramp) a swatch click live-applies it immediately while the picker stays open so you can try several, and the hex field beside it takes exact entry; Enter commits, Esc closes, an empty commit on a syntax hue resets it to the renderer's palette); every committed hex re-themes the whole window immediately (the app itself is the preview) without touching the active theme's name, Save writes a complete self-contained theme file to ~/.kcode/themes/<name>.ron (the theme watcher picks it up at once) and switches to it; bundled names (kcode-dark / kcode-light / kcode-high-contrast / kcode) can't be overwritten, and a refused or failed save says so on the Save row itself instead of silently doing nothing. Full coverage: after Providers, the sidebar carries one section per documented [section] config namespace, named by what it controls and listed by that name (Agent turns, Code search, Context compaction, File-change triggers, Logs, Worktrees, …), a data-driven registry derived from the same type list kcode config defaults documents, so a documented lib key has a row unless it is internal: a limit or guard that can break the app, lose data or remove a safety check (kvstore, session_history, the rate guards, the limits on plugins) works in config.toml but has no row. kcode's license, update and catalog-address settings are fixed in a release build: they have no row, and it ignores them in every file and the environment. A row is named from its key, its unit in brackets and an abbreviation in capitals (plugin_marketplace.cache_ttl_secs reads Cache TTL (seconds)); a byte count is named a size (tool_tests.output_bytes reads Output size) and shows in the largest of KiB, MiB, GiB or TiB that divides it (32 MiB), else as its byte count (10,000,000 bytes). A boolean renders an On/Off toggle; a key that takes one of a fixed set of words (permissions.default_mode) shows the current word, and a click, Enter or ←/→ moves to the next; any other scalar (integer, float, string) shows its current value and opens the typed text editor, where a size takes a count with or without a unit: 64 MiB, 512 KiB or 10 MB (KiB, MiB and GiB count in 1024s, KB, MB and GB in 1000s). A • marks a value that differs from its compiled default. These lib knobs are read once at daemon boot, so an edit writes ~/.kcode/config.toml and takes effect on the next daemon restart (the editor says so); there is no live relay for them. Also on ⌘, and the context menu's Settings action. Each control live-applies and persists (layout/grid to the daemon workspace; zoom + dirs to config.toml; keys to auth.toml). Provider keys live here (not on a session command) because one key serves every session (all-session config). Session-varying knobs (theme, model, effort, chat display gates) are session slash commands, not here. The whole page is keyboard-drivable, sidebar-primary: it opens on the sidebar in the Basic view (⌘1 / ⌘2 switch views and keep you on the same section where it has settings in both), where ↑/↓ move the section selection and → (or Enter) dives into that section's rows; in the rows, ↑/↓ move the highlight, → / Enter act on the selected control (adjust a stepper/cycle/toggle in place, or open its picker/dir editor), and ← either nudges a numeric stepper down or (on any other row) steps back out to the sidebar. (Tab is deliberately not a section switch: the GPU window's framework binds Tab to focus-cycling and consumes it before kcode sees it, so the sidebar owns section switching.) Esc closes the page. GPU build only.See /config #config | |
| /config | Alias for /settings: opens the same fullscreen settings page (⌘, / context menu Settings). GPU build only. Alias: /settings.See /settings #config | |
| Ways of working | ||
| /goal | [<objective> | clear] | Set a verifiable, per-session goal: the north-star that defines when the session is done. /goal <objective> sets it (the objective is the rest of the line as typed, line breaks kept): the goal persists on the session row (survives restart), shows as a mission line in the tile chrome, is baked into the agent's system prompt on each spawn/resume, and drives a kickoff turn where the agent confirms the goal, breaks it into verifiable sub-tasks, and starts executing them; images in the composer go with that kickoff turn. The kickoff and each nudge show in the chat as a one-line kcode notice that opens to the full text, never as your message, with the kickoff's images in a row of their own below it. From there the goal is self-driving: an implicit on-idle driver (the tile shows the looping marker) re-nudges the agent toward the goal whenever the session idles, until the agent declares an exit via <goal-status state="done"> inside <control-plane> (posted as a goal complete notification) or state="blocked" (a goal blocked needs-input notification), the no-progress guard trips (session_daemon.goal_driver_stall_turns consecutive toolless turns, default 3), the user presses Esc on a turn (the goal is kept, and the chat says so), or the goal is cleared. An agent-set goal (run_command goal) arms the same driver without a kickoff; the driver dies with the session and never re-arms on restart/resume: re-issue /goal to resume driving. Bare /goal shows the current goal; /goal clear or /goal reset removes it and disarms the driver: the word alone, in capitals or not, with or without a full stop after it, so a longer objective that starts with either word is set as the goal. GPU build only.See /effort /model /loop |
| /loop | [<every>] [<n>x] [instruction] | stop | Schedule recurring continuation turns for this session: kcode's autonomous-endurance driver. A leading cadence (/loop 10m wakes every 10 minutes), a repeat count (/loop 5x), an on-idle cadence (/loop 0s, or any bare instruction, fires on every idle), or any combination drives the agent; the rest of the line becomes the instruction run on each fire, line breaks kept (none = a plain continuation nudge that composes with /goal instead of repeating it). Each fire's instruction shows in the chat as your message; a plain nudge shows as a one-line kcode notice that opens to the full text, never as your message. Images in the composer go with the first fire only, so a recurring loop doesn't send them again. A count and a duration may lead in either order (/loop 5x 10m run the tests); the first non-cadence word begins the instruction, and a duration accepts h/m/s (1h30m) or bare seconds. A timer tick that lands mid-turn is deferred to the next idle, never interrupting work; <n>x caps the total fires, otherwise the loop runs until /loop stop or Esc on one of its turns: Esc stops an on-idle loop and says so, while an interval loop keeps its schedule and the chat says it is still on and that /loop stop ends it. /loop stop (or cancel, or off: the word alone, in capitals or not, with or without a full stop after it; a longer line that starts with one of them is an instruction) stops every loop the session has: this loop, the agent's set_timer timers (a saved one is deleted, so it doesn't come back when the session starts again) and the /goal driver, which keeps its goal; the reply names each one it stopped. While armed, an idle session reads looping: on its tile, in the status bar, in the switcher, in the sidebar, on its /debug card and in the /worktree list, and its dot in the switcher, /stats all and the /worktree list wears the working colour, as its tile glow does. The cadence syntax is shared with the agent's own set_timer tool (/loop is the user's front door to the scheduler, set_timer the agent's) so both read identically. GPU build only.See /goal |
| Plugins and skills | ||
| /plugins | List the session's loaded plugins (Lua, MCP, native) from ~/.kcode/plugins/<name>/plugin.toml (user scope), <project>/.kcode/plugins/<name>/plugin.toml (project scope), and .mcp.json MCP servers. Shows name, version, runtime kind, scope, and source path, and under its row a declared [events] table (events: watches …; intercepts …; provides …), its capabilities, a scoped one with the files or hosts it covers (fs.read (**/*.md), fs.read (the whole project), fs.write (nothing), net.http (public hosts, localhost)), the tools, commands, skills, agent kinds, output styles and themes it adds (tools: todo_count, commands: /greet, skills: /tidy, sweep (agent only), agent kinds: general, output styles: terse, themes: midnight), its files of those kinds that did not load (not loaded: commands/bad.md — /doctor says why), and each tool it went without because the name was taken (tool not added: todo_count — the user plugin hello has a tool by that name). A Failed to load section lists each plugin folder whose last load or reload failed, with the reason in full: a manifest that does not parse, a capability it uses but does not declare (with the line to add), a name another loaded plugin already has (with that plugin's folder), an installed plugin whose files changed after its install (turned off until you reinstall it). A Not connected section lists each MCP server that is not connected, with the reason, until it connects: one whose process would not start or whose address could not be reached when the session loaded it, one whose reconnect failed, and one that lost its connection and could not get it back. Each failed folder, each MCP server that is not connected, with its error, each tool a plugin or MCP server went without, with who holds the name, and each policy notice: a plugin the project's policy blocks, one it requires that is not installed, a policy file that could not be read, posts its own ⚠ Plugin problem notification for the session, led by the plugin or file it is about, when the session starts and whenever a later load adds one; a reload that changes nothing posts nothing. Reads live state: adding or editing a plugin under a plugin dir loads it into the running session, its commands and skills included, and shows here. kcode plugins list prints the same local state from the CLI (no session needed); kcode plugins scaffold/validate are the authoring path (emit a working skeleton, pre-flight it with the same checks a session load runs); kcode plugins install <folder> and kcode plugins remove link and remove plugins as Settings › Plugins does. A plugin can also replace a built-in tool: list the built-in's name under shadows = [...] in its plugin.toml and give a tool the same name; the plugin tool goes live, the original stays reachable as builtin:<name>, and removing the plugin restores it. A plugin tool on one of kcode's tool names without shadows is left out when the plugin loads, with the reason in the plugin's activity, and the rest of the plugin still loads, even when the session doesn't offer that tool (web_search with no search key, advisor with no advisor model), so a plugin loads the same way in every session, and kcode plugins validate fails it the same way. No tool may take submit_result, even with shadows: a turn with an output schema answers through kcode's own tool by that name. Two plugins that add a tool by the same name: the one loaded first keeps it, and the other loads without it. Shadowing a safety-critical built-in (bash and the shell_* tools, fs_write/fs_edit/apply_patch, run_tests/test_cancel) additionally needs the replace-builtin capability plus project trust and the install soft-wall approve. The permission check judges a replacement by what it declares, as it judges every plugin tool, never as the built-in: one declared read-only runs without a prompt unless its arguments name a secret location, any other follows the session's mode, and the rules written for the built-in (url(…), bash(…), path(…)) don't reach it, while a tool(<name>) rule does.See #plugins | |
| /skills | List the loaded skills. There are no built-in skills (the four prompt routines are commands), so this is the user/project markdown skills from ~/.kcode/skills and <project>/.kcode/skills plus any plugin bundle's skills/: the session's own project's, once you trust it, and never another project's. Run any of them as /<name>: the run is prepared as the agent's run_skill prepares it, the core.skill.* points, the lock, the state home, the tool lists (allowed-tools, disallowed-tools) and the ${KCODE_SKILL_STATE}, ${KCODE_SKILL_DIR} and ${KCODE_SESSION_ID} placeholders, and the skill's guide becomes the agent prompt, with $ARGUMENTS (the text you type after the name, line breaks and spacing kept) and $1,$2,… (its words; $10 is the tenth, and a $ you type stays as typed) substituted in. A value in quotes is one word (/compare "main branch" topic), the highest-numbered placeholder also takes the words after its own, and a placeholder past the words you typed is left empty: opencode's rules. A body with neither gets your text as a new paragraph after it. A skill with typed inputs (an input_schema, or a script) reads the text after its name as a JSON object of them instead (/explain {"path": "src/main.rs"}; no text is {}), and a script skill runs its code before the turn, whose prompt carries the result. The prompt ends with what the skill's tool lists do for the turn: see run_skill. A skill marked user-invocable: false is the agent's only. A typed /name finds a skill in any case, so /deploy runs a skill named Deploy, and two skills whose names differ only in case are one name: the first to load is kept, as with two of the same name. kcode's own commands come before every skill, also in any case, so a skill named Compact never runs. /doctor names a skill of yours that another skill or one of kcode's own commands hides (content.hidden). A skill's argument-hint (what the text after its name should be) shows after its name here, in the / menu and in the palette, and a skill with one waits for its text: picked with Enter from the / menu, or from the palette, it fills /<name> into the composer instead of running. The daemon answers it from the skills it holds, the same set the agent's run_skill reads; never sent to the agent. Images pasted or dropped into the composer go with a /<name> run, as with a typed prompt, and a /<name> in a stopped session resumes it. A skill's model (a models.dev id or name, or Claude Code's opus, sonnet or haiku for the newest Claude model of that family; inherit or none is the session's) is the model of the turn its /<name> starts: that turn only, when a connected provider serves it; otherwise the chat says why and the turn runs on the session's model. The agent's run_skill can't switch models mid-turn, so its result only names it. Loaded skills also appear in the / slash menu and the Cmd-P command palette (tagged skill); a skill file or directory symlinked into a skills dir is followed. A skill whose name is not one plain folder name (empty, ., .., or holding a /) is not loaded, and /doctor names its file; nor is one whose name holds a space or a /, which a typed /name could never reach, and /doctor says why. GPU build only.See /init /plugins /agents /commands | |
| /commands | List the markdown commands. They are the built-in prompt routines (/commit, /init, /review, /security-review) plus the user-authored commands loaded from command_dirs (~/.kcode/commands and <project>/.kcode/commands by default) and any plugin bundle's commands/: the session's own project's, once you trust it, and never another project's. Run any as /<name>: the command's markdown body becomes the agent prompt, with $ARGUMENTS (the text you typed after the name, line breaks and spacing kept) and $1,$2,… (its words; $10 is the tenth, and a $ you type stays as typed) substituted in. A value in quotes is one word (/compare "main branch" topic), the highest-numbered placeholder also takes the words after its own, and a placeholder past the words you typed is left empty: opencode's rules. A body with neither gets your text as a new paragraph after it, so /review src/auth.rs keeps the path. A user command wins a name collision with a built-in (first-registration-wins; the built-ins load last), so your own commit.md overrides /commit. A typed /name finds a command in any case, so two commands whose names differ only in case are one name: the first to load is kept, as with two of the same name. A skill of the same name runs before a command, and kcode's own commands before both; /doctor names a command of yours that another command, a skill or one of kcode's own commands hides (content.hidden). A command's frontmatter may set argument-hint, what the text after its name should be, as a skill's does: it shows after the name here, in the / menu and in the palette, and a command with one waits for its text, picked with Enter from the / menu, or from the palette, it fills /<name> into the composer instead of running. A command's allowed-tools and disallowed-tools work as a skill's do (see run_skill), whether you type /<name> or the agent runs it through run_command: for the turn that runs the command, allowed-tools approves the calls its entries cover once you accept them, the first run of a list that is new or lists more shows a prompt, and a project command you trusted as it stands counts as accepted, and disallowed-tools refuses the calls its entries claim, hiding a tool an entry names whole. The model reads what the lists did in a note after the command's prompt; an entry kcode can't read approves or removes nothing, and /doctor names the command's file and list (command.tool-list). Before, kcode did not read either list. The daemon answers it from the commands it holds, the same set the agent's run_command reads; never sent to the agent. Images pasted or dropped into the composer go with a /<name> run. A command's model works as a skill's does: the turn its /<name> starts runs on it when a connected provider serves it, else on the session's model with a note saying why. Adding or editing a command file takes effect live (a file-watcher repopulates the registry: no restart). Loaded commands also appear in the / slash menu and the Cmd-P command palette (tagged cmd); a command file symlinked into a commands dir is followed. A command whose name is empty, holds a space or a / (from its frontmatter name:, its file name or a folder it sits in) is not loaded, because a typed /name could never reach it, and /doctor names its file and says why. GPU build only.See /skills | |