The OKLM agent: user guide
How to use oklm agent, the coding agent of OKLM, day to
day. Each section points to the page with the details: harness.md for how it works, commands.md for every command, processes.md for background work and
integrations.
Status: maintained.
Starting
oklm agent -m models/qwen3-4b/Qwen3-4B-Q4_K_M.gguf # a local model, in the process
oklm agent --url http://127.0.0.1:8080 --remote-model NAME # an OpenAI-compatible server
oklm agent -m MODEL -p "fix the failing test" # one request, then exit
oklm agent --resume [SESSION] # go on with the last session, or the one named
oklm agent sessions | sessions export ID | sessions rm ID # the project's sessions: listed, written out, removed
oklm agent --worktree feature-x # work in a git worktree of its ownThe first run in a folder asks whether you trust it: the agent reads
its files, follows the instructions in them and runs commands there. The
project is the current directory (--project DIR to change
it).
tools/oklm_agent starts the agent in the current
directory with a model of its own: put it, or a link to it, in a
directory of your PATH
(ln -s /path/to/OKLM/tools/oklm_agent ~/.local/bin/).
oklm_agent # the first time in a folder: pick a model (or a server URL), saved for that folder
oklm_agent # later: starts with it at once; other arguments go to oklm agent
oklm_agent --choose-model # pick again
oklm_agent --show-model # print the folder's modelIt lists the GGUF models with a chat template found under
$OKLM_MODELS (directories separated by :),
~/.local/share/oklm/models and the OKLM tree's
models/, the default model (Qwen3-8B Q4_K_M) first, and
saves the choice as model (baseUrl for a
server) in .oklm/settings.local.json, which
oklm agent reads itself: in that folder
oklm agent alone uses it too. It finds oklm
through $OKLM_BIN, the PATH, then the tree's
build.
Talking to it
Type a request. @path attaches a file (Tab completes),
@server:uri an MCP server's resource; !command
runs a command yourself; #note saves a note to the memory;
/ opens the commands' menu. Esc or Ctrl-C interrupts, at
any moment of a turn (while the prompt is read, the model writes or a
tool runs), Esc Esc rewinds, Shift+Tab cycles the permission mode,
Ctrl-R shows tool output whole, Ctrl-B sends a running command to the
background. Ctrl-O (or /thinking) switches between the
classic view, where a thinking model's reasoning is one "Thinking" line
with its word count, and the full view, where it is shown as it is
written; --thinking show starts in the full view (the
ui.viewMode setting: classic,
full, or fullscreen for the full-screen UI of
/tui; ui.promptColor colors the prompt). A
message typed while the agent works steers it. Ctrl-T prints the task
list the agent keeps (/todos).
In the full-screen UI (/tui) the task list stays on
screen above the transcript, updated as the agent works: ☒ done (the
older ones folded into one line), ◼ what is being done now, ☐ to do. It
shows when the terminal has 16 rows or more; Ctrl-T hides it or shows
it. /tasks there opens a panel of the background jobs and
agents (state, run time, last line):
| Key | In the /tasks panel |
|---|---|
| Up / Down (Ctrl-P / Ctrl-N) | select a job |
| Enter | follow its output live (Up, Down, Page Up, Page Down scroll; End
follows again; Esc or q back) |
s |
stop it (its stop command, then the grace before it is killed) |
r |
restart it (a service, or a job with a restart policy) |
k |
keep it running when the session ends |
q, Esc |
close the panel |
/config there opens a panel of the settings in force,
each with the file or source it comes from, then the known keys no file
sets:
| Key | In the /config panel |
|---|---|
| Up / Down (Ctrl-P / Ctrl-N), Page Up / Down, Home, End | select a setting |
| letters | filter the keys (Backspace takes one off) |
| Enter | edit the selected value in the input (a string without its quotes;
JSON otherwise, as /config set reads it) |
| Enter again | choose where to save it: Left / Right or l,
p, u for local, project or user, then Enter
saves (a value of the wrong type is refused with what the key takes; an
empty value removes the key from that file) |
| Esc | one step back; in the list, close the panel |
While the agent works, a row above the status bar shows what it is
doing: writing: 120 tokens, 45.6 tok/s, 12.3s while the
model writes, running Bash: 3.4s while a tool runs, then
the background jobs running and the context's use.
The context's length is 32768 tokens (the model's training length
when that is shorter); -c N sets another for a run, and
oklm agent config set contextWindow N keeps it for the
folder (--scope user for every folder). A larger context
takes more memory for its cache: Qwen3-8B needs about 144 KB a token
with the default F16 cache (-ctk q8_0 -ctv q8_0 halves it),
so 40960 tokens, its training length, take about 5.6 GB beside its 4.7
GB of weights. On a 20 GB GPU Qwen3-8B Q4_K_M reads a 27,500-token
prompt at 339 tokens/s (13,700 tokens at 500/s) and writes 24 tokens/s
at that depth.
Permissions
Four modes: default (edits and commands ask),
acceptEdits (edits in the project run, commands ask),
plan (reads only, until a plan is accepted) and
bypassPermissions (only inside the sandbox). Rules in
the settings decide calls without asking: Bash(make test),
Bash(git add:*), Edit(src/**),
WebFetch(domain:docs.python.org), mcp__github,
Service(web). Some calls always ask whatever the rules:
deleting a tree, force-pushing, git reset --hard,
publishing, a Kubernetes context that is not local, a phone over adb,
cloud changes, tunnels (they say what they expose), container cleanup.
Commands run in a sandbox by default (no writes outside the project, no
network: /sandbox network on allows it all;
"sandbox": {"allowedDomains": ["github.com", "*.npmjs.org"]}
lets commands reach only those, through a proxy that tools such as curl,
pip, npm and git use). Answer "always" to save a rule.
/permissions shows them; every decision is in the audit log
(oklm audit).
The project's memory
AGENTS.md (and CLAUDE.md, the user's and
the managed ones) are read at the start: the project's conventions,
commands, warnings. /init writes one; #note
adds to it; /memory edits them.
Settings
.oklm/settings.json (the team's),
.oklm/settings.local.json (yours, not committed),
~/.config/oklm/settings.json (all projects), a managed file
on top. /config edits them, /config KEY=VALUE
sets one, and outside a session
oklm agent config get|set|unset KEY [VALUE] [--scope local|project|user]
does the same (get gives the value in force, or with
--scope only that file's); /doctor finds what
is wrong and /doctor fix repairs what it can;
/status says what the session runs with.
Sessions
Every conversation is a session kept in .oklm/sessions:
/resume picks one, /rename names it,
/branch forks it, /rewind goes back (the
conversation, the files, or both), /export saves it,
/compact frees the context, /clear starts
over. /background hands the conversation to a process of
its own and oklm agent attach ID follows it;
/fork sends a copy off with a request.
Skills and commands
Skills are instructions the model loads when a task matches their
description; prompt commands are the ones you type. Built in:
/commit, /pr, /code-review,
/security-review, /simplify,
/batch, /bisect, /autofix-pr,
/run, /verify, /debug,
/deep-research, and skills for git history, Docker, dev
servers, databases, Playwright, Kubernetes, Android, VMs, clouds and
tunnels. /skills lists them all; extending.md tells how to write your own.
Sub-agents
The model can start sub-agents for searches and side tasks (in the
foreground, or in the background with their reports coming later), with
types you define in .oklm/agents/ (/agents).
isolation: "worktree" gives one a git worktree and branch
of its own; /batch splits a large change across
several.
Git
The agent knows the repository's state, commits only when asked, in
the repository's style, staging files by name, blocking secrets; asks
before touching a protected branch or rewriting pushed history; resolves
conflicts; reviews (/code-review); opens pull requests
(/pr); keeps them green (/autofix-pr).
/diff shows the changes, the agent's marked.
Background work
Servers and watchers run as background jobs the agent reads and waits
for (WaitFor) instead of sleeping; monitors turn their
errors into events that wake it; /loop repeats a prompt;
/schedule runs one from cron;
.oklm/services.json declares the project's stack
(/services). /tasks lists what runs (in
/tui, a panel to follow, stop, restart or keep each one).
See processes.md.
Tools from elsewhere
MCP servers (oklm agent mcp add NAME -- COMMAND, or
.mcp.json, approved once) add tools, resources and prompts
(/mcp); a remote one that asks for a sign-in shows "needs
auth": /mcp login NAME opens the browser, and the tokens
are kept and refreshed. Plugins bundle commands, skills, agents, hooks
and servers (oklm agent plugin install,
/plugin). WebFetch reads pages; WebSearch needs a SearXNG
instance (webSearch.url).
Hooks
Commands run on events: before or after a tool call (blocking or
approving it), when a message is sent, when the agent stops, when a
process starts or ends, before events reach the model.
/hooks lists them. See agent-extensions.md.
Scripts and CI
oklm agent -p TASK --output-format json|stream-json for
scripts, with --allowedTools,
--permission-mode, --mcp-config; piped input
comes first; the exit status tells how it went.
/install-github-app writes a workflow for a self-hosted
runner.
Usage and diagnostics
/usage (tokens, time in the model and the tools,
stats for the project's), /context (what fills
the context), /status, /doctor, the audit
log.
{ "pricing": { "default": { "input": 0.2, "output": 0.6, "cachedInput": 0.05 } } }A price table (dollars per million tokens, by model name prefix or
default) gives /usage and the JSON results
(total_cost_usd) a cost. --debug,
OKLM_DEBUG=1 or /debug writes the session's
debug log to ~/.local/state/oklm/logs/SESSION.log: model
turns, tool calls (secrets masked) and their results, with durations.
/bug [report] (or /feedback) writes a local
bundle under ~/.local/state/oklm/feedback/ with as much of
the conversation as you choose; nothing is sent. With
OKLM_ENABLE_TELEMETRY=1 and
OTEL_EXPORTER_OTLP_ENDPOINT (or
telemetry.enabled and telemetry.otlpEndpoint),
log records and metrics go to an OpenTelemetry collector, never the
content of a call.