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.