OKLMdocumentation v1.0.3
On this page

Processes, services and integrations

How oklm agent runs things that outlive a command: background jobs, monitors, wakeups, language and MCP servers, declared services, containers, clusters, devices, machines, clouds and tunnels. The design is in process-design.md and adr/0012-jobs.md; each part's details follow its overview here, MCP servers' in agent-extensions.md.

Status: maintained.

One process manager

Every long-lived process is a job of the session (jobs.h): a command in its own process group with its log under .oklm/jobs/SESSION/, a kind (command, monitor, lsp, mcp, service, agent), a label, an owner, an optional restart policy and stop command. Jobs stop with the session (their whole group, after a grace), unless kept (keep_alive) or detached (asked), or unless processes.keepOnExit leaves every running job alive at exit. On the terminal, leaving with jobs running asks: stop them, keep them running ([k]eep: they outlive the harness, the next session lists them with the orphans, said kept at exit), or stay. A session that died leaves orphans: the next one finds them and offers to stop them (processes.autoReapOrphans), /doctor fix stops them too. A recorded process id now held by an unrelated process (another start time) is not taken for the job. Jobs run in the commands' sandbox, except the servers the user configured (MCP servers), which run as the user's own programs.

A background sub-agent owns the jobs it starts (owner agent N, and agent N/agent M for one of its own). When it ends, those still running are stopped and its report lists them; a job started with Bash's keep_alive is handed to the session instead, and the report says so.

Background jobs

include/oklm/harness/jobs.h, src/harness/jobs.c; the decisions of adr/0012-jobs.md. Bash with run_in_background starts a job and returns its id; the model reads it with JobOutput and stops it with JobKill, and before each model turn the agent tells it, as a user message, which jobs ended and how.

  • Journal: .oklm/jobs/<session>.jsonl, one JSON line per event (started with the process id, its start time, the command and the files; finished with the exit code; killed; interrupted; reattached). Output goes to .oklm/jobs/<session>/<id>.log, the exit status to <id>.status.
  • Owned jobs (the default) run in their own process group under a wrapper shell that runs the command in the background and waits for it, so a SIGTERM reaches its trap at once; the trap kills the whole group. The wrapper gets SIGTERM when the harness dies (Linux, PR_SET_PDEATHSIG), and oklm_jobs_close() stops the jobs still running: nothing the harness started runs on unseen. Windows: a Job Object that kills on close.
  • Detached jobs (detach, decided by Detach(command) rules, which read command lines like Bash rules and ask by default) run in their own session and survive the harness. Opening the session again re-attaches a job whose process id and start time (/proc/<pid>/stat) still match; a job found dead is recorded as finished when it wrote its status, as interrupted otherwise. Nothing is restarted.
  • Retention: journals and logs of sessions older than 30 days (processes.logRetentionDays) whose jobs have all ended are removed when a session opens.
  • What a job is (oklm_jobs_start_spec()): a kind (command, monitor, lsp, mcp, service, agent), a label, a directory, an owner (a sub-agent), all in the journal's started line and read back; its start and end times, the signal that ended it. Its environment carries OKLM_SESSION_ID and OKLM_PROCESS_ID, GIT_EDITOR=true, GIT_SEQUENCE_EDITOR=true, GIT_PAGER=cat, PAGER=cat and GIT_TERMINAL_PROMPT=0, so nothing waits for a person; the harness's own descriptors are closed before the command runs (a socket it inherited would look like its own port).
  • At most 20 run at once (processes.maxConcurrent); past that, starting one fails and the Bash tool lists what runs.
  • Readers (oklm_jobs_read()): each reader (the model, a monitor) keeps its own place in a job's output and gets only what is new, whole lines only while the job runs, escape sequences removed, a carriage return keeping what follows it (progress bars), optionally only the lines a regular expression matches, only the last N, within a byte cap, told how many lines were left out.
  • Rotation: a log over 32 MiB (processes.logRotateMB) is copied to <id>.log.1 and emptied (the job appends to it); offsets count the rotated bytes, and a rotated event is journalled.
  • Restart policy: a job started with restart_max is started again when it fails (exit status not 0, not stopped), after 1 s, then 2, 4... (restarted in the journal); stopping it ends that.
  • Stopping (oklm_jobs_stop()): the job's stop command first (such as docker compose down), SIGTERM to its group, SIGKILL after the grace (5 s, processes.defaultGraceMs, or the job's own), then a check that the group is gone. At close the last started goes first, and jobs kept alive (keep_alive, processes.keepOnExit, --keep-services) are left running: each gets a mark beside its status file (N.status.keep) that its wrapper's TERM trap reads, so the TERM its harness's end sends it (PR_SET_PDEATHSIG) does not stop it either; in the sandbox the process waiting for the namespace passes that TERM on to the wrapper instead of dying of it. A piped job (a language or MCP server) and a command adopted from the foreground cannot be kept: their output goes through the harness.

oklm agent opens the jobs of its session (/jobs lists them) and stops its owned jobs when it exits.

What an earlier session left (oklm_jobs_orphans(), oklm_jobs_reap()): opening the jobs reads the other sessions' journals; an owned job with no end whose process group still has processes started after it (its leader dead or not: a child ignoring SIGTERM outlives the wrapper) was left by a harness that died without closing. A process now holding the recorded leader's id with another start time is an unrelated later process that reused the id (the kernel gives no group's id to a new process while the group has members): no orphan, nothing signalled; a job of the session's own journal whose process id was reused is recorded as interrupted, without a signal, as one whose process is gone. oklm agent lists them at start and asks whether to stop them (stopped at once with processes.autoReapOrphans; /tasks reap later); each one stopped gets an interrupted line, reaped_by this session, in its own session's journal. Detached and kept-alive jobs are never orphans; jobs kept by the exit question's "keep" answer are, said kept at exit, so the next session offers to stop them.

Leaving: /exit or Ctrl-D on the terminal with jobs running lists them and asks: [y]es stops them, [k]eep leaves them running (oklm_jobs_keep(): each one marked as at close, a kept line in the journal, a detached job from then on; the next session lists it with the orphans, --resume re-attaches it; POSIX only), [n]o brings the prompt back. At exit the agent says how many it stops and how many it keeps alive.

Notices (oklm_events_notice(), oklm_events_take_notices()): what went wrong or ended in the background is told to the user once, as a dimmed line with the terminal's notification (preferredNotifChannel), or a {"type":"system","subtype":"notification","message":...} line in a headless stream-json run: a job that crashed (it ended by itself with an exit status other than 0 or by a signal; not one the agent or the user stopped), with its label and last line (job 3 (dev server) crashed: exit code 1; its last line: Error: port 5173 in use); a service whose readiness probe failed (timed out, or its process ended first: one notice, not a crash besides); a background agent that finished or failed. The model hears of each at its next turn: crashes through its job notes, a background agent's report as before, a readiness failure through its tool result, or, for a service started with the session, as a [notice] line among the events (which does not wake the idle agent).

A job's end note: the note the model gets at its next turn when a job ended says how (Background job 3 (npm test) finished with exit code 1., a signal named) and its last non-empty line (Its last line: ..., escape sequences removed, a carriage return keeping what follows it, secrets masked by the telemetry masker, clipped at a character with ...; oklm_jobs_last_line(), which ProcessList uses too).

Monitors and events (events.h): the Monitor tool watches a command of its own (tail -F build.log, a test watcher; a job of kind monitor, decided by Bash's rules) or a job already running (attach_to, from its next line on; a read of that job's output, so a bare Bash deny rule, which refuses Monitor's commands, lets it attach and Monitor stays offered, while a Monitor deny rule refuses both and leaves it out of the tools); the lines its filter matches become events. Lines within batch_ms (1 s) make one event, showing the last five ([event] monitor 2 (test failures): 12 new lines, the last ones: ...); past max_per_minute (30) a batch is dropped and counted in the next event; a line matching stop_when ends the monitor and stops its own job; the job's end ends it too, said in an event. Jobs that end are events as well (their details come with the agent's job notes).

  • While the agent works, the events are told at the next turn's start, as short notes.
  • While it waits for the user, the prompt looks at them twice a second; one wakes the agent with a turn of its own, shown as (woken by a background event), what was typed kept for the next prompt (events.wakeOnEvents, on by default). At most events.maxWakeupsPerHour (10) wakeups an hour, then events wait for the next message; a monitor that wakes the agent three times in a row comes with a note to stop it.
  • Headless, the run goes on while monitors watch or wakeups are scheduled: each event is a turn with its own result, until no monitor watches, no wakeup waits and no event is left (ten minutes or the hour's cap at most).

Wakeups: the ScheduleWakeup tool (deferred by default) schedules a [wakeup N] MESSAGE event in delay_seconds (at least events.minWakeupSeconds, 60; at most a day); cancel removes one, or all with -1. A wakeup wakes the idle agent like an event, shown as (woken by a wakeup it scheduled), without counting against the hour's cap, since the agent asked for it. /tasks lists those still waiting; they end with the session.

Loops: /loop [interval] [prompt] (/proactive) runs a prompt again and again while the session is open. With an interval (30s, 5m, 2h, 1d; minutes without a unit; at least events.minWakeupSeconds) the prompt is sent at once, then each time the interval has passed and the agent is idle. Without one the model paces the loop: each round ends with an instruction to call ScheduleWakeup for the next, and the wakeup brings the prompt back; a round that schedules nothing ends the loop. Without a prompt, .oklm/loop.md, else the loop.defaultPrompt setting, else a maintenance round (the work tree, the jobs, the task list; small fixes only). /loop shows it, /loop stop ends it and cancels its wakeups. Piped input is read unbuffered so that loops and wakeups run between its lines too.

tools/check_events.sh scripts it without a model: a monitor's two error lines come back as one event and one turn, its end as another, three results in all. Checked on a terminal through a pseudo-terminal too: the agent woke for the burst and for the end.

Waiting instead of sleeping (probe.h): a readiness probe is a port that accepts connections, an HTTP answer of a status class ("2xx|3xx"), a line of a job's output matching a regular expression (read from the job's start, so a line printed before the wait counts), a command exiting as expected, a delay, or all / any of several. It is checked every 200 ms until it passes, times out (120 s), or the job it watches ends first, which fails the wait at once; a failure says why and gives the job's last 30 lines. Before waiting for a port of a job, a port another process already holds is named (node (pid 4411), read from /proc/net/tcp and the processes' descriptors), since the probe would pass for the wrong reason. oklm_job_ports() gives the ports a job's processes listen on, in its own network namespace when the sandbox gave it one (whose ports the host cannot reach: a timeout says so).

The model's tools for jobs: Bash with run_in_background starts one and answers with its id and its log; ProcessOutput gives what a job wrote since the model last read it (filter, tail; the job's state, how many lines were left out and the log's path); ProcessStop stops one or several (ids, grace_ms); ProcessList (deferred) lists them with their kind, command, label, state, ports and last line. The spec's BashOutput and KillShell (with bash_id, shell_id) are read as ProcessOutput and ProcessStop; JobOutput (by byte offset) and JobKill still answer, no longer offered.

Moved to the background: a foreground Bash command still running at its timeout is not killed but becomes a job (moved to the background): its output so far is in the answer, ProcessOutput reads what follows, and the model is told its id (processes.autoBackgroundOnTimeout, on by default; a command starting with sleep is stopped as before; Windows stops it too). On the terminal, Ctrl+B moves the command running now the same way. The persistent shell's state is saved when such a command ends, whenever that is.

PowerShell (deferred): a command run by pwsh (Windows PowerShell when pwsh is missing on Windows) from a script file under .oklm, with Bash's rules (PowerShell(...) rules, the same splitting and dangerous patterns), its timeout and background mode; where PowerShell is not installed it says so.

/tasks (/jobs, /bashes) lists the jobs as ProcessList does and the background agents running; /tasks stop N stops one, /tasks output N shows what it wrote since the user last looked (the model's place is its own), /tasks reap stops what earlier sessions left running. In the full-screen UI /tasks is an interactive panel (follow, stop, restart, keep; § Terminal UI).

The WaitFor tool takes the job's id and port, http, log, command, or a combined probe, and a timeout; it answers Ready after 1.4 s; job 3 listens on port 5173., or Not ready: with the reason and the job's last lines. It asks nothing, so a command probe runs only a command an allow rule covers.

Tools the model has

Tool What it does
Bash with run_in_background Starts a job and answers at once with its id; a foreground command past its timeout moves to the background instead of dying (Ctrl+B does it by hand). The same command already running in the same directory is reused.
ProcessOutput The job's new output since this reader's last read, with filter and tail.
ProcessStop Stops jobs, after a grace (their stop command first).
ProcessList The jobs: id, kind, label, state, time, ports, last line. Deferred.
WaitFor Waits for a port, an HTTP answer, a log line, a command, or all / any of them, failing at once when the watched job ends.
Monitor Watches a command's or a job's lines matching a filter: they become events, batched and rate-limited, told at the next turn or waking the idle agent.
ScheduleWakeup Wakes the agent later in the session with a message (loops, checking a build). Deferred.
Service Starts, stops, restarts or lists the project's declared services. Deferred; asks unless a rule allows Service.
LSP Asks the language server: definitions, references, hover, symbols, calls, diagnostics, a rename preview. Deferred.
PowerShell Bash's contract for pwsh. Deferred.
mcp__SERVER__TOOL, ListMcpResources, ReadMcpResource The MCP servers' tools and resources.

Commands the user has

/tasks (jobs, wakeups, loops, background agents and sessions; stop N, output N, reap; in the full-screen UI an interactive panel: Enter follows a job's output, s stops, r restarts a service or a job with a restart policy, k keeps it running at exit, q closes), /services, /mcp, /loop, /schedule, /background, /fork, /status, /doctor. Outside a session: oklm agent agents | attach | send | stop, oklm agent mcp ....

The status line counts the jobs running and, in red, the long-lived processes that failed (a service, a language server, an MCP server); a status line command gets them as jobs.running and jobs.failed.

In a headless run with --output-format stream-json, each process's start and end are {"type":"system","subtype":"process_started"|"process_exited"|"process_ready",...} lines (its id, kind, label, command, state, exit code; a ready service's name, pid, ports and probe), the events that reach the model monitor_event (or wakeup) lines, and the user's notices notification lines.

Events and hooks

Monitors' batches, jobs that end, wakeups due, MCP servers that crash or come back are told to the model. A job's end note says how it ended and its last non-empty line (clipped, secrets masked).

The user is told once, in the terminal with a notification, when a job crashes (an exit status other than 0 or a signal, not a stop the agent or the user asked for), when a service's readiness probe fails (timed out, or its process ended first), and when a background agent finishes, each with its label and the reason; the model hears of the same at its next turn (its job notes, the agent's report, the tool's result, or a [notice] line among the events for a service started with the session).

Hooks: ProcessStart and ProcessExit (matched on the kind), MonitorEvent (a block drops the events before the model sees them), ServiceReady (a declared service passed its readiness probe: its name, job id, pid, ports and probe; matched on its name).

Declared services

.oklm/services.json describes the development stack once: each service with its command, directory, dependencies, ports, readiness probe, monitor and stop command. Starting one starts what it depends on first, each waited for; a port held by another process is named (Linux from /proc; Windows from GetExtendedTcpTable's owning process ids, cross-compiled, untested on Windows; macOS from libproc's socket descriptors, never compiled); autostart only in a trusted folder (details below).

A service may cap what its processes use together: "resources": {"memLimit": "512M", "cpuLimit": 1.5} (bytes, or a number with K, M or G in powers of 1024; CPUs). On Linux with cgroups v2 and systemd's user manager, its job runs in a cgroup of its own (systemd-run --user --scope, memory.max with no swap, cpu.max); past its memory the kernel kills it. On Windows its Job Object carries them (JOB_OBJECT_LIMIT_JOB_MEMORY, the smaller of the sandbox's memory limit and the job's; a hard CPU rate, JOBOBJECT_CPU_RATE_CONTROL_INFORMATION, in hundredths of a percent of all the processors, from Windows 8); past its memory the job's allocations fail. A detached job with limits gets a Job Object for them that does not kill it at close. This is cross-compiled, untested on Windows. Elsewhere the job runs without the limits, which the log says (oklm_job_spec.mem_limit, cpu_limit; oklm_jobs_limits_available(), oklm_job_info.limited).

Declared services in detail

include/oklm/harness/services.h, src/harness/services.c, over the jobs (kind service), the readiness probes and the events.

  • The file: .oklm/services.json (else .agent/services.json), {"services": {NAME: {"command", "stop", "cwd", "dependsOn": [...], "ports": [...], "readiness": PROBE, "monitor": REGEX, "autostart"}}}; a service without a command or an unknown dependency is left out and said; a cycle of dependsOn declares none.
  • Starting a service starts what it depends on first, in order, each waited for with its readiness probe (WaitFor's form: port, http, log, command, delay, all / any); one running already is left alone; a declared port held by another process stops it with the holder named (port 5173 is in use by node (pid 4411); on Windows from the TCP tables' owning process ids, node.exe (pid 4411), System (pid 4) for http.sys, cross-compiled and untested on Windows; on macOS from libproc, the user's own processes, never compiled; elsewhere only whether it answers); a service that dies before it is ready fails at once with its last lines. A monitor attaches a Monitor to its output (service NAME), its lines events. Stopping one stops those running that depend on it first, then it (its stop command, then its process group).
  • The session: the services are read at the start; those with autostart (true unless false) start then, only in a folder the user trusts (processes.autostartServices, on by default). The Service tool (deferred by default; action start, stop, restart or status) asks like any tool unless a rule allows Service. /services lists them (state, job, command, dependencies, ports), and /services start|stop|restart|logs NAME. /init proposes a services.json when the project has a package.json, compose file, Procfile or Makefile and none yet, written only if the user agrees. The jobs stop with the session.

Language and MCP servers

Language servers start when a file of theirs is read and report the new errors an edit made. MCP servers come from the settings, .mcp.json (approved once) and --mcp-config, over stdio or Streamable HTTP; their tools, resources and prompts join the session. See agent-extensions.md.

Language servers

include/oklm/harness/lsp.h, src/harness/lsp.c, over include/oklm/harness/jsonrpc.h (JSON-RPC 2.0 with Content-Length or line framing, shared with the MCP client).

  • Servers: clangd for C and C++, pyright for Python, typescript-language-server, rust-analyzer, gopls; the lsp setting adds or replaces ({"zig": {"command": ["zls"], "extensions": [".zig"]}}), lsp.enabled: false turns them off. A server starts the first time a file of its language is read or edited, as a background job of kind lsp whose standard input and output are the connection's pipes (a piped job: no wrapper shell, its errors in its log), initialized with the project as its root; it is asked to shut down, then stopped, at the end. A server not installed is told once (LSP: clangd is not installed...), and nothing waits for it.
  • Sync: Read opens the file in its server (didOpen; didChange when its text changed since); Write, Edit and MultiEdit send the new text and didSave.
  • After an edit, the agent waits up to lsp.diagnosticsWaitMs (1.5 s) for the diagnostics of the version it sent (servers say which version they answer), and adds to the tool's result the errors and warnings of that file it did not report before, ten lines at most: LSP: 1 new error: then main.c:3:19 incompatible pointer to integer conversion.... An edit that leaves an old error adds nothing.
  • The LSP tool (deferred; Read's permissions): definition, references, hover, documentSymbols, workspaceSymbols (query), implementation, incomingCalls, outgoingCalls, diagnostics, rename (a preview of the places a new name changes; the edits are made with Edit). Lines and columns count from 1; answers are path:line:col with the line's text, 50 at most.

Integrations

Each integration is a built-in skill the model finds with ToolSearch when a task needs it (not listed in the prompt), plus checks that ask before a command acts on something beyond the machine's files.

Integration Skill What asks, whatever the rules
Docker / Podman docker system prune, volume rm, rmi, image rm/prune, --privileged, mounting / or the Docker socket, --network host; a container past processes.maxContainers (10). The session's containers (label oklm.session=$OKLM_SESSION_ID, compose project oklm-$OKLM_SESSION_ID) stop with it.
Dev servers dev-server — (a running copy is reused)
Databases database The skill asks before DROP, TRUNCATE, unqualified DELETE or UPDATE, and remote connections.
Browsers playwright — (localhost by default)
Kubernetes kubernetes Every kubectl or helm call on a context that is not a local cluster (kind-*, minikube, k3d-*, docker-desktop, rancher-desktop, orbstack, kubernetes.allowedContexts), naming it; kubectl delete, helm uninstall, cluster deletion.
Android android adb on the default device, with -d or on a serial that is not an emulator's; fastboot; adb uninstall on a device.
Virtual machines vms A second VM or emulator while one runs; vagrant destroy, multipass delete.
Clouds cloud Anything but reads with aws, gcloud, az, terraform, tofu, pulumi and the hosting CLIs (cloud.readOnly, true by default).
Tunnels tunnels Every tunnel, saying what it exposes (ngrok, cloudflared, localtunnel, ssh -R).

iOS simulators are out of scope (macOS only). /doctor says when docker is installed but its daemon does not answer.

Integrations in detail

Built-in skills the model finds with ToolSearch when a task needs one (counted in the prompt, not listed, so a small model's prompt stays as short as before them): docker (compose stacks named oklm-$OKLM_SESSION_ID, one-off containers labelled oklm.session=$OKLM_SESSION_ID and published on 127.0.0.1, health, logs through Monitor, exec without -it, the dangerous forms), dev-server (the command from services.json or the project, a running copy reused, WaitFor its ready line, Monitor on its errors), database (containers with ephemeral data, the readiness commands, what to ask before running), playwright (screenshots, the page's text and console errors through a small script, test runs in the background). Every command gets OKLM_SESSION_ID; when the session ends, the containers labelled with it (docker or podman) are stopped, their volumes kept. Deleting images (rmi, image rm|prune) and --network host ask whatever the rules, like the other container dangers. Two more skills, kubernetes (a kind cluster of the session's, rollouts, logs and events through Monitor, port-forward as a job) and android (a headless emulator, boot readiness, install and input, logcat, screenshots, the UI tree). Before a command runs, devices.h reads what it acts on: a kubectl or helm call whose context (its --context or --kube-context, else kubectl config current-context) is not a local cluster (kind-*, minikube, k3d-*, docker-desktop, rancher-desktop, orbstack, or processes.kubernetesContexts) asks, naming the context; an adb call on the default device (unless ANDROID_SERIAL names an emulator), with -d or on a serial that is not an emulator's asks, and so does fastboot. Cloud CLIs are read-only unless asked: aws, gcloud, az, terraform, tofu, pulumi and the hosting CLIs run their reads (describe, list, get, show, ls, plan, validate, preview, output...) under the usual rules, and anything else asks whatever the rules. A tunnel asks saying what it exposes (exposes local port 3000 to the internet through ngrok, a Cloudflare tunnel's URL, localtunnel, an ssh -R forward). The vms (QEMU with QMP and a console log, Vagrant, Multipass, Lima), cloud (the identity first, reads free, plans shown before applying, no secrets printed) and tunnels skills complete them. Starting a second virtual machine or emulator while one runs as a job, or a container while processes.maxContainers (10) run, asks. cloud.readOnly: false lets the cloud CLIs' changes follow the rules; kubernetes.allowedContexts adds safe contexts. OKLM_DISABLE_BACKGROUND_TASKS refuses background jobs. /doctor says when docker is installed but its daemon does not answer. A background command already running in the same directory is reused rather than started twice.

Settings

processes.* (maxConcurrent, defaultGraceMs, logRetentionDays, autoReapOrphans, autoBackgroundOnTimeout, autostartServices, maxContainers), events.* (wakeOnEvents, maxWakeupsPerHour, minWakeupSeconds), lsp.*, mcp.* (connectTimeoutMs, callTimeoutMs, maxOutputChars, deferAboveTokens), mcpServers, kubernetes.allowedContexts, cloud.readOnly, git.worktree.copy and git.worktree.symlink. The environment: OKLM_SESSION_ID (given to every command), OKLM_DISABLE_BACKGROUND_TASKS (refuses background jobs).

Not built yet

CPU and memory per job, the identity reminder for clouds and credential redaction, parsing a tunnel's public URL. --keep-services leaves the service, LSP and MCP jobs running at exit (beside processes.keepOnExit, which keeps every job). The emulator checklist runs on a real emulator with tools/check_emulator.sh (an AVD and the SDK's build-tools needed). tools/check_docker.sh runs the container side against a real Docker daemon: a container and a compose stack of the session stopped at its end with their volumes kept, an image deletion asking and the image staying, /doctor quiet about the daemon. It prints SKIP and exits 0 when docker is not installed, its daemon does not answer or no small image (busybox) is there or can be pulled.