Master Git Context Controller

A structured skill for managing AI agent memory as a versioned file system — providing persistent context storage across sessions using Git-inspired operations (COMMIT, BRANCH, MERGE, CONTEXT) to prevent context loss and enable efficient long-running agent workflows.

When to Use This Skill

Choose Master Git Context Controller when you need to:

• Persist AI agent state across long-running tasks that exceed context limits
• Track decision history and rationale in a structured, retrievable format
• Manage parallel workstreams with branching context
• Recover from context window exhaustion without losing progress
• Build a knowledge base that grows across multiple AI sessions

Consider alternatives when:

• You need simple session handoff documents (use a session handoff skill)
• You need git version control for code (use git directly)
• You need project documentation (use a documentation skill)

Quick Start

Copy
# Initialize the Git Context Controller
claude "Initialize GCC for this project. Create the .GCC/ directory structure and commit the initial context with project overview and current task state."

Copy
# GCC Initialization

## Directory Structure Created
.GCC/
├── HEAD              # Points to current branch
├── commits/          # Context snapshots
│   └── 001.md        # Initial commit
├── branches/         # Named context branches
│   └── main.md       # Default branch
└── index.md          # Working context (staging area)

## Initial Commit: 001
**Branch**: main
**Timestamp**: 2024-12-15T14:00:00Z
**Message**: "Initialize project context"

### Stored Context
- Project: E-commerce API refactoring
- Tech Stack: Node.js, Express, PostgreSQL
- Current Task: Migrating from monolith to microservices
- Key Files: src/api/, src/services/, src/models/
- Decisions: Using event-driven architecture for inter-service communication

Core Concepts

GCC Operations

Operation	Purpose	Git Equivalent
COMMIT	Save current context state	git commit
BRANCH	Create parallel context track	git branch
MERGE	Combine context from branches	git merge
CONTEXT	Retrieve stored context	git log / show
STATUS	Show current context state	git status
DIFF	Compare context between commits	git diff

Context Commit Structure

Copy
## Commit Format

### Header
- Commit ID: Sequential (001, 002, ...)
- Branch: Which context branch
- Timestamp: When committed
- Message: What this context snapshot captures

### Context Sections
- **Task State**: Current task progress and status
- **Decisions**: Key decisions made with rationale
- **Files Modified**: What code was changed and why
- **Discoveries**: Findings from code exploration
- **Blockers**: Current obstacles and status
- **Next Steps**: Planned actions for continuation

### Example Commit
# Commit 003 (branch: auth-refactor)
**Message**: "Complete JWT → session migration in auth module"

## Task State
Auth module migration: 80% complete
- ✅ Token generation replaced with session creation
- ✅ Middleware updated for session checking
- ⬜ Tests not yet updated

## Decisions
- Redis for session store (multi-instance requirement)
- 24hr TTL with sliding window (matches old JWT expiry)

## Files Modified
- src/auth/auth.ts:15-89 — session creation logic
- src/middleware/auth.ts:1-45 — session-based checking

## Next Steps
1. Update test suite for session-based auth
2. Update API documentation

Branching for Parallel Workstreams

Copy
## Branch Management

### Creating a Branch
When exploring multiple approaches to a problem:

BRANCH auth-approach-a FROM main
→ Context for JWT refresh token approach

BRANCH auth-approach-b FROM main
→ Context for session-based approach

### Merging Results
After evaluating both approaches:

MERGE auth-approach-b INTO main
→ Session approach selected (rationale: simpler,
  no token refresh complexity, Redis available)

### Branch Cleanup
Delete branches that are no longer needed:
DELETE BRANCH auth-approach-a
→ Preserved in commit history for reference

Configuration

Parameter	Description	Example
gcc_dir	Directory for GCC context files	".GCC/"
auto_commit	Auto-commit context periodically	true
commit_interval	Turns between auto-commits	5
max_commits	Maximum commits to retain	50
include_code	Store code snippets in commits	true
format	Context file format	"markdown"

Best Practices

1. Commit context at every decision point — Don't wait until the end of a long session. Commit after every significant decision, discovery, or direction change. If the context window resets, you want fine-grained recovery points, not one massive dump.

2. Write commit messages that explain the state change — "Updated auth" is useless. "Complete JWT removal, session store connected, tests pending" captures exactly where things stand. The next agent should understand the project state from reading commit messages alone.

3. Use branches when exploring alternatives — Before committing to an approach, create a branch for each option. This preserves the exploration context so you can explain why you chose one approach over another, even after the decision is made.

4. Include file paths with line numbers in every commit — Vague references like "modified the auth module" force the next agent to search. "Modified src/auth/auth.ts:15-89" lets them jump directly to the relevant code.

5. Review and prune context regularly — Old commits with outdated information (superseded decisions, abandoned approaches, fixed issues) add noise. Periodically clean up or summarize old context to keep the working set relevant and concise.

Common Issues

Context commits become too large and repetitive — Each commit should capture only what changed since the last commit, not the entire project state. Use a diff-style approach: "Changed auth from JWT to sessions" not "Project overview + tech stack + full auth description again."

Branch context diverges too far from main — If a branch runs for too long without merging back, the main context becomes stale. Set a maximum branch lifetime (e.g., 10 commits) before requiring a merge or decision about whether to continue.

Next agent ignores the GCC context — The GCC system only works if the resuming agent reads the context before starting. Include a clear instruction at the top of .GCC/HEAD: "READ THIS FIRST: Review commits 001-015 on branch main before continuing work."