OKLMdocumentation v1.0.3
On this page

Agent tools

The tools oklm agent's model calls: the built-in tools, skills, deferred tools found with ToolSearch, sub-agents and the git operations. Part of the agent harness (harness.md); long-lived processes (jobs, services, language servers) are in processes.md, what decides whether a call runs in agent-permissions.md.

Status: implemented.

Tools

include/oklm/harness/tools.h, src/harness/tools.c, src/harness/process.c. oklm_tool_run(ctx, name, args_json, &result) takes a call as the model writes it (ADR-0009) and:

  1. parses the arguments (a JSON object), checks them against the tool's schema (types, required members, enums, items: an error names what is wrong and shows the schema), and takes the argument the rules read: the path, the command line;
  2. decides with the permission rules;
  3. when the decision is ask, calls the context's ask callback with an oklm_ask: the tool, the call in short (subject: the command line, the file relative to the project), the decision and why, for Write, Edit and MultiEdit a unified diff of the change (preview), and the rules "always" would add (rule: each simple command of the line, or the path relative to the project; none for a dangerous call or a line that cannot be split). The answer is no, yes or always: the rules are then added for the session, or, when the context's save_rules is set, saved to .oklm/settings.local.json. With a no, the callback may set feedback, which the model reads in the result ("The user says instead: ...");
  4. appends the audit line, with the answer;
  5. runs the tool, or returns the refusal with its reason and rule, which the model reads as the tool's result.
Tool Arguments Result
Read file_path, offset, limit, pages numbered lines (2000 by default, long lines cut); a PDF or Word document as text, a PDF's pages range; a notebook's cells and their text outputs; an image named with its size (the model cannot see it); other binary files and directories refused. Each file read is remembered (path, time, size, hash) for Write and Edit.
Write file_path, content the file created or replaced (directories created), atomically; an existing file only once read and unchanged since; its CR LF line ends and byte order mark kept; line numbers pasted from Read are stripped (as for Edit)
Edit file_path, old_string, new_string, replace_all old_string must occur once unless replace_all; the file must have been read and not changed since; line numbers pasted from Read are stripped (Read's tab, or a space when the numbers run on from 1 as small models paste them back; a number alone an empty line), CR LF files matched with plain newlines; written atomically, permissions kept; the result shows the numbered lines around the change
MultiEdit file_path, edits: [{old_string, new_string, replace_all}] Edit's edits applied in order to one file, each on the previous one's result: all of them, or none (the failing edit named)
Glob pattern, path, no_ignore the matching files, newest first, at most 1000
Grep pattern, path, glob, type, -i, -n, -A, -B, -C, output_mode, multiline, head_limit, offset, no_ignore path:line:text of matching lines (context lines as path-line-text, groups apart by --), or the files (files_with_matches), or counts per file (count); OKLM's regex engine (-i or (?i) ignores case); multiline runs the pattern over whole files; head_limit and offset page through the results; binary and oversized files skipped
Bash command, timeout, run_in_background, detach output (standard output and error) and exit code; in the background, the job's id
JobOutput id, offset a job's state, exit code and output from offset
JobKill id the job stopped with what it started
TodoWrite todos: [{content, status, activeForm}] the agent's task list (pending, in progress, completed), replaced whole, one task in progress at most; kept in the context (todos, todo_done of todo_total, todo_active: the task in progress as its activeForm says it); shown whole on the terminal, recalled to the model when it goes unwritten
Skill skill, args a skill's instructions, its arguments put in, with its directory; its allowed-tools allowed until the request is done; a context: fork skill runs as a sub-agent
ToolSearch query, max_results offered when tools are deferred or skills left out of the prompt's list: the definitions of the tools named (select:A,B) or matching words, and the skills matching
ExitPlanMode plan in plan mode, the plan shown to the user: yes leaves plan mode for default, always for acceptEdits, no keeps planning
  • Glob and Grep walk the tree without following symbolic links, skip .git and .oklm (the agent's own state), and never list or read a file a Read deny rule covers, so a search of the project does not reveal Read(./secrets/**). The .gitignore files apply, those from the project's root down to where the search starts, those met on the way, and .git/info/exclude: the last matching rule decides, ! re-includes, a trailing / means directories, ignored directories are not entered (no_ignore lists them). Grep's types are ripgrep's names (c, cpp, py, rust, go...); cpp covers .c too, as models ask for it on C projects.
  • Bash runs /bin/sh -c (cmd.exe /c on Windows) with an empty standard input. On POSIX systems the shell persists between calls: its directory and its variables (exported or not) are saved when a command ends, an exit included, under .oklm/shell/ and restored by the next call; a directory outside the project and its added directories is not reused (the next call starts in the project, with a note). Pagers and editors are neutralized (PAGER=cat, GIT_PAGER=cat, EDITOR=true, GIT_TERMINAL_PROMPT=0, TERM=dumb, NO_COLOR=1) and escape sequences are removed from the output. The shell runs in its own process group (a Job Object that kills on close on Windows). When the shell ends, what it left running in the background is killed; at the timeout (2 minutes by default, 10 at most) the group gets SIGTERM, then SIGKILL 2 seconds later; on Linux the shell dies with the harness. Output beyond 30000 bytes keeps its first and last halves, with a note of how much was left out between. Background jobs that outlive a call are the job manager's (ADR-0012).
  • TodoWrite, ExitPlanMode, Skill, JobOutput and JobKill touch only the session and the jobs it started: every mode lets them run (deny rules still apply). A first version refused a list with two tasks in progress; a 4B model then marked unfinished tasks completed to satisfy it, so the list takes any statuses.
  • oklm_tools_json() gives the eleven tools as OpenAI-style function definitions for the chat templates' tools; the descriptions say how to use them, and "No matches" suggests searching for the bare name (spec §27: instructional errors for local models).

The web, notebooks, questions

  • WebFetch {url, prompt}: a GET through the API client (TLS checked), 30 s and 5 MiB at most; redirects on the same host followed (five), one to another host said so the model fetches it itself (and the rules decide it); HTML rendered to text (scripts and styles out), JSON indented, a PDF read, other binaries named; an error status is an error. WebFetch(domain:HOST) rules decide it; without one it asks. It is offered in the prompt: deferred, Qwen3-4B reached for curl instead of looking it up.
  • WebSearch {query, allowed_domains, blocked_domains} (deferred): ten results (title, address, snippet) from the SearXNG instance of webSearch.url; without one it says so. There is no built-in provider.
  • NotebookEdit {notebook_path, cell_id, new_source, cell_type, edit_mode} (deferred): a cell, by its id or its number, replaced (its other keys kept, a code cell's outputs cleared), a new one inserted after it (or first), or deleted; the notebook must have been read and be unchanged, like Edit; written atomically, checkpointed. Edit rules cover it.
  • AskUserQuestion {questions: [{question, header, options: [{label, description}], multiSelect}]} (deferred): one to four questions, each shown in the picker with "something else" last (numbers for several choices); the answers go back as the result. A -p run has nobody to ask: the tool tells the model to decide and say so.

Retrieval

  • Retrieve {query, k, scope}: offered only when retrieval is on (--rag-project or rag.enabled: the project's documentation, indexed and kept up to date by the agent; --rag INDEX: a fixed index). The passages that answer the query, numbered with their file, lines and heading to cite as [n], judged by the model (those that do not answer left out, the query rewritten when none does), or a notice that no reliable source was found. scope (with --rag-memory): project, memory (earlier sessions' transcripts and the memory files) or all. It only reads: every mode runs it without a question, plan mode included, as Read inside the project; a Retrieve deny rule removes it. The index, its updates and the settings: rag.md.

Skills

A skill is a directory holding a SKILL.md: instructions for one kind of task, loaded only when the task needs them, so the system prompt stays short. Other files of the directory (a reference.md, scripts/) are read or run by the agent when the instructions name them; only what it reads, or a script's output, enters the context.

.oklm/skills/c-check/SKILL.md
---
name: c-check
description: Check a C source file for warnings. Use when the user asks to check, lint or compile-check a .c file.
allowed-tools: Bash(cc:*)
---
To check a C file:
1. Compile it with: cc -Wall -Wextra -c FILE -o /dev/null
2. Report every warning with its line number, or say it is clean.

Where. oklm_tool_ctx_load_skills() reads, in this order of precedence: the project's .oklm/skills/*/SKILL.md and .oklm/commands/ files, its .agent/skills and .agent/commands, the user's ~/.config/oklm/skills and commands ($XDG_CONFIG_HOME/oklm, %APPDATA%\oklm), ~/.agent/skills and commands (the commands directories left out with commands.legacyDirs false), then the built-in skills. A later skill of a name already found is kept, marked shadowed (/skills says by which). Entries are read in name order, so the list, and the system prompt, are the same on every file system. Project skills come with the project's trust: the first run in a folder asks (§ Terminal UI) before anything of it is read.

The header. Between two --- lines, in the YAML that skills use: plain or quoted values, > and | blocks, lists as [a, b] or - a lines, # comments. Keys:

Key Meaning
name kebab-case, 64 characters at most (the directory's name without it)
description what the skill does and when to use it, 1024 characters at most (the body's first line without it)
allowed-tools permission rules allowed without asking while the skill runs, until the request is done (deny rules still win)
argument-hint the arguments, shown in the command menu
disable-model-invocation true: only the user starts it, as /name
user-invocable false: only the model loads it
context, agent context: fork runs the skill as a sub-agent of the agent type (general-purpose by default)
model read and shown, not acted on: the agent's model is used

A malformed header, a name or description over its limit, a name not in kebab-case, a boolean that is not one, or an allowed-tools entry that is not a rule leaves the skill out; unknown keys and a missing description are warnings. Both are printed at start, kept in oklm_tool_ctx.skill_warnings, and listed by /skills; nothing makes the agent fail to start. oklm agent skills validate DIR checks a skill directory, a directory of skills or a single file the same way (status 1 on any error); oklm agent skills list shows what the agent finds.

Three levels. The system prompt lists each skill the model may load, name and description (cut at 250 characters), and asks the model to check the list before a task. The list takes at most skills.listBudget tokens (2000; about 65 a skill, so twenty fit); skills past it are counted in a line pointing to ToolSearch, which finds them by words. The Skill tool (skill, args) returns the body, its arguments put in as for a prompt command ($ARGUMENTS, $0...; !`cmd` and @file too), with the skill's directory and a line telling the model that loading it did nothing yet and the steps are to be carried out (small models otherwise took the loaded text for the work done).

While a skill runs, its allowed-tools are rules of their own source (skill), cleared when the request is done: the user's agent clears them at the end of each oklm_agent_send(), and a prompt command's at the end of its turn. A context: fork skill becomes an Agent call: its expanded body is the sub-agent's task, decided and audited as one.

After a compaction the summary is followed by the names of the skills loaded before it (their instructions went with the old messages), so the model may load them again. A sub-agent definition's skills: [a, b] preloads them: their instructions are the sub-agent's first message.

Changes on disk are noticed before each line typed at the prompt (the directories' entries, sizes and times as one stamp, oklm_tool_ctx_skills_changed()): the skills are read again, the menu and the system prompt with them. /reload-skills does it at once and tells what was added and removed.

Built in: skill-creator walks through writing a skill (interview, place, header, body, skills validate, trying it).

Deferred tools and ToolSearch

Tools named in deferred_tools (the deferredTools setting; ProcessList and PowerShell by default) keep their definitions out of the prompt: the system prompt names them, and ToolSearch (select:NAME, or words) returns their definitions as <function>{...}</function> lines. For the in-process model the tool-call grammar accepts every tool from the start, so the prompt (and the KV cache) never changes when a tool is loaded; a backend is offered the tools loaded from then on. ToolSearch is offered only when a tool is deferred or a skill is left out of the list.

Tool selection by retrieval (--tool-rag K, the toolSearch.topK setting; off by default). The agent keeps its tools, skills, plugin commands and sub-agent types in a retrieval index (Type, Service, Tool; src/harness/tool_index.c), searched hybrid with an embedding model (toolSearch.model, bge-small-en-v1.5 by default, on the CPU) or with BM25 alone when there is none; toolSearch.mode dense or bm25 ranks by one list instead (hybrid stays the default: at the same number of definitions given, dense defines no more of a request's tools). With it on, every MCP tool is deferred and the prompt counts each server's tools instead of naming them; before each user message's first turn the K best entries for the message (and the previous one) are retrieved, and the deferred tools among them whose cosine with the request reaches toolSearch.minScore (0.62) come with the message (skills and sub-agent types are only logged): their definitions in a reminder for the in-process model (its prompt and KV cache unchanged), offered in the tools array for a backend (those of the previous message no longer). ToolSearch's word queries are ranked by the same index. Each decision (the query, the ranking with its dense, BM25 and fused scores, what was chosen) goes to the debug log (--debug) as a tool retrieval: or ToolSearch: line. Measured in rag.md.

Sub-agents

The user's agent also offers an Agent tool (Task is read as it): description, prompt, subagent_type, model (accepted; the agent's own model is used) and run_in_background. A self-contained task (a search across many files, an investigation, a plan) is handed to a sub-agent with a fresh conversation on the same model, the same rules and audit log. The call is decided like a tool, as Agent(description) (asks by default, denied in plan mode); the sub-agent's system prompt adds that it answers with a short report, which comes back as the call's result without its reasoning, followed by a line [agent N (type): K turns, T tokens written; wrote a.py, CHANGELOG.md; its last command, python3 t.py, exited 0; SendMessage to N continues it]: the files it wrote with Write, Edit, MultiEdit or NotebookEdit, or wrote no file (Write, Edit), and the last Bash command it ran with its exit code, from what it did, not from what it says (a background agent's report ends with [agent N: wrote ...]). A sub-agent whose task asks for a change (fix, change, edit, add, write, update, rename, implement, create, remove, replace, refactor, modify, delete) and that ends having written nothing is asked once more, to make it with Edit or Write or to say plainly that it changed nothing and why; its second answer is the report. Sub-agents running at once share the working tree, so a line one of them wrote is kept from the others while their runs overlap: an Edit or Write that would remove it is refused ("this removes a line another sub-agent working beside you wrote in this file: ...; keep it as it is and add your change beside it"), a change beside it goes through. Lines of fewer than eight characters that are not blanks stay free; the writer may change its own lines, a sub-agent started after it ended may change them, and the session's own agent is never held.

  • Types (include/oklm/harness/agents.h): general-purpose (all the tools), Explore (Read, Glob, Grep: a fast read-only search, reporting the files and lines it found), Plan (Read, Glob, Grep: read-only research ending in a plan) and code-reviewer (Read, Glob, Grep, Bash: a read-only review of a change that reports findings and never edits, which the /code-review skill's passes use), then the Markdown files of the project's .oklm/agents/ (.agent/agents/ when it is absent) and of the user's agents/ directory, a header giving name, description, tools (left out: all), skills (preloaded: their instructions are the sub-agent's first message) and model (small or fast: the sub-agent runs on the smallModel when one is set, in a context of its own; else the main model), the body instructions added to the sub-agent's prompt. A later one of a name already known is shadowed. The system prompt lists the types with their tools; an unknown subagent_type is answered with the list.
  • Tools: a type's tools are the only ones offered to it, and a call to another is refused (Error: Write is not one of this agent's tools).
  • At once: several Agent calls in a row in one turn (two to eight, not in the background) run at the same time, each on a context and a tool context of its own (the in-process model, a generate callback, or a backend that gives each sub-agent a copy of its own, as the HTTP backend of --url does with a connection per sub-agent; a backend without copies serves one turn at a time, so they run one after another); their reports come back in the calls' order, and the caller's context holds only them. A single call runs on the caller's context while it waits, so the caller evaluates its conversation again on its next turn.
  • SendMessage (to, message) continues a sub-agent that finished, foreground or background (sixteen are kept, the oldest let go, all of them at a reset): it reads the message after what it did before and answers with a new report.
  • Depth: sub-agents start none (agents.maxDepth, 1 by default; 2 lets a sub-agent start its own).
  • /agents lists the types (source, tools); /agents new NAME DESCRIPTION has the model write the instructions and saves .oklm/agents/NAME.md (all the tools; a tools: line narrows them); /agents edit NAME gives the file; /agents reload reads them again.
  • The SubagentStop hook runs when a sub-agent ends (§ Hooks).

With run_in_background: true the sub-agent runs in a thread of its own, with a context of its own on the same model (background_ctx in the agent's options, by default the agent's context length; oklm agent gives it the agent's backend and cache types), and the call returns at once ("Started background agent N"). At most max_background (2 by default, --max-background) run at once. Its tool context is a copy (oklm_tool_ctx_share()): the same rules, audit log, jobs and sandbox, its own task list, and no one to ask, so a call that would ask is refused. Threads sharing a tool context take one lock around decisions, rules added, audit records and jobs; commands and file operations run outside it, and the user is asked without it. Before each turn of the caller, the reports of the sub-agents that ended arrive as one user message ("Background agent N (description) finished. Its report: ..."). An answer given while some still run is followed by a wait for the next report and another turn, so oklm_agent_send() returns once every report was read, or at the turn limit. A Bash call that commits or pushes while some still run is not run either: its result names them ("Not run: background agents are still running (agent 1: ...)"), the turn's other calls run, and the next turn waits for a report, so the model decides again with it read; a sub-agent may still be changing the files, or report what changes the decision. agents.waitForBackground lists those commands (["git commit", "git push"] by default, a deploy command added there; [] none); a git entry matches git with options before its subcommand (git -C dir commit), after variable assignments, in any command of a compound line; freeing or resetting the agent stops the ones still running at their next turn or token and waits for them. Several contexts of one model run at once on the CPU and on an OpenCL device (each instance enqueues one call at a time).

Qwen3-4B on the GPU, asked to start a background agent to find which file defines helper and meanwhile change app.c's version string: the agent starts the sub-agent, edits app.c while the sub-agent greps (a wrong glob, src/**/*.c, then **/*.c: util.c:1:int helper(void) { return 4; }), and once the report arrives answers "util.c, returns 4; app.c now prints v2". The 4B model also tries JobOutput on the agent's number, which answers that a background agent is not a job.

Qwen3-4B, --allow "Agent", asked to find with a sub-agent which file defines helper: the sub-agent globs **/*.c, greps for helper, and reports util.c:1:int helper(void) { return 4; }; the agent answers "util.c, returns 4".

Git

include/oklm/harness/git.h, src/harness/git.c, and the git part of the permission rules; git_spec.md G1 to G3. Git runs as the git command, through Bash and its rules; the harness only reads what it needs.

  • At the start (oklm_git_detect()): the work tree, the branch, the default branch (origin's HEAD, else main or master, else init.defaultBranch), an operation left half done (merge, rebase, cherry-pick, revert, bisect: told at start), origin and its host, gh, submodules, LFS, a shallow clone, how the last 50 commit subjects are written (Conventional Commits, a module prefix, a ticket number, gitmoji; case, length, final period), how branches are named, the pull request template, the hooks a commit runs, signing.
  • The snapshot in the system prompt (oklm_git_snapshot()), computed once and kept, so the prompt and the KV cache stay the same: the branch, the default branch, the status (40 lines), the last 5 commits (subjects cut at 80 characters), the conventions and the hooks; then the rules of committing (prompts/git.md): only when asked, the files of the change staged by name, the repository's style, -m or -F, a check after, hooks' failures fixed and committed anew (three tries), never --no-verify or rewriting pushed history unasked. git.coAuthorTrailer adds the trailer to put at the end of each message. With LFS paths, a line says whether git lfs is installed (without it the LFS files are pointers and a commit would store the file itself) and, when it is, the objects git lfs status lists as not pushed and the files git lfs ls-files marks - (pointer only, not pulled), ten of each at most.
  • Code owners (oklm_git_owners()): /commit and /pr get, after their expanded prompt, the owners of the files the session edited, from .github/CODEOWNERS, else the top's CODEOWNERS, else docs/CODEOWNERS (else .gitlab/CODEOWNERS): gitignore-style patterns (*, **, ?, a leading / anchoring, a trailing / naming a directory, docs/* not recursive), the last matching line winning, one naming nobody taking the owners away. /commit names them in its report, /pr in the description and as gh pr create --reviewer.
  • Changes: before each model turn the branch and HEAD are read from the repository's files (oklm_git_head(), packed refs and worktrees included, GIT_CEILING_DIRECTORIES honored); a switch or a new HEAD is told in one line, the snapshot left as it was.
  • Commands read apart (oklm_perms_git_class()): global options and assignments dropped (git -C x push, GIT_DIR=y git push meet the rules on git push; an allow rule only when what was dropped just chose the directory or the pager), then the subcommand classed:
    • reads (status, diff, log, show, blame, branch and tag listings, remote -v, stash list, config --get, rev-parse... and gh pr view, gh api GET...): allowed without a rule, in plan mode too, unless the output goes to a file or -c changes git's settings;
    • changes (add, commit, checkout, merge, fetch, pull...): ask unless a rule allows them; config writes are dangerous;
    • interactive (rebase -i, add -p, commit without -m / -F, checkout -p, clean -i, mergetool...): refused whatever allows them, with what to do instead, since they would wait for a person.
  • Dangers that depend on the repository: a push to the default branch or one of git.protectedBranches, an amend or a rebase of a commit already pushed, ask even when a rule allows them (with the reason in the question).
  • Before a commit (oklm_git_precommit(), on what is staged, and the tracked changes for -a): what looks like a secret in the added lines (AWS, GitHub, GitLab, Slack, Google keys, sk- API keys, private keys; gitleaks too when installed) stops the commit, which the agent never runs, the findings named by file and line, never shown; .env files, keys, credentials, node_modules, OKLM's local state, personal instruction files, and files over 5 MB outside LFS are told to the user after the commit.
  • Branches and conflicts (in prompts/git.md): new branches named as the repository names them, from the task, on the up-to-date default branch; a switch with uncommitted changes asks first (commit, stash or carry); git pull --rebase or --ff-only, a divergence explained; git branch -d after a merge. A stopped merge, rebase or cherry-pick: the conflicted files listed, their markers and git log --merge read, resolved with Edit, tested, staged, continued; both sides shown to the user when they changed behavior; --abort always a way out. Squashing by git reset --soft and a new commit. In code: a switch carrying uncommitted changes and a commit straight to a protected branch ask (git.protectedBranches, by default main, master, develop and release/*; entries ending with a star match a prefix), with the reason in the question.
  • Bisect: git bisect start BAD GOOD, git bisect run with a test command; a bisect a Bash call started is reset (git bisect reset) when its request ends, finished or interrupted, and the user is told.
  • /diff lists the work tree's changes against HEAD with their counts, the files the agent wrote or edited this session marked *, the untracked ones as new, then the diff (colored on a terminal); /diff stage|unstage FILE, /diff revert FILE (asks first, on the terminal only), /diff open FILE ($VISUAL or $EDITOR). The git commands run as the user's, through the audit log.
  • /commit is a built-in prompt command (the model cannot start it): the status, the diffs and the last commits put in, then the steps: the files of the change, staged by name, the repository's prefix, the check, the report. Its allowed-tools let it run git add and git commit for that request.
  • /pr [base] [--draft] [notes] is a built-in prompt command like /commit: the status, the default branch, the branch's commits and files and the repository's pull request template put in; then the steps: stop on uncommitted files or on the default branch, read every commit, push a branch without upstream (asked unless allowed), a title in the commits' style, the template's sections or Summary / Changes / Test plan written to .oklm/pr-body.md, gh pr create --body-file (or glab mr create), the URL reported. Its allowed-tools let it create the pull request and write the body. Sandboxed commands have no network: /sandbox network on lets a push and gh reach the host.
  • Reviews: /code-review [low|medium|high|max] [--fix] [--comment] [--max-findings N] [PR|branch|path] reviews for bugs: low one pass, medium three sub-agents (correctness, edge cases, tests), high and max a refuting sub-agent per finding (max also the code the change calls), findings merged and ranked with file:line, the failing input and the fix; --fix applies them, --comment posts them with gh (asked). /security-review reviews the branch against origin's default branch (injection, authorization, secrets, deserialization, traversal, SSRF, cryptography, dependencies, exposure, memory safety), each candidate checked by a refuting sub-agent, with severity, confidence and the exploit. /simplify runs four sub-agents (reuse, simplification, efficiency, abstraction) and applies what the user accepts. /ultrareview is /code-review max, locally. /bisect [bad] [good] [command] drives git bisect. All are prompt commands with read-only allowed-tools; the level is not remembered between calls yet, but review.defaultLevel gives /code-review its level when the arguments name none.
  • Worktrees (git.h): oklm_git_worktree_add() makes .oklm/worktrees/NAME on the branch oklm/NAME from HEAD or a base, copying git.worktree.copy (by default .oklm/settings.local.json) and linking git.worktree.symlink (node_modules) from the repository; its changes are counted without the harness's .oklm; removal refuses uncommitted work unless forced and deletes the branch (-d) when it holds no commit. The Agent tool's isolation: "worktree" runs a sub-agent (foreground or background) in a worktree of its own: its tools rooted there (the sandbox already covers it, under the project), its report followed by what became of it (removed when it changed nothing, otherwise its path, branch, commits and uncommitted files, with how to see, merge or drop it). oklm agent --worktree [NAME] runs the session in one; at the end it is removed when it holds nothing new, otherwise said kept. The EnterWorktree tool (deferred) moves the session's root into a new one mid-session (relative paths, commands and the shell start there; a sub-agent cannot move); ExitWorktree (keep, remove with force once the user agreed when it holds work, merge of its commits into the branch at home: a protected one asks, whatever the rules; a conflict is undone and the session stays) comes back; one left untouched is removed at the session's end. Every worktree, whoever asks (worktree.h), is made by the WorktreeCreate hook when there is one, by git otherwise, then set up: git.worktree.copy and git.worktree.symlink (into their directories), then the commands of git.worktree.setup one after the other (not confined, like hooks; 10 minutes each; their outcome told). Settings with dots nest at any depth: {"git": {"worktree": {"setup": [...]}}}. /doctor lists the agent's worktrees. /batch INSTRUCTION researches, splits the change into independent units, has the plan approved, starts a background isolated Agent per unit (each committing on its branch) and reports a table; nothing is merged unless asked.
  • /autofix-pr [PR] [focus] keeps a pull request green: its checks put in (gh pr checks), failing ones read (gh run view --log-failed) and fixed, review comments addressed (no reply posted without the user), fixes committed and pushed (asked unless allowed, never forced), then a ScheduleWakeup in five minutes for the next round; it stops when all passes, or at round ten. The git-history skill (the model loads it) teaches blame, log -L, the pickaxe, --follow and release ranges. /install-github-app [label] [model] writes .github/workflows/oklm.yml for a self-hosted runner (OKLM needs the model on it): run on @oklm comments from members, the comment passed through the environment, the sandbox kept, pushes to the pull request's branch only, the result commented; and a GitLab equivalent.
  • Running the application: /run [what] launches and drives the project's application (the project's run skill when there is one; otherwise from its README, Makefile, package.json, compose files: build, launch in the background, WaitFor, curl or run it, show the real output, stop what it started). /verify [change] states first what should be observed, runs and observes it and a case next to it, and gives a verdict with the evidence (tests alone are not one). /run-skill-generator writes .oklm/skills/run-app/SKILL.md from steps it tried from clean, validated.
  • Every command's environment sets GIT_EDITOR, GIT_SEQUENCE_EDITOR, GIT_PAGER, PAGER and GIT_TERMINAL_PROMPT, so nothing waits for an editor or a password.

On Qwen3-4B, /commit the new sub function in math.c in a repository written in Conventional Commits with a stray notes.txt: it stages only math.c and commits fix(math): ... (the prefix right, the subject's wording loose). The first wording of /commit got a plain "Add ..." subject; another time the model answered "committed" without a call, which the line "answer only once git log shows the new commit" ended.