project-context-sync
Keep a living project state document updated after each commit, so any agent (or future session) can instantly understand where things stand.
What It Does
┌─────────────┐ ┌──────────────────┐ ┌─────────────────────┐
│ Git Commit │ ──▶ │ Post-commit Hook │ ──▶ │ PROJECT_STATE.md │
│ │ │ │ │ (auto-updated) │
└─────────────┘ └──────────────────┘ └─────────────────────┘
After each commit, the hook:
- Gathers git info (last commit, recent history, branch, changed files)
- Optionally calls an LLM to generate a smart summary
- Updates
PROJECT_STATE.md
in the repo root
Installation
# From the repo you want to enable:
cd /path/to/your/repo
/path/to/skills/project-context-sync/scripts/install.sh
Or if you have the skill in your path:
project-context-sync install
This will:
- Install a post-commit hook in
.git/hooks/
- Create
.project-context.yml
with default config
- Create initial
PROJECT_STATE.md
- Add
PROJECT_STATE.md
to .gitignore
Uninstall
cd /path/to/your/repo
/path/to/skills/project-context-sync/scripts/uninstall.sh
Manual Update
Trigger an update without committing:
cd /path/to/your/repo
/path/to/skills/project-context-sync/scripts/update-context.sh
Configuration
Edit
.project-context.yml
in your repo root:
project_context:
# Use AI to generate smart summaries (default: true)
ai_summary: true
How many recent commits to include
recent_commits: 5
Include diff stats in context
include_diff_stats: true
Sections to include
sections:
- last_commit
- recent_changes
- current_focus # AI-generated
- suggested_next # AI-generated
AI Summary Mode
With ai_summary: true
(default):
- Generates intelligent summaries of what changed
- Infers current focus from recent commit patterns
- Suggests next steps
- Costs tokens but provides rich context
- Requires: Gateway HTTP API enabled (see below)
With ai_summary: false
:
- Just logs raw git info
- Fast and free
- Less intelligent but still useful
Enabling the Gateway HTTP API
AI mode uses Clawdbot's OpenAI-compatible endpoint (
/v1/chat/completions
). This is
disabled by default for security. To enable:
// ~/.clawdbot/clawdbot.json
{
"gateway": {
"http": {
"endpoints": {
"chatCompletions": { "enabled": true }
}
}
}
}
Security notes:
- The endpoint inherits gateway auth (requires bearer token)
- With
bind: "loopback"
(default), only local processes can connect
- The script reads the token from
~/.clawdbot/clawdbot.json
automatically
- Risk is minimal for local development setups
Output
PROJECT_STATE.md
will contain:
# Project State
*Auto-updated by project-context-sync*
Last Commit
- Hash: abc123
- Message: Implement isPro check for app blocking
- Branch: feature/subscription-gating
- When: 2026-01-29 12:34
- Files changed: 3
Recent Changes
- abc123: Implement isPro check for app blocking
- def456: Add PaywallPrompt component
- ...
Current Focus
[AI-generated summary of what's being worked on]
Suggested Next Steps
[AI-suggested based on commit patterns]
Notes
PROJECT_STATE.md
is gitignored by default (regenerated locally)- The hook requires Clawdbot to be running for AI summaries
- Without Clawdbot, falls back to raw git info mode
