Git Integration
Relevant source files
The following files were used as context for generating this wiki page:
Git Integration in the OCX ecosystem provides a robust framework for managing isolated development environments, tracking changes, and maintaining project history through automated workflows. The primary purpose of this integration is to enable AI agents to operate within safe, isolated "worktrees" while adhering to standard version control practices like conventional commits and systematic reviews.
The scope of Git Integration covers the creation and lifecycle management of git worktrees, automated commit message generation, and specialized agent permissions for interacting with repository metadata and history. Sources: facades/opencode-worktree/README.md, workers/kdco-registry/files/agent/scribe.md
Isolated Development with Worktrees
The opencode-worktree system allows for the creation of isolated git worktrees that spawn dedicated terminal sessions. This architecture prevents context switching and ensures that AI experimentation does not affect the main working directory until changes are ready to be finalized. Sources: facades/opencode-worktree/README.md:1-25
Worktree Lifecycle
Worktrees follow a specific lifecycle managed by the worktree_create and worktree_delete tools. When a worktree is created, it is stored in a centralized directory outside the main repository, typically at ~/.local/share/opencode/worktree/<project-id>/<branch>. Sources: facades/opencode-worktree/README.md:46-60
The diagram shows the transition from a standard repository to an isolated terminal session and the eventual automated cleanup. Sources: facades/opencode-worktree/README.md:46-55
Configuration and Tooling
| Tool | Description |
|---|---|
worktree_create | Creates a new git worktree and opens a new terminal with OpenCode. |
worktree_delete | Commits changes with a snapshot message and removes the worktree. |
getProjectId | Uses the git root commit hash to generate a unique project identifier for storage paths. |
Sources: facades/opencode-worktree/README.md:83-93, workers/kdco-registry/files/plugin/workspace-plugin.ts:405-410
Automated Commits and Documentation
Git Integration includes specialized behavior for the scribe agent, which is responsible for maintaining the human-facing history of the repository. Sources: workers/kdco-registry/files/agent/scribe.md:1-10
Conventional Commits
The system enforces the use of the Conventional Commits format to ensure a clean and readable history. The scribe agent follows this structure:
type(scope): description
[optional body explaining WHY]
[optional footer with breaking changes]
Supported types include feat, fix, docs, style, refactor, test, and chore. Sources: workers/kdco-registry/files/agent/scribe.md:38-48
Review and Audit Integration
Before git changes are merged or finalized, the system integrates a review protocol handled by the reviewer agent. This agent utilizes git metadata to perform its audit. Sources: workers/kdco-registry/files/agent/reviewer.md:1-15
Git-Based Review Tools
The Reviewer Agent is granted specific authorities to interact with the git filesystem to provide high-confidence feedback. Sources: workers/kdco-registry/files/agent/reviewer.md:88-95
git diff: Analyzes the specific lines changed in the current session.git log: Reviews the history of a file to understand context.git show: Inspects specific commits or objects.
The sequence shows how agents interact with the Git System to validate changes before reporting completion. Sources: workers/kdco-registry/files/agent/reviewer.md:17-30, workers/kdco-registry/files/plugin/workspace-plugin.ts:601-615
Workspace Routing and Boundaries
The workspace-plugin enforces strict boundaries regarding how agents interact with the codebase vs. external resources. Sources: workers/kdco-registry/files/plugin/workspace-plugin.ts:490-505
| Agent | Git/Codebase Scope | Description |
|---|---|---|
explore | Internal Only | Authorized to search codebase files and trace logic within the git repository. |
researcher | External Only | Forbidden from searching codebase files; focuses on external docs and APIs. |
coder | Internal/Write | Authorized to modify files but never allowed to perform git commits/pushes directly. |
Sources: workers/kdco-registry/files/plugin/workspace-plugin.ts:494-515, workers/kdco-registry/files/agent/coder.md:65-75
Repository Metadata for Context
The project uses git metadata to maintain session consistency across different environments. For example, the projectId is derived from the git root commit hash, ensuring that even if a user moves between different worktrees or clones of the same project, the configuration and implementation plans remain linked to the correct repository. Sources: workers/kdco-registry/files/plugin/workspace-plugin.ts:405-410, AGENTS.md:135-145
Git Integration provides a seamless bridge between raw version control and automated AI workflows, ensuring that isolation, documentation, and review are handled systematically without manual developer intervention.