OKLMdocumentation v1.0.3
On this page

Agent design

How the coding agent of agent_skill_chat_spec.md maps onto OKLM: how the model is run today, and for each section of the spec the existing module it extends or where new code goes. What exists and what is missing, with evidence, is in gap-analysis.md.

Status: accepted (the spec's M0, 2026-11-02); its M1 starts from here.

The model today

  • Invocation. In process. oklm agent loads a GGUF model, opens one context (32768 tokens by default, within the model's training length) and hands it to the agent (include/oklm/harness/agent.h). Each turn, the conversation is rendered by the model's chat template, tokenized, and only the tokens after the prefix already in the KV cache are evaluated (src/harness/agent.c model_turn). Sampling is greedy by default.
  • Streaming. Token by token through the on_text callback; tool calls are not echoed, they come back through on_tool with their result. The terminal view (apps/oklm.c, view_*) splits the reasoning from the answer (include/oklm/harness/think.h) and folds it.
  • Chat templates. The model's own Jinja template, run by OKLM's interpreter, identical to jinja2 on the corpus (adr/0006-chat-templates.md); tools in its tools variable, tool results as tool messages with their call id.
  • Tokenizer. The model's, from the GGUF (tokenizer.md), bit-exact with Hugging Face's; counting tokens is exact and cheap.
  • Context length. -c, 32768 by default for the agent (capped at the model's training length); a turn has at most 8192 tokens; overflow is reported and the user asked to /reset.
  • Native tool calling. Hermes, Llama 3, Mistral and GLM-4.5 formats, detected from the template; from the opening marker on, the call is constrained by a grammar built from the tools' schemas, so it always parses (adr/0009-tool-calls-and-grammars.md). The spec's text protocol (§2.3) is not needed: the native formats stay, Hermes being the fallback for templates without tools.

Principles of the mapping

  • One library, include/oklm/harness/ and src/harness/, one module per concern, each with its own test in tests/harness/; the command line and the terminal stay in apps/oklm.c until the terminal code grows enough to become its own module (src/harness/tui.c or an app file of its own).
  • OKLM's names and places are kept (oklm agent, .oklm/, ~/.config/oklm/); the spec's names become aliases where users would look for them (/clear for /reset, BashOutput for JobOutput...), subject to the open questions below.
  • Decisions that change a convention get an ADR, as permissions, the sandbox and jobs did (ADR-0010 to ADR-0012).

Section by section

§ Existing module New code
2 Model adapter agent.c model_turn, the generate callback oklm_agent_backend in agent.h: the in-process model, the callback, and an OpenAI-compatible HTTP backend over src/client/ (so oklm agent can drive oklm serve or another server); stream events (text, reasoning, tool call, usage, stop) instead of the bare on_text; cancel through the existing stop flag, from Esc / Ctrl-C. Fixture mock: a JSONL script read by the tests' generate.
2.4 Reasoning think.c, view_split Reasoning dropped from the history sent back (as sub-agent reports already are), a setting to keep it.
2.5 Models A second context for a small model (--small-model), used by compaction and the command classifier; /model reloads.
3 Messages agent.c msg Content blocks (text, image, reasoning) and metadata (id, parent, time, usage) on the existing message list; images through src/mm/ when the model has a projector.
4 Loop agent.c oklm_agent_send Hook calls around tools and prompts (§15), reminders as marked messages, compaction on overflow (§10), read-only calls of one turn in parallel, loop detection, interrupts.
5 Tools tools.c, process.c, jobs.c A tool registry replacing the fixed table (flags read-only / concurrency safe, enabled per settings and agent, deferred); MultiEdit, LS, WebFetch (client + ingest's HTML to text), NotebookEdit, AskUserQuestion, EnterPlanMode, ToolSearch in tools.c or tools_web.c; a read registry (path, mtime) for Edit and Write; a persistent shell per session in process.c; BashOutput / KillShell as aliases of the job tools.
6 Permissions permissions.c, sandbox.c, audit.c Shift+Tab in the line editor, a dangerous-pattern list, diffs in the question, "always" saved to .oklm/settings.local.json, secrets registered from the environment. The sandbox stays ADR-0011's.
7 Settings permissions.c (settings files) src/harness/settings.c: the whole settings object (model, hooks, env, MCP servers, compaction...) merged once, permissions reading their part from it; /config, /permissions in the REPL.
8 Memory src/harness/memory.c: the memory files by scope, imports, lazy loading of sub-directories, injected in the system prompt; /init, #, /memory.
9 System prompt agent.c render src/harness/prompt.c: the prompt assembled from parts (identity, rules, tools policy, environment, git, memory, skills, style), with a snapshot test.
10 Context agent.c (n_cached) Token accounting per part, /context, compaction by the model (or the small one), micro-compaction of old tool results.
11 Sessions audit.c and jobs.c journals src/harness/session.c: the transcript as JSONL in .oklm/sessions/, --resume, checkpoints of the files edited, rewind, /export.
12 Sub-agents agent.c run_subagent, background agents Definitions in .oklm/agents/*.md, built-in types (general, explore, plan), parallel foreground calls; worktree isolation from git_spec.md §9.
13 Skills tools.c skills The rest of the front matter (allowed tools, model, user-only), /name args, warnings, reload, trust.
14 Commands cmd_agent REPL Replaced by commands_spec.md: a registry of built-ins and prompt commands (.oklm/commands/*.md, skills), a parser, a menu and completion in the line editor.
15 Hooks process.c proc_run src/harness/hooks.c: events, matchers, JSON on standard input, exit codes and JSON answers.
16 MCP client.c, process.c, nilorea JSON src/harness/jsonrpc.c (framing, shared with language servers, see process_spec.md) and src/harness/mcp.c (stdio and HTTP transports, tools into the registry as mcp__server__tool, resources, prompts).
17, 18 Plugins, styles Late milestones; files under .oklm/plugins/, .oklm/output-styles/.
19 Terminal view_*, line_edit.c Markdown while streaming (the GUI's renderer has the rules), diffs, a spinner, the task list, multiline input, key bindings, a status line.
20 Headless cmd_agent -p `--output-format text
21 to 23 jobs.c, audit.c Git per git_spec.md; Monitor (process spec); usage and time per session, /cost, /status, /doctor.
24 Security permissions.c, sandbox.c Trust question before project settings, hooks, MCP and skills; untrusted-content rules in the prompt.
25 Tests tests/harness/ A fuzz target for the tool-call parser and the command splitter (fuzz/ exists), prompt snapshots, an evaluation script over scripted tasks with a published model.

Order

The spec's milestones, each starting with a fresh search: M1 to M8 first (backend and events, loop, tools, permissions, prompt, memory, settings, compaction, sessions), then M9 to M14, then M15 to M20. The process specification (process_spec.md) starts once M1 to M8 are done; it shares the JSON-RPC module with MCP.

Decisions

The questions the code could not answer, answered on 2026-11-02:

  1. Names. OKLM's stay: oklm agent, .oklm/ in the project, ~/.config/oklm/ for the user. The spec's .agent/ and ~/.agent/ are read as a fallback when present (settings, skills, agents, commands), never written.
  2. Memory file. AGENTS.md is written (by /init) and read first; OKLM.md, AGENT.md and CLAUDE.md are read too when present, in each scope of §8.
  3. Tool and command names. OKLM's stay (Agent, JobOutput, JobKill, /reset, /jobs, --system, --mode); the spec's are accepted as aliases (Task, BashOutput, KillShell, /clear, /bashes, --system-prompt, --permission-mode).
  4. Bypass mode. It still needs the sandbox (ADR-0011); --dangerously-skip-permissions is another spelling of --mode bypassPermissions and is refused without the sandbox, like it.
  5. Default models (decided 2026-11-02, changed 2026-11-04, roadmap.md). General use and coding share one model, Qwen3-8B, from the official BF16 safetensors (Qwen/Qwen3-8B), so the agent rarely switches models. The base for security training is an abliterated Qwen3-8B that OKLM makes from those official weights. The 27B first chosen (Qwen3.8-27B) was too large for the 20 GB GPU.