agent-orchestrator/docs/pro/features/git-integration.md

Git Integration

This documentation covers Pro edition features available in the agents-orchestrator/agents-orchestrator private repository.

Git Integration provides two features: Git Context Injection (branch, commit, and diff information formatted for agent prompts) and Branch Policy (session-level protection for sensitive branches).

---

Git Context Injection

Purpose

Git Context Injection gathers repository state and formats it as markdown for inclusion in agent system prompts. This gives agents awareness of the current branch, recent commits, and modified files without requiring them to run git commands.

Context Gathering

The system collects three categories of information by invoking the git CLI:

Branch Information

• Current branch name (git rev-parse --abbrev-ref HEAD)
• Tracking branch and ahead/behind counts (git rev-list --left-right --count)
• Last commit on branch (hash, author, date, subject)

Recent Commits

• Last N commits on the current branch (default: 10)
• Each commit includes: short hash, author, relative date, subject line
• Collected via git log --oneline --format

Modified Files

• Staged files (git diff --cached --name-status)
• Unstaged modifications (git diff --name-status)
• Untracked files (git ls-files --others --exclude-standard)

Formatted Output

The collected information is formatted as a markdown section:

## Git Context

**Branch:** feature/new-dashboard (ahead 3, behind 0 of origin/main)

### Recent Commits (last 10)
- `a1b2c3d` (2 hours ago) fix: resolve null check in analytics
- `e4f5g6h` (5 hours ago) feat: add daily cost chart
- ...

### Working Tree
**Staged:**
- M src/lib/components/Analytics.svelte
- A src/lib/stores/analytics.svelte.ts

**Modified:**
- M src/lib/adapters/pro-bridge.ts

**Untracked:**
- tests/analytics.test.ts

Commands

pro_git_context

Gathers all git context for a project directory and returns formatted markdown.

Field	Type	Required	Description
cwd	String	Yes	Absolute path to the git repository
commitCount	u32	No	Number of recent commits to include (default: 10)

Response:

interface GitContext {
  markdown: string;      // Formatted markdown section
  branch: string;        // Current branch name
  isDirty: boolean;      // Has uncommitted changes
  aheadBehind: [number, number]; // [ahead, behind]
}

pro_git_inject

Convenience command that gathers git context and prepends it to a given system prompt.

Field	Type	Required	Description
cwd	String	Yes	Repository path
systemPrompt	String	Yes	Existing system prompt to augment
commitCount	u32	No	Number of recent commits (default: 10)

Returns the combined prompt string.

pro_git_branch_info

Returns structured branch information without formatting.

Field	Type	Required	Description
cwd	String	Yes	Repository path

Response:

interface BranchInfo {
  name: string;
  trackingBranch: string | null;
  ahead: number;
  behind: number;
  lastCommitHash: string;
  lastCommitSubject: string;
  lastCommitDate: string;
}

Implementation Notes

• All git commands are executed via std::process::Command (not libgit2). This avoids a heavy native dependency and matches the git CLI behavior users expect.
• Commands run with a 5-second timeout. If git is not installed or the directory is not a repository, commands return structured errors.
• Output encoding is handled as UTF-8 with lossy conversion for non-UTF-8 paths.

---

Branch Policy

Purpose

Branch Policy prevents agents from making commits or modifications on protected branches. This is a session-level safeguard -- the policy is checked when an agent session starts and when git operations are detected in tool calls.

Protection Rules

Protected branch patterns are configurable per project. The defaults are:

Pattern	Matches
main	Exact match
master	Exact match
release/*	Any branch starting with release/

When an agent session starts on a protected branch, the system emits a warning notification. It does not block the session, because agents may need to read code on these branches. However, the branch name is included in the agent's system prompt with a clear instruction not to commit.

Commands

pro_branch_check

Checks whether the current branch is protected.

Field	Type	Required	Description
cwd	String	Yes	Repository path
projectId	String	Yes	Project identifier (for project-specific policies)

Response:

interface BranchCheckResult {
  branch: string;
  isProtected: boolean;
  matchedPattern: string | null; // Which pattern matched
}

pro_branch_policy_set

Sets custom protected branch patterns for a project. Replaces any existing patterns.

Field	Type	Required	Description
projectId	String	Yes	Project identifier
patterns	Vec<String>	Yes	Branch patterns (exact names or glob with *)

pro_branch_policy_get

Returns the current branch policy for a project. Returns default patterns if none are set.

Field	Type	Required	Description
projectId	String	Yes	Project identifier

pro_branch_policy_delete

Removes custom branch policy for a project, reverting to defaults.

Field	Type	Required	Description
projectId	String	Yes	Project identifier

Integration

Branch policy is checked at two points:

1. Session start: AgentSession.startQuery() calls pro_branch_check. If protected, a warning toast is shown and the branch protection instruction is appended to the system prompt.
2. System prompt injection: The formatted git context (from pro_git_inject) includes a PROTECTED BRANCH warning banner when applicable.