OKLMdocumentation v1.0.3
On this page

Git with the OKLM agent

What oklm agent knows and does in a git repository, and what it asks before doing. The design is in git-design.md, the details in agent-tools.md.

Status: maintained.

What it knows

At the start of a session the prompt holds a snapshot: the branch, the default branch, the status, the last commits, how commit messages and branches are written here, the hooks a commit runs, an operation in progress (merge, rebase, cherry-pick, bisect), and whether the clone is shallow, has submodules or LFS paths. With LFS paths (a filter=lfs in .gitattributes), it says whether git lfs is installed and, when it is, the LFS objects not pushed yet (git lfs status) and the files only present as pointers, not pulled (git lfs ls-files). A HEAD that moves during the session is told.

The status line before the prompt shows the branch with its marks: ↑2 commits ahead of the upstream, ↓1 behind it (as of the last fetch), * when files are changed or untracked; main ↑2 *. They are read with one git status after each line you send or ! command, never while you type, and a statusLine.command gets them as git.ahead, git.behind and git.dirty.

The agent's own state stays out of the status: .oklm/audit, jobs, sessions and worktrees each hold a .gitignore of * (oklm_git_ignore_dir()), so the snapshot does not show a clean tree as dirty and a commit does not pick them up; the project's own .oklm files (settings, skills, agents) show as usual.

What it does without asking

Reading: git status, diff, log, show, blame, branch, stash list, gh pr view, gh pr checks..., in every mode.

What asks

Changing: commits, branches, merges, rebases, pushes, gh pr create (rules can allow them: Bash(git commit:*)). And whatever the rules: a force push, reset --hard, clean -f, branch -D, discarding changes, amending or rebasing pushed commits, --no-verify, a push to the default or a protected branch (git.protectedBranches), switching branches with uncommitted changes, deleting a remote branch, publishing. Interactive commands (rebase -i, add -p) are refused with what to do instead; nothing waits for an editor or a password.

Commits

Only when asked (or /commit): the change's files staged by name, the user's unrelated files left alone, a message in the repository's style, the hooks' failures fixed and retried (three times at most), secrets blocking the commit, large or unwanted files told. git.coAuthorTrailer adds a trailer. When the repository has a CODEOWNERS file (.github/CODEOWNERS, else the top's, else docs/CODEOWNERS), /commit and /pr are told the owners of the files the session edited (the last matching pattern wins), to name them in the report or as the pull request's reviewers.

Branches, conflicts, history

New branches named like the repository's; conflicts resolved from both sides' intent, asked when both changed behavior; /bisect (the bisect is reset when the request ends); the git-history skill for why, when and by whom.

Reviews and pull requests

/diff (the agent's changes marked; stage, unstage, revert, open), /code-review [level] (review.defaultLevel when no level is given), /security-review, /simplify, /ultrareview, /pr, /autofix-pr. Sandboxed commands have no network: /sandbox network on lets a push and gh reach the host.

Worktrees

oklm agent --worktree NAME works on a branch of its own in .oklm/worktrees/NAME; sub-agents can each get one (isolation: "worktree"), which is removed when they changed nothing; /batch splits a large change across them. /doctor lists the worktrees left.

Mid-session, ask the agent to work apart: its EnterWorktree tool moves the session into a new worktree, and ExitWorktree comes back, keeping the worktree, removing it (with work in it, only once you agreed), or merging its commits into the branch you are on (into a protected branch, you are asked first). One left untouched at the end of the session is removed.

{ "git": { "worktree": {
    "copy": [".oklm/settings.local.json", ".env.local"],
    "symlink": ["node_modules"],
    "setup": ["npm ci"] } } }

A new worktree gets copies and links of git-ignored files, then the setup commands run in it. A WorktreeCreate hook replaces git (it is given the name and prints the path it made: jj, hg or p4 worktrees), a WorktreeRemove hook removes what it made.

CI

oklm agent -p TASK --output-format json in a pipeline; /install-github-app writes a workflow for a self-hosted runner.

Large and unusual repositories

A shallow clone's history is incomplete (said; git fetch --unshallow only with your word); a change in a submodule is committed there first; LFS paths stay in LFS. Slow git commands time out instead of hanging.