OKLMdocumentation v1.0.3
On this page

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 own

The 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 model

It 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.