Oak: A Version Control System Reimagined for AI Agents 🌳

Oak is a specialized alternative to Git, engineered specifically to serve as the foundational substrate for autonomous agents. It moves beyond traditional versioning to provide a "space" where agents can operate efficiently across multiple repositories.

🛠️ Core Command Suite

The Oak CLI provides a streamlined interface for both humans and agents to interact with codebases.

Command	Action	Nuance
`oak clone <repo>`	Duplicate	Standard repository retrieval.
`oak clone <repo> <branch>`	Feature Branch	Clones directly into a local feature branch.
`oak mount <repo>`	Lazy Load	Creates a virtual working tree $\rightarrow$ no full clone required.
`oak space new <name>`	Org Space	Initializes a multi-repo agent environment for an organization.

🔄 The Agentic Workflow

Unlike human developers, agents require strict contracts to ensure they don't corrupt the main codebase or leave "ghost" changes.

📋 Agent Finishing Checklist

To maintain repository integrity, agents must adhere to the following:

No Mutation of canonical checkouts.
No Local-Only checkpoints (must be visible to reviewers).
Commit all changes.
Describe the work performed.
Push to a reviewable branch.

📈 Recent Evolution & Changelog

Oak has undergone rapid iteration, moving through versions v0.98.0 and v0.99.0. The development focus has shifted toward agent-native launch contracts and system hardening.

🛡️ Security & Validation

The system now aggressively rejects malformed data to prevent injection or filesystem errors:

Identity Protection: All control characters are now rejected in org/repo specs, commit identity fields, and oak site organization slugs.
Filesystem Integrity:
- .oak markers must be directories.
- Tree entry filenames cannot contain control characters.
- SQLite database permissions are hardened to $\text{mode} = 0600$ .
API Safety: Organization slugs are validated before being used as API identifiers.

🤖 Agent-Specific Logic

The "Launch Contract" ensures agents behave predictably:

The Finish Saga: The finish process is now a retryable sequence (rather than rollback-atomic) that preflights authentication and remote reachability before any local mutation occurs.
State Management: recommended_action.kind is now a closed enum to prevent agent hallucination.
Scale Gates: Implementation of $n10/n100$ scale gates for branch review and triage.
Isolated Workers: Explicit rules now forbid agents from mutating canonical checkouts.

⚡ Performance & Compatibility

Windows Support: The Oak CLI now builds and runs natively on Windows.
Lazy Loading: Large-repo mount startup is now root-only and lazy over committed trees.
Git Integration:
- Accelerated git import speeds.
- CI fallback identities allow reflog writes even without user.name or user.email configured.
- oak merge can now handle main-parent branches without requiring a checkout hop.

🎨 UI & UX

Visual Identity: The macOS app icon has been updated to a pixel-art compass mark.
Design Language: Browser login pages now follow the oak.space black-and-white aesthetic.
Accessibility: Added a high-contrast app icon.

⚙️ Technical Implementation Details

Release Proofing

The team has refined how releases are verified. ~~Manual proof via oakvcs-cli cargo publish --dry-run~~ $\rightarrow$ New non-mutating release-proof target.

This new workflow:

Encodes the correct core dry-run.
Uses a CLI build proxy.
Verifies version lockstep.
Ensures release signing is explicit and "fail-closed."

Code Quality

The project maintains strict adherence to Rust standards:

// Example of the internal focus on formatting and imports
// Reordered imports in merge.rs and review.rs to satisfy rustfmt
use oak_core::vcs::merge;
use oak_core::vcs::review;

Toolchain: Pinned to 1.94 for cargo fmt --all --check.
Pathing: Fixed repo-relative path resolution for .. paths to preserve symlink boundaries.

Summary of Recent Merges

Feature/Fix	Author	Timeline
Windows CLI Build	`zdgeier`	16hr ago
SQLite Permission Hardening	`zdgeier`	19hr ago
Agent Action Metadata Module	`mrmrs`	1d ago
v0.99.0 Release	`zdgeier`	1d ago
Virtual Branch Naming	`zdgeier`	3d ago
M1 Agent Launch Contract	`mrmrs`	5d ago