OKLMdocumentation v1.0.3
On this page

Slash commands and the terminal UI

What the user of oklm agent types and sees: the slash commands and the full-screen terminal UI. Part of the agent harness (harness.md); every command is listed in commands.md.

Status: implemented.

Slash commands

include/oklm/harness/commands.h, src/harness/commands.c: one registry for OKLM's built-ins and the prompt commands, which are skills.

  • Built-ins: /clear [name] (/reset, /new), /compact [focus], /context, /rewind (/checkpoint, /undo), /export [file], /mode [mode], /plan, /add-dir <dir>, /output-style [style], /theme [theme], /config (/settings), /permissions (/allowed-tools), /init, /memory [N], /tasks [stop N | output N | reap] (/jobs, /bashes), /thinking, /verbose, /help, /skills [NAME [on|menu-only|model-only|off]], /reload-skills, /hooks [reload], /agents, /todos, /btw [question], /copy [N] [file], /recap, /rename [name], /branch [name], /resume [session], /continue, /autocompact [on|off|auto|TOKENS], /autocontinue [on|off|N], /goal [condition|clear], /model [N|PATH|NAME] [s], /effort [low|medium|high|max|auto|status] (sets or removes the template variable enable_thinking alone, those given with --template-vars kept: oklm_agent_set_template_var()), /sandbox [on|off], /cd <dir>, /import [claude|agent] [--dry-run], /skill-doctor, /statusline [command|clear], /color [color|default], /exit (/quit). /help lists them by source with their arguments and aliases.
  • Project and context: /cd DIR moves the session, its conversation kept: the folder's trust asked on a terminal, the rules read from its settings files (this session's own rules, added directories and mode kept), the sandbox's writable places, its settings, memory files, git snapshot (oklm_agent_set_project()) and skills read there, background jobs started there from then on, the model told in a note. /import copies .claude/ (or .agent/) commands, agents and skills into .oklm/, never over a file there (--dry-run lists them). /skill-doctor gives each skill's tokens in the prompt and its uses in the project's transcripts (Skill calls, /name typed), pointing at those never used. /statusline COMMAND sets statusLine.command in the user's settings (clear goes back to the built-in one). /color colors the prompt for the session, over ui.promptColor.
  • Scheduled tasks: /schedule WHEN PROMPT (/routines) adds a line to the user's crontab that runs .oklm/schedule/N.sh: oklm agent -p with the options of the session that scheduled it (less -p, the output formats, --resume, --api-key: OKLM_API_KEY serves), from the same directory, the prompt read from N.prompt, each run's output in .oklm/schedule/N/DATE-PID.log. WHEN is hourly, daily HH:MM, weekdays HH:MM, weekly DAY HH:MM, every Nm, every Nh or cron "M H DOM MON DOW". The run is unattended: tools that need approval are refused unless the project's settings allow them. /schedule lists the project's tasks with their last run; remove N, run N (now, as a background job), log N (the last run's output). Lines are marked # oklm-schedule:PROJECT:N, so other entries are left alone. Needs cron (no systemd timers, launchd or Task Scheduler yet): schedule.backend set to systemd, launchd or taskscheduler makes /schedule say so and do nothing, rather than write a crontab line the user did not ask for.
  • Background sessions: /background [request] (/bg) hands this conversation to a process of its own, oklm agent with this session's options and permission mode resuming the session with the request (by default: go on with the task on your own and report), detached from the terminal so it outlives this one; a new conversation starts here. /fork REQUEST leaves the conversation here (in a new session) and sends the session as it was to the background with the request. Each one has .oklm/background/ID.json (its process, request, options), ID.log (its output) and ID.inbox. oklm agent agents lists them, running or finished; oklm agent send ID MESSAGE appends to its inbox, which the session reads every 300 ms: while it works the message steers it at the end of the model's turn, after its request it is a turn of its own. oklm agent attach ID prints the transcript as it grows, sends each line typed, and once the session ends goes on with it here (oklm agent --resume with its options); Ctrl-C leaves it running. oklm agent stop ID ends it. /tasks counts the ones running. Being unattended, they cannot ask: what needs approval is refused unless the mode or the rules allow it. Not on Windows yet.
  • The reference: oklm agent commands [--markdown] prints every command from the registry: the built-in commands, the built-in prompt commands (and who may start them), the commands left out and those not built yet; commands.md is its Markdown, generated. A command left out (an account's, billing's or a cloud's, or removed upstream: /login, /upgrade, /ultraplan...) says so when typed. The prompt commands also include /debug (reproduce, narrow down with evidence, prove, fix with a test) and /deep-research (sub-questions researched by sub-agents in the code, the documents and the history, a cited report; no web search).
  • Diagnostics: /status prints the version, the model, the project and its trust, the session, the mode and the sandbox, the settings files present, the memory files, the skills, what runs (jobs, background agents) and the language servers. /usage (/cost) gives the conversation's turns and tokens as its transcript records them, and the session's from the usage events (cached tokens included) with the time since it started; /usage stats adds the project's sessions, tokens a day and the tools most used from the audit logs. /doctor (/checkup) lists errors and warnings: settings files that are not JSON objects, keys of the wrong type (left out) and unknown keys, the skills' and the memory files' problems, git missing, no sandbox, orphaned processes, a status line or hook command not found; /doctor fix removes the keys of the wrong type and stops the orphans; /doctor prompt-audit has the model review the memory files and skills for conflicts and bloat, changing nothing.
  • Context size: /context-size (alias /ctx) prints the context's size and what the model takes; /context-size N makes a context of N tokens for the same loaded model, from 2048 (the agent's instructions and tools need room) to 1 048 576, anything above the context the model was trained with coming with a warning in red. The conversation is kept and evaluated again on the next turn. A size the memory plan says does not fit is warned of in red and not made unless force follows (/context-size 65536 force). With a model on a server (--url) the command asks the server (GET and POST /api/context) and prints its refusal or warning (models.md).
  • Model and behavior: /model is the selection of oklm chat (inference.md): the catalogue's models under their groups' names, each with its size, its state and its description, those no chat serves dimmed, then under "Other files" the models found elsewhere (the models setting, the GGUF files under ./models, $OKLM_MODELS and the model directory). It is a panel in the full-screen UI (arrows, Enter, typing searches, Esc) and a numbered list with a question in line mode; a model that is not installed is downloaded only once the selection asked, naming its size and its licence. /model NAME, /model N (a number of the list) and /model PATH choose without the list. The model is loaded with the session's options and handed to the agent (oklm_agent_set_model(): its template, tool-call format and grammar; the conversation evaluated again, which the message says), and saved as the model setting unless s follows. Without a terminal (-p) the list is printed and nothing is asked or downloaded. With --url the model is the server's: /model NAME sends the name, and /model alone offers the models the server lists (GET /v1/models); when the server lists one model, or none, the agent says that the model cannot be changed from where it is. /effort low turns the reasoning off where the template allows it (enable_thinking, through oklm_agent_set_template_var(), the other variables kept), the other levels on; with --url the variables reach the server's template as chat_template_kwargs. /sandbox on|off confines commands or not for the session. /plan TEXT enters plan mode and starts planning. /config KEY=VALUE ... sets keys (also with -p), /config --help lists them. Built-in prompt commands: /update-config (the model edits the right settings file), /fewer-permission-prompts (rules proposed from the audit logs' asked calls).
  • The session's commands: /clear NAME names the conversation left behind (for /resume). /btw asks the model a side question after the conversation, its cache reused, nothing added to the history (/btw alone lists the side questions and their answers). /copy puts the Nth latest answer, its reasoning dropped, in the clipboard (wl-copy, xclip, xsel, pbcopy, clip, else the terminal's OSC 52, which works over SSH), or in a file. /recap is the session in a sentence, asked aside. /rename names the session in the lists (a title line in its transcript; without a name the model writes one). /branch copies the conversation into a new session and goes on there, the original kept for /resume, which switches to another session in place (picked, or by id). /autocompact 24k sets when the conversation is compacted by itself (auto: the default share), saved as compactThreshold in the user's settings; /autocompact off leaves compaction to /compact and on gives it back (autoCompact). /continue goes on with the last answer when the token limit or the context cut it (it was an alias of /resume before 2026-11-16; the start option that reopens the last session is oklm agent --resume); /autocontinue off leaves that to /continue, on gives it back, and /autocontinue 3 sets the pieces in a row at most (autoContinue, continueMax; agent-sessions.md). /goal CONDITION starts working toward it; after each turn the model is asked aside whether it is met, and a new turn starts until it says yes or goal.maxIterations (10) turns have passed; /goal clear forgets it. tools/check_commands.sh types them into the prompt with a fixture model.
  • Prompt commands: each skill (.oklm/skills/NAME/SKILL.md) and each file of .oklm/commands/ (sub-directories as namespaces: .oklm/commands/git/state.md is /git:state), the project's then the user's (~/.config/oklm/skills, ~/.config/oklm/commands; the commands directories are skipped with commands.legacyDirs false). The header takes name, description, argument-hint, allowed-tools (rules allowed while the command runs: its ! commands, then its turn), disable-model-invocation, user-invocable, model (read, not acted on) and context (§ Skills). The body is expanded in one pass: !`cmd` runs through Bash and its permissions (10 s, 10000 bytes) and its output takes its place; @path is inlined (a project file, read through Read); $ARGUMENTS and $0, $1... (words split as a shell does, quotes kept together) are substituted; without any placeholder the arguments follow as ARGUMENTS: ....
  • Parsing: a command only at a message's start; names case aside; //text or /text sends text starting with a slash; up to commands.maxStack (6) prompt commands stack, /review /fix the parser sending both with the same arguments (a built-in cannot be stacked); an unknown name is answered Unknown command: /clera (did you mean /clear?) and never sent; without a terminal, a command that needs one says so.
  • Precedence: built-in, project, user. A name taken already is kept under its source: a project skill clear is /project:clear, a user command fix hidden by the project's is /user:fix; /help marks the commands that hide another.
  • While the agent works, a command typed with Enter runs at once when it only reads (/context, /tasks, /help, /thinking, /verbose) or changes what the next tool call sees (/permissions, /mode, /plan, /add-dir, /theme); the others wait for the turn's end ((queued: /compact, after this turn), then (running /compact)). Prompt commands are expanded and sent to the agent like any line typed meanwhile.
  • -p "/cmd" runs the command; a prompt command is sent expanded; an unknown one, or one that needs a terminal, fails with status 1.
  • The menu: / opens it under the prompt; letters filter by prefix, word start, or with the separators dropped (/adddir finds /add-dir, /new finds /clear by its alias); the first row is highlighted on a real match only (a typo lists close names, highlighted none; a lone / none), Up / Down move, Tab completes the name, Enter runs the row chosen. Hidden commands show only once typed whole. Each row shows the name, the arguments, the description and [project] or [user]. After the name, Tab completes the argument from the values it takes (/mode acc gives acceptEdits) or as a directory (/add-dir).
  • The picker (oklm_picker in term.h): a list filtered as one types, Up / Down, a number, Enter, Esc; a numbered list read from the input without a terminal. /rewind, /mode, /theme and /output-style (without an argument) use it.
  • Visibility: skillOverrides ({"name": "on" | "menu-only" | "model-only" | "off"}) hides a skill from the menu, from the model, or both; /skills NAME VALUE sets it in .oklm/settings.local.json. A skill with disable-model-invocation: true is not listed to the model nor loaded by Skill; user-invocable: false keeps it out of the menu. /skills lists each skill's visibility, source, kind and tokens in the prompt, what shadows it, the total listed and what is past the budget, and the problems found; /skills NAME shows one (its file, description, arguments, allowed rules, whether it is listed).

tests/harness/test_commands.c: the parser (start of a message, escapes, case, aliases, namespaces, stacking and its limit, an argument starting with a slash, a built-in stacked, unknown names with and without suggestions, a model-only skill), precedence and shadowing, overrides, the menu table (adddir, new, cl, comp, component, frontendcomp, a typo, nonsense, a hidden command partly and wholly typed, a model-only skill, nothing typed), submitting (at once, queued while busy, immediate, taken in order, refused without a terminal, unknown, /quit, //), the allowed tools given and taken back and covering a ! command, the expansion ($0 $1 with quotes, $ARGUMENTS, arguments appended or not, ! run, ! refused, @ inlined, a missing @ kept, the header dropped, an output cut), a /permissions deny typed mid-turn refusing the next call, and a command file with ! and @ reaching the model expanded. Checked by hand on a pseudo-terminal: the menu (/ad, Down, Tab), /mode acc Tab, the /mode picker, /clera, a prompt command from the menu, /tasks run mid-turn and /compact queued then run; with -p: /help, /git:state the release expanded (@notes.txt inlined), /hepl, /rewind refused.

Terminal UI

The rendering lives in the library, apart from the terminal, so it is tested frame by frame (include/oklm/harness/term.h, term_md.c, term_ui.c); apps/oklm.c writes it.

  • Markdown as it streams (terminals only; a pipe gets the raw text): paragraphs, headings, list items (nested, task boxes ☐ ☒) and quotes stream, their emphasis, code spans and links styled as they close; code blocks go a line at a time, indented, fences hidden, the syntax colored (C-like languages, Python, shells, JSON / YAML / TOML, diffs); tables are held until they end, then aligned with their header bold (written as they came when wider than the terminal); rules span the width. Escape sequences and control characters in the model's text are dropped, so it cannot drive the terminal.
  • Tool calls compactly: ● Read(src/main.c) (green, red when it failed, yellow when refused), then ⎿ Read 120 lines, ⎿ Wrote 12 lines to a.c, ⎿ Updated a.c with 2 additions and 1 removal and the diff (12 lines), a command's first three lines with … +N lines, the task list with ☐ ◼ ☒. Ctrl-R while the model works, or /verbose (which shows the last call again), switches to whole outputs.
  • Spinner: ✻ Pondering… (12s · ↓ 340 tokens · esc to interrupt), redrawn every 120 ms by a thread sharing a lock with the agent's callbacks, at a line's start only (before the first word, between calls); its verb is the task in progress (activeForm) when there is one; while a reasoning block is folded it counts the block's words.
  • Status line before each prompt: the model, the mode, the context used (context 36% (3.0k/8.2k)), the git branch (read from .git/HEAD, worktrees too) with its marks (⎇ main ↑2 ↓1 *: commits ahead of and behind the upstream, files changed or untracked; from one git --no-optional-locks status --porcelain=v2 --branch, oklm_git_read_marks(), read again only after a line is submitted or a ! command runs, never on a redraw), the jobs running; or the first line printed by the statusLine.command setting, which gets the session as JSON on its standard input (session_id, cwd, model.display_name, workspace, permission_mode, output_style.name, git.branch, git.ahead / behind (null without an upstream) / dirty, context.used / window / percent, jobs.running, version), 2 s at most.
  • The prompt (include/oklm/harness/line_edit.h, on a terminal; Windows keeps its console's own editing): Left / Right, Home / End, word moves, Backspace / Delete, Ctrl-U / Ctrl-K / Ctrl-W, the history with Up / Down and Ctrl-R (searched back; Ctrl-R again for older, Ctrl-G or Esc back, Enter sends, another key keeps the line found). Several lines: a backslash before Enter, Alt-Enter, or Shift-Enter where the terminal tells it; drawn on as many rows as they take, long ones wrapped. Pastes come bracketed: three lines or more, or more than 800 bytes, show as [Pasted text #1 +42 lines] (Backspace removes it whole) and are sent whole. /vim [on|off] (also /vi) switches between vi and Emacs line-editing keys, without an argument to the other of the two; editorMode in the settings chooses the one a session starts with. Ctrl-L clears the screen. Ctrl-T prints the task list inline: at the prompt it runs /todos (the line typed comes back after), while the model works it prints Tasks, 1 of 3 done; now: Running the tests: and the list.
  • Full-screen UI (/tui, or ui.viewMode fullscreen; POSIX): the transcript, the status bar and the input drawn by oklm_tui_render() (include/oklm/harness/tui.h). The task list stays on screen above the transcript while one exists and the terminal has 16 rows or more (Ctrl-T hides it, and shows it again, on a shorter terminal too): Tasks 2/5 done, then ☒ completed (beyond three, the earlier ones fold into ☒ N more completed), ◼ the task in progress by its activeForm, ☐ pending; at most a third of the rows, scrolled to keep the task in progress in sight with ... N above, M below. It follows each TodoWrite while the model works. /tasks there opens a panel of the jobs (commands, services, monitors, language and MCP servers) and the background agents, refreshed four times a second: a row each with its state, run time, kind and label, its last line under it when there is room. Up / Down (Ctrl-P / Ctrl-N) select; Enter follows the job's output in a pager (its last 500 lines, then what it writes; Up / Down / Page Up / Page Down scroll, End follows again, Esc or q back); s stops it (ProcessStop's stop command and grace), r starts it again (a service through its declaration and readiness, a job with a restart policy with its own command, oklm_jobs_restart()), k keeps it running past the session (oklm_jobs_keep_one(), the exit question's "keep" for one job); what an action did shows at the panel's foot, and a key a row does not allow says why. q, Esc or Ctrl-C closes it. Typed while the model works, /tasks stays text. /config there opens the settings panel (oklm_tui_settings_open()): the settings in force from oklm_settings_list(), a row each as KEY = VALUE with its source under it, then the known scalar keys no source sets (not set: the default). Up / Down, Page Up / Down, Home and End select, letters filter, Enter edits the value in the input area (a string without its quotes), Enter again picks the scope (Left / Right or l, p, u: local, project, user) and Enter saves: oklm_tui_settings_key() returns SAVE, the value read as /config set reads it, checked by oklm_settings_check() (the load's table of key types and member values: a refused value is not written, the reason shown), written to that scope's file, the settings read again and applied as /config set applies them; the rows refresh with the selection kept, and the foot says what was written where. An empty value removes the key from the chosen file. Esc steps back, and closes the list. Typed while the model works, or outside the full-screen UI, /config stays text. While a turn runs, a progress row above the status bar (oklm_tui_progress_set()) says what it does: writing: N tokens, R tok/s, T (the pieces of the current model turn, counted since it began) or running TOOL: T, then the status's background jobs running and its context use (context 12% (3.9k of 32.8k)); the agent's events set the activity (TOOL_CALL, TOOL_RESULT), the paint computes the time and speed. The reasoning follows the view (Ctrl-O switches it at the prompt too): in the classic view a block shows as its [thought, N words] line once it ends (the transcript cannot take a line back, so no live Thinking line), in the full view as it is written. A message over several lines (Alt-Enter, or a backslash before Enter) grows the input to six rows, then scrolls it to keep the cursor in sight. What the status bar and the task strip show comes from the program running in the UI through oklm_tui_host (oklm_tui_refresh()): the agent gives its session, mode, branch, jobs and task list; oklm chat --tui gives its model, context use and speed (inference.md).
  • Prefixes: @path names a file: Tab completes it (a prefix, then a name holding what was typed, then its characters in order; hidden entries, .git, node_modules and build left out), and on sending, each file named is read (through Read and its rules) and given to the model with the message. !command runs a command as the user's own (no question, the sandbox and limits applying, the audit log saying user), shows its output and gives it to the model with the next message. #note saves a note to a memory file (§ Memory files).
  • Notifications: the terminal's bell when a question waits and when a turn of more than 20 s ends; preferredNotifChannel: terminal_bell (the default), iterm2 (an OSC 9 message), system (a desktop notification: notify-send on Linux, osascript on macOS, a toast on Windows through Windows PowerShell and Windows.UI.Notifications, nothing to install (oklm_notify_toast_command(): the script passed with -EncodedCommand, under PowerShell's application id; without PowerShell, MessageBeep; cross-compiled, untested on Windows); the bell when none is available), notifications_disabled.
  • Themes: theme dark (the default), light, colorblind (blue and orange in place of green and red; dark-daltonized and light-daltonized read as it), none. NO_COLOR set, or output that is not a terminal, means no colors. The width is read at each drawing, so a resized terminal is followed.
  • Welcome and trust: the first interactive run in a folder asks whether its files are trusted (the agent reads them, follows their instructions, runs commands there); the answer is kept in the user's trusted-folders.json (a folder trusted covers those under it); no leaves. It is asked before any of the folder's files is read: before its settings, and with --worktree before the worktree is made (a WorktreeCreate hook comes from those settings). Then a box with the folder, the model, the mode, how commands are confined, the session, and the tips. -p asks nothing.

tests/harness/test_term.c holds the frames: a Markdown document plain and in the dark theme, the same fed whole or a byte at a time; tables, too wide; code blocks by language, a block comment across lines, a diff, a fence never closed; escape sequences (CSI and OSC) dropped; a paragraph streaming before its line ends, a table waiting for its end; the tool lines (Read, Edit's diff, Bash shortened and whole, Write, the task list, a refusal, an error in color, a long command cut); the spinner; the status JSON, the built-in line, a command's; the folders trusted; the completion's order; the branch, from a sub-directory and a worktree. tests/harness/test_line_edit.c: new lines, the layout of several lines and of a wrapped one, Ctrl-R, pastes and their placeholders, Tab, Ctrl-L and Ctrl-T. tests/harness/test_tui.c plays the full-screen frames on a screen of cells and checks rows: the task strip at 24 x 80 and 50 x 120 (the fold, the marks, the activeForm), hidden on 12 rows and shown by Ctrl-T, scrolled on a list of 30, following two TodoWrite calls; the /tasks panel at 24 x 80 and 10 x 60, its keys against a fake job manager (stop, restart, keep called for the selected job, refusals noted, the pager following and scrolling, Esc back, q closing); a host filling the status bar (a chat's: the model, the context, the speed, no mode) and the task strip; a message over three and ten lines, the cursor after a newline and at a full row. tools/check_commands.sh drives both UIs on a pseudo-terminal (script): the strip after a TodoWrite, the panel stopping a job and following its output, Ctrl-T in the line-mode UI. Checked by hand on a pseudo-terminal (100 columns), with the scripted backend: the trust question, the welcome box (a long folder shown by its end), @RE Tab completing @README.md and the file read, a heading, a table and a C block rendered while streaming, ● Read and ● Edit with its diff, the bell before the question, the spinner, !echo, Ctrl-R finding the earlier line and Ctrl-G restoring, a line of two rows, /verbose; piped (-p), the raw Markdown and plain tool lines; and with Qwen3-4B (8192 tokens, reasoning on): the folded reasoning counted, the model's Markdown table aligned, the edit's diff, context 36% in the status line.