Git Context Controller (GCC) v2

Lean, git-backed context management for LLM agents.

GCC v2 stores hash + intent + optional decision notes instead of verbose markdown. Full context is reconstructed on demand via git show. Dual mode: git-backed or standalone.

Based on the research paper: Git Context Controller

---

Why GCC?

LLM agents lose context as conversations grow. GCC solves this by giving agents structured memory:

• Lean storage — ~50 tokens per entry vs ~500 in v1
• Git-backed truth — real commits, not narrative copies
• Safe experimentation — branches via git worktrees for real isolation
• Cross-session recovery — reconstruct context from hashes on demand
• aiyoucli bridge — auto-feeds commit data to vector memory when available

How It Works

Git Mode (with repo)

.GCC/
├── index.yaml       # Single source of truth (~50 tokens/entry)
├── branches/        # Branch-specific notes
├── worktrees/       # Worktree tracking
└── .bridge-log      # Sync state with aiyoucli

index.yaml entry:
  - id: C001
    hash: 85c8539        ← pointer to git truth
    intent: "release prep" ← why
    note: "descartamos semantic-release por overhead" ← optional decision
    branch: main
    date: "2026-02-25T21:40:00Z"

Standalone Mode (no repo)

Falls back to markdown files compatible with v1:

.GCC/
├── index.yaml       # Timeline
├── main.md          # Roadmap (v1 compat)
├── log.md           # OTA traces (v1 compat)
└── branches/

Context Reconstruction

Agent needs context
       │
       ▼
  gcc_context.sh --summary     ← ~50 tokens, zero git calls
  gcc_context.sh --last 5      ← reconstructs via git show
  gcc_context.sh --decisions   ← only entries with notes
  gcc_context.sh --hash abc123 ← full diff for one commit

Installation

As a Claude Code Skill

# Via skills.sh
npx skills add faugustdev/git-context-controller

# Manual installation
cp -r gcc/ your-project/.claude/skills/gcc/

Standalone

git clone https://github.com/faugustdev/git-context-controller.git

# Initialize GCC in your project
cd your-project
/path/to/scripts/gcc_init.sh

Quick Start

Once installed, GCC activates automatically. Use commands or natural language:

Action	Command	Natural Language
Save progress	/gcc commit	”save this milestone”
Try alternative	/gcc branch experiment	”branch to try a different approach”
Integrate results	/gcc merge experiment	”merge the experiment results”
Quick status	/gcc context --summary	”where were we?”
Recent work	/gcc context --last 10	”show recent activity”
View decisions	/gcc context --decisions	”what did we decide about X?”
Deep dive	/gcc context --hash abc123	”details on that commit”
Clean up	/gcc cleanup	”clean up old worktrees”
Sync memory	/gcc bridge --sync	”sync to aiyoucli”

Scripts

GCC v2 includes utility scripts for mechanical operations:

Script	Purpose
gcc_init.sh	Initialize GCC (auto-detects git/standalone)
gcc_commit.sh	Real git commit + lean index entry
gcc_context.sh	Reconstruct context from hashes
gcc_bridge.sh	Feed commit data to aiyoucli vector memory
gcc_cleanup.sh	TTL-based worktree cleanup + index pruning

gcc_commit.sh

gcc_commit.sh "implement retry logic"
gcc_commit.sh "release prep" "descartamos semantic-release por overhead"
gcc_commit.sh --staged "hotfix: null check"

gcc_context.sh

gcc_context.sh --summary          # one-line per entry (cheapest)
gcc_context.sh --last 5           # last 5 with git details
gcc_context.sh --hash abc123      # full diff for specific commit
gcc_context.sh --decisions        # only entries with notes
gcc_context.sh --full             # everything

gcc_bridge.sh

gcc_bridge.sh --status            # check bridge connectivity
gcc_bridge.sh --sync              # sync all unsynced entries to aiyoucli

gcc_cleanup.sh

gcc_cleanup.sh --dry-run          # show what would be cleaned
gcc_cleanup.sh --force            # clean without asking
gcc_cleanup.sh --prune-index 50   # keep last 50 timeline entries

Commands Reference

COMMIT

Persists a milestone. In git mode, executes a real commit.

/gcc commit <summary>

BRANCH

Creates an isolated workspace. In git mode, uses real git worktrees.

/gcc branch <name>

MERGE

Integrates a branch back. In git mode, real git merge + synthesis note.

/gcc merge <branch-name>

CONTEXT

Retrieves historical memory reconstructed from git.

/gcc context [--summary | --last N | --hash HASH | --decisions | --full]

Flag	Returns	Cost
--summary	One-line per entry	~0 extra tokens
--last N	Last N entries with git details	~200 tokens/entry
--hash HASH	Full diff for one commit	Variable
--decisions	Only entries with notes	Minimal
--full	Everything	All entries

Configuration

Controlled via index.yaml:

config:
  proactive_commits: true     # Auto-suggest commits after milestones
  worktree_ttl: 24h           # Auto-cleanup expired worktrees
  bridge_to_aiyoucli: auto    # auto | off | manual

Project Structure

git-context-controller/
├── SKILL.md              # Skill definition (v2)
├── README.md             # This file
├── LICENSE               # MIT License
├── CONTRIBUTING.md       # Contribution guidelines
├── .gitignore
├── scripts/
│   ├── gcc_init.sh       # Initialization (git detect + index.yaml)
│   ├── gcc_commit.sh     # Commit + lean entry
│   ├── gcc_context.sh    # Context reconstruction
│   ├── gcc_bridge.sh     # aiyoucli memory bridge
│   └── gcc_cleanup.sh    # Worktree TTL + index pruning
├── references/
│   └── file_formats.md   # Format specifications (v2)
└── examples/
    └── sample_session.md # Example session (v2)

Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines.

References

• Paper: Git Context Controller: Structured Context Management for LLM Agents
• Concept: Emergent Mind - GCC Topic

License

MIT