OKLMdocumentation v1.0.3
On this page

Git design

How git_spec.md maps onto OKLM. What exists, with evidence, is the "Git" section of gap-analysis.md: the harness has no git code yet, so this is mostly new code on existing foundations.

Status: accepted (the spec's G0); the four decisions below taken on 2026-11-03 as proposed; G1 to G3 done.

Principles

  • Git through the git command, run like any Bash call (permission rules, sandbox, jobs for long operations); no library.
  • One module, src/harness/git.c, for what the harness itself needs from git: detection, the snapshot, the classifier, the pre-commit checks, the worktrees. The model's own git work stays Bash calls.
  • The commands of §11 are prompt commands and skills in the commands framework (commands_spec.md), with their steps written here.

Section by section

§ Existing New code
1.1 Detection git.c: rev-parse at start (and after /cd), default branch, remotes and hosts, operations in progress, conventions from the last 50 commits, cached per repository.
1.2 Snapshot agent.c render Computed once in oklm_agent_new and appended to the system text (stable for the KV cache); a reminder when the branch or HEAD changes, through the event queue of process-design.md.
1.3 Status line view_status Branch, ahead / behind, dirty, operation in progress, in the agent specification's status line.
2 Classifier permissions.c check_bash, util.c sh_split A git normalizer (drops global options -C, -c, --git-dir, environment assignments and redirections) and a classifier: read-only (allowed, plan mode included), mutating local (asks unless a rule allows), dangerous (asks even when a rule allows: a pass after the rules turns allow into ask), never (refused). The table lives in permissions.c next to the rules; settings can extend it.
2.4 Environment process.c, jobs.c spawning GIT_EDITOR=true, GIT_SEQUENCE_EDITOR=true, GIT_PAGER=cat, PAGER=cat, GIT_TERMINAL_PROMPT=0 for every command (Linux and Windows).
2.5 Pre-commit checks git.c: secret patterns over the staged diff (and gitleaks when installed), large files, unwanted files; staging limited to the files the agent edited (the agent specification's checkpoint registry) or named by the user.
3, 4, 6 Commits, branches, conflicts The steps in the system prompt's git part and in /commit; protected branches and conventions from settings; interrupted operations reported at start.
5 Hosts Gitea first: its REST API through src/client/ with the token from git's credential helper (never printed), or tea when installed; GitHub through gh. A fake host for tests.
7 Archaeology skills A git-history skill shipped with OKLM.
8 Review sub-agents /diff (the session's edits against the user's), /code-review with parallel reviewer sub-agents (needs the agent specification's parallel foreground calls and agent types), /security-review, /simplify.
9 Worktrees git.c: create under .oklm/worktrees/<name> on oklm/<name>, the worktree's git common directory added to the sandbox's writable set, isolation: "worktree" on the Agent tool, cleanup without force.
12 Settings git.* keys in the agent specification's settings module.
13 CI .gitea/workflows/ci.yml A Gitea Actions template running oklm agent -p on a self-hosted runner.

Decisions

Taken on 2026-11-03, each as proposed (the network one waits for the per-job network permission, needed by push and fetch in G4 and G7):

  1. Network in the sandbox. Fetch, push and host access fail in a sandboxed session without --allow-network. Proposed: the per-job network permission of process-design.md (a question unless a rule allows git push / git fetch to reach the network).
  2. Plan mode. Proposed: classified read-only git commands run in plan mode (today every Bash call is denied there).
  3. Trailer setting name. The spec says git.coAuthor and git.coAuthorTrailer; proposed: git.coAuthorTrailer.
  4. Gitea access. Proposed: the REST API with the credential helper's token, tea when present.

Order

G1 to G3 after the agent specification's M4 to M6 (permissions, settings, prompt); G5 needs its sessions; G7 the host decision; G8 and G9 its sub-agent work (M12).