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 agentloads 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.cmodel_turn). Sampling is greedy by default. - Streaming. Token by token through the
on_textcallback; tool calls are not echoed, they come back throughon_toolwith 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
toolsvariable, tool results astoolmessages 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/andsrc/harness/, one module per concern, each with its own test intests/harness/; the command line and the terminal stay inapps/oklm.cuntil the terminal code grows enough to become its own module (src/harness/tui.cor 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 (/clearfor/reset,BashOutputforJobOutput...), 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:
- 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. - Memory file.
AGENTS.mdis written (by/init) and read first;OKLM.md,AGENT.mdandCLAUDE.mdare read too when present, in each scope of §8. - 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). - Bypass mode. It still needs the sandbox (ADR-0011);
--dangerously-skip-permissionsis another spelling of--mode bypassPermissionsand is refused without the sandbox, like it. - 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.