Oak vcs

Oak VCS

Overview

Oak is version control at the speed of agents. It is a Git replacement built around branch-per-session work, messageless local checkpoints, explicit publishing, stable machine-readable output, and content-addressed lazy mounts.

Never run git in an Oak repository. An Oak repository has a .oak/ directory at its root and normally no .git/. Creating or using a Git repo inside it introduces a conflicting source of truth.

Before version-control work, detect the repository and inspect its live state:

# Run from the working directory or a subdirectory.
oak info --json
oak agent state --json --compact

If Oak is unavailable, report that directly and direct the user to the official installation page at https://oak.space/install. Source installations can use cargo install oakvcs-cli. Always trust the installed CLI's oak --help and oak <command> --help over stale examples.

When to Use

Use this skill when:

• the working tree or an ancestor contains .oak/;
• the user requests status, diff, commit, branch, push, pull, merge, clone, history, review, or recovery in an Oak repository;
• the user mentions Oak, oak.space, oak mount, an Oak space, or a virtual branch;
• an agent must finalize or publish work from an Oak branch or mount.

Do not use Git workflows in Oak repos. For an actual .git/ repository with no .oak/, use the normal Git/GitHub workflow instead.

Mental Model: Differences from Git

1. No staging area. There is no add or index. oak commit checkpoints all working-tree changes, or only explicitly supplied paths.
2. No commit messages. oak commit -m is invalid. The branch description is the work's narrative and becomes the squash-merge message. Set it with oak desc "..." or oak desc --file FILE.
3. Flat branches. Every branch parents directly onto main; branches are not stacked on other feature branches.
4. Local checkpoints. oak commit never publishes unless --push is explicitly supplied. Publish with oak push, oak commit --push, or oak finish.
5. Server-side, CI-gated merge. oak merge squash-merges into the parent.
6. No stash. oak switch -c carries dirty files onto the new branch; --clean discards them and starts from fresh main.
7. Parallel tasks use lazy mounts. oak mount is the Oak equivalent of a lightweight, agent-oriented worktree.

Core Workflow

Inspect and checkpoint:

oak status --json --compact
oak diff --json                         # summary, non-interactive
oak diff --json --hunks --max-bytes 60000
oak diff --branch --json                # whole branch vs fork point
oak commit --json --quiet               # local checkpoint only
oak commit path/to/file path/to/dir     # selective checkpoint

Start or switch work:

oak switch -c fix-auth-redirect         # named branch, preserves dirty files
oak switch -c                           # generated branch name
oak switch -c --clean                   # discards dirty files; use cautiously
oak switch existing-branch
oak pull                                # fetch branch, then merge in parent
oak fetch                               # refresh local main only

Describe and publish:

oak desc "Add rate limiting to auth endpoints"
oak push
oak commit --push --json --quiet        # checkpoint and publish explicitly

For a fresh local repo's first non-interactive publish:

oak push --repo ORG/REPO

Finishing Agent Work

When work is complete, leave it reviewable and server-visible with oak finish. Write a meaningful branch description explaining what changed and why; it becomes the squash-merge message.

Use the Hermes file-writing tool to create the description file rather than a shell heredoc when available, then run:

oak finish --desc-file /tmp/oak-desc.txt --json

oak finish preflights, saves the branch description, checkpoints dirty work, and publishes. It is a retryable saga, not a rollback-atomic transaction. If a phase fails, inspect the JSON's completed phase and recommended_next_commands; run the exact suggested command instead of restarting or guessing.

Do not merge a branch unless the user explicitly asks to land it. Finishing or pushing makes work reviewable; merging changes the parent/main branch.

Machine-Readable Output Contract

Prefer JSON for unattended agent work: status, diff, log, commit, branch, merge, ci, finish, and agent state expose machine-readable forms.

• Schemas are append-only within a schema_version; ignore unknown fields.
• Missing optional fields mean their documented default.
• Prefer exact commands in recommended_next_commands over invented flags.
• Paged results include a ready-to-run next_page_command.
• Bounded diff output reports truncation through fields such as hunks_truncated and patch_omitted.

Useful forms:

oak agent state --json --compact [--refresh]
oak status --porcelain
oak diff --exit-code
oak commit --json --quiet
oak diff BRANCH --json --hunks --max-bytes 60000
oak diff BRANCH --json --hunks -- path/to/file

Global exit codes: 0 success, 1 generic failure, 2 usage, 3 locked, 4 dirty tree blocked the operation, 5 conflicts, 6 network/server/auth. oak diff --exit-code returns 1 when differences exist. oak ci status uses 0 for passed, 1 for failed/no runs, and 3 for still running.

Avoid interactive forms in unattended execution:

Interactive command	Agent-safe form
oak diff	oak diff --print, --stat, --name-only, or --json
oak switch	pass a branch name or -c [NAME]
oak clone	pass ORG/REPO
oak split	pass --plan FILE or --plan -
oak reset / oak restore	inspect status, then pass -f only if intended
first oak push	pass --repo ORG/REPO

Environment variables: OAK_REMOTE overrides the server, OAK_REPO supplies ORG/REPO for first publish, and OAK_DIFF_TOOL replaces the interactive diff browser with a blocking external tool such as code --wait --diff.

Branch Inspection and Review

Review without switching:

oak branch list --json
oak branch --show-current
oak branch show NAME --json
oak branch review NAME --merge-preview --json
oak branch review NAME --remote --json
oak diff NAME --json
oak diff REV1 REV2 --json --hunks -- path/to/file
oak log -n 20 --oneline
oak log -S "symbol"

Unique commit hash prefixes of at least four hexadecimal characters are accepted where revisions are supported.

CI and Landing

Oak merges are server-side squashes. The branch description is the merge message, and the branch head must pass CI.

oak ci status --json
oak ci runs --limit 20 --json
oak ci logs RUN_ID --json
oak ci rerun RUN_ID --json
oak merge --dry-run --json
oak merge --wait --json
oak merge --wait=90 --json

When explicitly asked to land:

1. Run oak finish --desc-file ... --json to describe and publish.
2. Check oak ci status --json.
3. Use oak merge --wait --json to ride out running CI.
4. On failure, inspect logs. Fix code and publish a new head, or use ci rerun only for a genuine infrastructure flake.

oak merge --force bypasses the CI gate. Never use it as the first response to a failed/stuck gate; inspect evidence and require explicit user intent to land despite CI.

Conflicts and Recovery

Inspect before acting:

oak conflict status --json
oak conflict show --json
oak agent state --json --compact

Resolve markers manually or choose a complete side:

oak conflict take PATH --ours
oak conflict take PATH --theirs
oak merge --continue     # or oak pull --continue
oak merge --abort        # or oak pull --abort

--ours is the current branch; --theirs is the parent/remote side.

Destructive recovery requires prior inspection:

oak status --json --compact
oak reset path/ -f
oak restore path/to/file -f
oak restore -s COMMIT path/to/file -f
oak pull -f
oak push -f

State which side wins and why before force pull/push. oak pull -f discards local commits absent from remote; oak push -f overwrites divergent remote history.

Mounts and Spaces

A mount exposes a remote repository as a lazy virtual filesystem. Each mount has a virtual branch pinned for its lifetime; do not use oak switch inside a mount. Mount a second path for another branch.

oak mount ORG/REPO [DEST]
oak mount ORG/REPO DEST --branch NAME
oak mount list
oak finish --desc-file /tmp/desc.txt --json                 # inside mount
oak mount finish DEST --desc-file /tmp/desc.txt --json      # outside mount
oak mount end DEST
oak mount forget --force                                    # stale registry only

A space organizes one task directory with one mount per touched repository:

oak space new ORG [DIR]
oak space repos [ORG]
oak mount ORG/REPO ./task-slug/REPO
oak space clean [DIR]

Use a 2–4 word task-oriented kebab-case slug. Read each mounted repository's checked-in contributor and agent guidance; edit only inside its mount. Finish each repository separately. oak space clean skips mounts with uncommitted or unpushed work; --force discards them.

Keep build products and caches off mounts. Redirect Rust builds with CARGO_TARGET_DIR=/tmp/<name>. Run package installation/builds that create symlinks, hardlinks, target/, dist/, or cache trees on real disk rather than the mount.

Platform notes: macOS mounts use FSKit and require macOS 26+ plus the enabled Oak Mount app. Linux mounts use FUSE and require fusermount3/fuse3.

Git-to-Oak Quick Reference

Git habit	Oak equivalent
git status	oak status
git add	none; there is no staging area
git commit -m MSG	oak commit, then oak desc MSG
git switch -c NAME	oak switch -c NAME
git diff	oak diff --print or oak diff --json
git diff main...HEAD	oak diff --branch
git log	oak log
git push / pull / fetch	oak push / pull / fetch
merge a PR	oak merge (server-side, CI-gated)
git restore / hard reset	oak restore / oak reset -f
git stash	create branch with oak switch -c; dirty files follow
git worktree add	oak mount ORG/REPO DEST
git clone ORG/REPO	oak clone ORG/REPO
export to Git	oak export DEST

Common Pitfalls

1. Running Git in an Oak repo. Detect .oak/ and use Oak exclusively.
2. Trying oak commit -m. Commit first; describe the branch separately.
3. Assuming a checkpoint was published. Verify remote/pending state through oak agent state --json --compact or use oak finish.
4. Running bare interactive commands without a TTY.
5. Guessing recovery flags instead of following JSON recommendations.
6. Merging without explicit permission or bypassing failed CI prematurely.
7. Running build caches or dependency installs directly on a lazy mount.
8. Using oak switch inside a mount, which is pinned to one virtual branch.
9. Force-resetting, pulling, pushing, cleaning, or ending mounts before inspecting what would be lost.

Verification Checklist

• Confirmed the repository uses Oak and did not run Git.
• Read the repository's checked-in contributor and agent guidance.
• Used non-interactive/JSON forms for unattended commands.
• Inspected status and diff before checkpointing or discarding.
• Ran the project's real tests with build output off-mount if applicable.
• Wrote an accurate branch description.
• Used oak finish --json or otherwise verified work is published.
• Did not merge unless explicitly asked.
• Reported the branch, validation result, and any recommended next command.

For unlisted or version-sensitive flags, run oak <command> --help or consult https://oak.space/docs.