tomevault-io State Tracker - Git-Powered Session & State Awareness
Purpose: Provide Claude with complete awareness of project state using git as source of truth, preventing stale mental models and redundant work.
What This System Tracks:
In-Session State (real-time)
- File modifications (git diff)
- Uncommitted changes (git status)
- Current branch and commit
Between-Session Context (differential)
- What happened since last session
- Commits made (by you or others)
- Files changed externally
- Branch switches
Historical Decisions (queryable)
- Past research findings
- Architectural decisions
- Implementation plans
Token Overhead:
- In-session checks: ~200-500 tokens (only when files change)
- Between-session context: ~1-2K tokens (differential only)
- Decision queries: ~2-5K tokens (selective loading)
- Total: <5K tokens vs 50K+ full reload
When This Skill Activates
Auto-activates when you detect:
State Queries:
- "what changed since last session?"
- "show me what happened"
- "what's the current state?"
- "what files did we work on?"
- "what commits were made?"
Before File Operations:
- PreToolUse hook activates automatically
- Checks if file changed externally
- Warns before Edit/Write if file is stale
Before Duplicating Work:
- "research X" → Check if already researched
- "decide on Y" → Check if already decided
- "plan Z" → Check if plan exists
Your Workflow When This Skill Activates
If User Asks "What Changed?"
Run the manual status script:
./scripts/session-status.sh
This shows:
- Git activity since last session
- Current working directory status
- Decision tracking summary
Token cost: ~500 tokens for complete state summary
If You're About to Edit a File
Trust the PreToolUse hook:
- It automatically checks git status
- If file changed externally, you'll see warning
- Follow the recommendation: Re-read before editing
Don't manually check git status - hook does it automatically!
If Starting Research or Planning
Query decisions.yaml first:
# Before research
uv run scripts/decision-query.py --topic "{topic}" --type research
# Before planning
uv run scripts/decision-query.py --topic "{topic}" --type plans
# Before deciding
uv run scripts/decision-query.py --topic "{topic}" --type decisions
If found: Load existing context (2-5K tokens) If not found: Proceed with new work
###If User Made External Changes
User says: "I made some changes" or "I committed something"
Your response:
# Check what changed
./scripts/session-status.sh
Then summarize what you found for the user.
The Complete State Awareness System
Component 1: In-Session State Sync (Automatic)
PreToolUse Hook checks git state before file operations:
# Happens automatically when you try to Edit/Write
PreToolUse: Intercepts tool call
→ Runs: git status <file>
→ If changed: "⚠️ File modified externally - Re-read before editing"
→ Always continues (non-blocking)
What you see:
⚠️ File State Change Detected
File: hooks/user_prompt_submit.py
Status: MODIFIED
Git Says: File has uncommitted changes
Recommendation:
- Re-read file to see current state
- Use Read tool before Edit
Continuing with your Edit operation...
Token cost: ~300 tokens (only when file actually changed)
Component 2: Between-Session Context (Automatic)
SessionStart Hook injects git context automatically:
Session starts:
→ SessionStart reads .contextune/last_session.yaml
→ Runs: git log <last_commit>..HEAD
→ Runs: git diff --stat <last_commit>..HEAD
→ Generates differential summary
→ Injects as additionalContext
What you see at session start:
📋 Git Context Since Last Session (2 hours ago)
**Git Activity:**
- 5 new commits
- 8 files changed (+250, -30)
- Branch: master
**Recent Commits:**
a95478f feat: add three-layer git enforcement
1e1a15a feat: add plan extraction support
... and 3 more
**Files Changed:**
Added (2):
- commands/ctx-git-commit.md
- hooks/pre_tool_use_git_advisor.py
Modified (6):
- hooks/user_prompt_submit.py
- hooks/hooks.json
... and 4 more
**Current Status:** 2 uncommitted changes
Ready to continue work!
Token cost: ~1-2K tokens (only NEW information since last session)
Component 3: Manual Status Check
When user asks "what changed?" or you need to check state:
# Run the status script
./scripts/session-status.sh
Shows:
- Current git state (branch, commit, uncommitted files)
- Changes since last session (commits, files, diff stats)
- Decision tracking status
- Full git summary
When to use:
- User asks "what's the current state?"
- You need to verify what happened
- Before major operations
- After user says "I made some changes"
Token cost: ~500 tokens
Complete Workflow Examples
Example 1: File Modified Externally (In-Session)
10:00 - You: Read hooks/user_prompt_submit.py
[File contents loaded into context]
10:15 - User edits file in VS Code
[Makes changes, saves]
10:20 - You: Edit hooks/user_prompt_submit.py
PreToolUse Hook: ⚠️ File State Change Detected
File: hooks/user_prompt_submit.py
Status: MODIFIED
Recommendation: Re-read before editing
You: "I see the file was modified externally. Let me re-read it first."
[Read hooks/user_prompt_submit.py]
[Now have current state]
[Proceed with Edit]
Token saved: Prevented edit conflict + re-work
Example 2: New Session After External Changes
Session 1 ends:
SessionEnd: Records metadata to .contextune/last_session.yaml
- session_id, timestamp, last_commit, branch, files_worked_on
[User works outside Claude]
- Commits via terminal: git commit -m "quick fix"
- Edits 3 files manually
- Switches to develop branch
Session 2 starts:
SessionStart: Loads .contextune/last_session.yaml
→ git log <last_commit>..HEAD
→ git diff --stat <last_commit>..HEAD
→ Generates summary
Claude sees:
📋 Git Context Since Last Session (3 hours ago)
**Git Activity:**
- 1 new commit: "quick fix"
- 3 files changed
- Branch: master → develop (switched)
**Current Status:** Clean ✅
Claude: "I see you made a commit and switched to develop branch.
The 3 files that changed are now in my context. Ready to continue!"
Token cost: ~1.5K (vs 50K+ full reload)
The Decision Tracking System
Structure
decisions.yaml - YAML database with 3 types of entries:
research:
entries:
- id: "res-001-authentication-libraries"
topic: "Authentication libraries for Node.js"
findings: "Compared Passport.js, Auth0, NextAuth..."
recommendation: "Use NextAuth for React apps"
created_at: "2025-10-28"
expires_at: "2026-04-28" # 6 months
tags: [authentication, libraries, nodejs]
plans:
entries:
- id: "plan-001-jwt-implementation"
title: "JWT Authentication Implementation"
summary: "5 tasks: AuthService, middleware, tokens..."
status: "completed"
created_at: "2025-10-28"
tags: [authentication, implementation]
decisions:
entries:
- id: "dec-001-dry-strategy"
title: "Unified DRY Strategy"
status: "accepted"
context: "CHANGELOG grows unbounded..."
alternatives_considered: [...]
decision: "Use scripts for git workflows"
consequences: {positive: [...], negative: [...]}
tags: [architecture, cost-optimization]
CLI Tools
Query existing context:
# Check if we already researched a topic
uv run scripts/decision-query.py --topic "authentication" --type research
# Check for existing decisions
uv run scripts/decision-query.py --topic "DRY" --type decisions
# Check for active plans
uv run scripts/decision-query.py --type plans --status active
# Query by tags
uv run scripts/decision-query.py --tags architecture cost-optimization
Output format:
# Filtered entries matching your query
# Load only relevant context (2-5K tokens vs 150K full CHANGELOG)
Your Workflow (IMPORTANT!)
Before Starting Research
ALWAYS query first:
# Check if we already researched this topic
uv run scripts/decision-query.py --topic "{research_topic}" --type research
If found:
- Load the existing findings (2K tokens)
- Check expiration date (research expires after 6 months)
- If recent → Use existing research
- If expired → Research again, update entry
If NOT found:
- Proceed with research
- SessionEnd hook will auto-extract to decisions.yaml
Savings:
- Skip $0.07 redundant research
- Load 2K tokens instead of researching again
Before Making Decisions
ALWAYS query first:
# Check for existing decisions on this topic
uv run scripts/decision-query.py --topic "{decision_topic}" --type decisions
If found:
- Load the decision context
- Check status (accepted, rejected, superseded)
- If accepted → Follow existing decision
- If superseded → Find superseding decision
- If rejected → Understand why, avoid same approach
If NOT found:
- Proceed with decision-making
- SessionEnd hook will auto-extract to decisions.yaml
Savings:
- Skip 15-30 min re-discussion
- Consistent decisions across sessions
Before Planning
ALWAYS query first:
# Check for existing plans on this topic
uv run scripts/decision-query.py --topic "{feature_name}" --type plans
If found:
- Load existing plan (2-3K tokens)
- Check status (active, completed, archived)
- If active → Continue existing plan
- If completed → Reference, don't recreate
If NOT found:
- Create new plan with /ctx:plan
- Plan will be auto-extracted to decisions.yaml
Auto-Population
decision-sync.py scans conversation history and auto-populates decisions.yaml:
# Scan all conversations for decisions (run once)
uv run scripts/decision-sync.py
# Result: Populates decisions.yaml with historical context
How it works:
- Scans
~/.claude/projects/*/conversation/for transcripts - Uses extraction patterns to detect decisions/research/plans
- Extracts and appends to decisions.yaml
- Deduplicates (won't add same decision twice)
Already populated: Check current state:
# See what's already in decisions.yaml
uv run scripts/decision-query.py --all
Token Efficiency
Context Loading Comparison
Old approach (CHANGELOG.md):
Import entire CHANGELOG: 150K tokens
Problem: Loads everything, most irrelevant
Cost: High context usage
New approach (decisions.yaml with queries):
Query specific topic: 2-5K tokens (83-97% reduction!)
Example: decision-query.py --topic "authentication"
Loads: Only relevant 2-3 entries
Selective Loading Strategy
Scenario 1: Starting authentication work
# Query for authentication context
uv run scripts/decision-query.py --topic "authentication"
# Loads:
- Research: Authentication libraries (if exists)
- Decisions: Auth approach decisions (if exists)
- Plans: Auth implementation plans (if exists)
# Total: ~3K tokens vs 150K full CHANGELOG
Scenario 2: User asks "why did we choose X?"
# Query for specific decision
uv run scripts/decision-query.py --topic "DRY strategy"
# Loads: Single decision with full context
# Total: ~1K tokens
Integration with Hooks
SessionEnd Hook (Automatic)
session_end_extractor.py already extracts to decisions.yaml:
- Detects decisions in conversation (## Decision: pattern)
- Extracts structured data
- Appends to decisions.yaml automatically
You don't need to do anything - it happens automatically at session end!
What You Should Do
During conversation:
- Output decisions in extraction-optimized format (see output style)
- SessionEnd hook extracts automatically
- Next session, query for context if needed
Examples
Example 1: Before Researching Libraries
User: "Research best state management libraries for React"
You: Let me check if we already researched this.
[Run decision-query.py --topic "state management" --type research]
Result: Found existing research from 2 months ago
- Compared: Redux, Zustand, Jotai, Valtio
- Recommendation: Zustand for simple apps, Jotai for complex
- Tags: [react, state-management, libraries]
You: We already researched this! Here's what we found:
[Load 2K tokens vs spending $0.07 to research again]
Example 2: Before Making Architecture Decision
User: "Should we use microservices or monolith?"
You: Let me check if we already decided on architecture approach.
[Run decision-query.py --topic "architecture" --type decisions]
Result: Found decision "dec-002-monolith-first"
- Decision: Start with modular monolith
- Rationale: Team size <5, single deployment simpler
- Status: accepted
- Date: 2025-09-15
You: We already decided this! Here's the context:
[Load 1K tokens vs re-discussing for 30 minutes]
Example 3: Before Planning Feature
User: "Plan implementation for user dashboard"
You: Let me check for existing plans.
[Run decision-query.py --topic "dashboard" --type plans]
Result: Found plan "plan-005-dashboard-v1"
- Status: completed
- Summary: "5 tasks implemented, merged to main"
- Created: 2025-10-01
You: We already implemented this! Let me load the existing plan.
[Load 3K tokens, reference existing work]
Lifecycle Management
Research entries expire after 6 months:
- Rationale: Technology evolves, best practices change
- Old research becomes stale (2024 → 2025 practices differ)
- Expired entries moved to archives
Plans archive 90 days after completion:
- Rationale: Useful during implementation, less useful after
- Completed plans moved to docs/archive/
Decisions never auto-expire:
- Unless explicitly superseded by new decision
- Architectural decisions stay relevant
Check lifecycle status:
# See active vs expired entries
uv run scripts/decision-query.py --show-expired
Cost Impact
Annual savings (assuming 50 research sessions):
Old: 50 × $0.07 = $3.50 in redundant research
New: Query first (free), research only if needed
Savings: ~$3.00/year + avoid 25 hours of redundant work
Token savings per query:
Load full CHANGELOG: 150K tokens
Load specific query: 2-5K tokens
Savings: 97% reduction per lookup
Quick Reference
Check before researching:
uv run scripts/decision-query.py --topic "{topic}" --type research
Check before deciding:
uv run scripts/decision-query.py --topic "{topic}" --type decisions
Check before planning:
uv run scripts/decision-query.py --topic "{topic}" --type plans
See all active context:
uv run scripts/decision-query.py --all
Integration Points
- Before /ctx:research - Query for existing research first
- Before /ctx:plan - Query for existing plans first
- Before /ctx:design - Query for existing decisions first
- When user asks "why" - Query for decision rationale
- At SessionEnd - Automatic extraction (no action needed)
Summary
Key principle: Query before doing work that might already be done.
Benefits:
- 83-97% token reduction for context loading
- Avoid $0.07 redundant research
- Consistent decisions across sessions
- Queryable, structured context
- Auto-populated from conversation history
Remember: decisions.yaml is plugin-local, works for all users who install Contextune!
Converted and distributed by TomeVault — claim your Tome and manage your conversions.