Git Module

Fast native git operations via pygit2 (libgit2 C bindings) with async subprocess fallback. Includes a 500ms TTL cache for repeated read-only calls.

Performance

Operation	pygit2	subprocess	MCP Server	Cache hit
status	3.5ms	4ms	~300ms	0.013ms
log (5)	0.4ms	15ms	~150ms	0.013ms
branches	0.3ms	10ms	~100ms	0.013ms
diff	-	7ms	~200ms	0.013ms

The module is 60-150x faster than MCP git servers for read operations, and cached reads are ~25,000x faster.

Configuration

modules:
  git:
    config:
      workspace: "{{execution.workspace}}"   # git repo directory
      default_remote: origin                  # default remote for push/pull
      github_token: "{{env.GITHUB_TOKEN}}"   # for PR creation (optional)
      sign_commits: false                     # GPG signing

Actions (17)

Read-only (risk: low)

Action	Description	Parameters
status	Branch, staged, unstaged, untracked files	-
diff	Changes between working tree, index, or refs	target? (staged/unstaged/ref), file?
log	Commit history	limit (default 20), branch?, file?, oneline
blame	Who modified each line	file, start_line?, end_line?
show	Commit details	ref (default HEAD), stat_only
branch_list	Local and remote branches	all (include remote)

Write (risk: medium)

Action	Description	Parameters
add	Stage files	files (list)
commit	Create commit	message, amend
branch_create	Create branch	name, start_point?, checkout
checkout	Switch branch/ref	target
stash	Save/restore changes	action (push/pop/list/drop), message?
tag	Create/list/delete tags	action, name?, message?, ref?
pull	Pull from remote	remote?, branch?, rebase

Dangerous (risk: high)

Action	Description	Parameters
push	Push to remote	remote?, branch?, force, set_upstream
reset	Reset branch state	mode (soft/mixed/hard), ref
merge	Merge branch	branch, no_ff

GitHub (risk: medium)

Action	Description	Parameters
pr_create	Create pull request	title, body, base?, draft

Requires the gh CLI tool installed. Uses GITHUB_TOKEN from config for authentication.

Caching

Read-only operations are cached for 500ms. Any write operation invalidates the entire cache. This means:

• Sequential status + diff + log calls within 500ms hit the cache after the first call
• After commit or add, all cached data is invalidated immediately
• Cache is per-module-instance (no cross-agent pollution)

Examples

# A coding assistant with git access
modules:
  git:
    config:
      workspace: "{{workspace}}"
  filesystem:
    config:
      checkpoint: true

agents:
  - id: coder
    brain:
      provider: deepseek
      model: deepseek-chat
    system_prompt: |
      You are a coding assistant with git access.
      Always check git status before and after making changes.

Implementation Details

• pygit2 is used for status, log, branch_list (C library calls, no process spawn)
• async subprocess is used for diff, blame, show, and all write operations
• All subprocess calls use asyncio.create_subprocess_exec (non-blocking)
• Output is parsed from --porcelain format where available (machine-readable, faster)