cnotes - Git Notes for Claude Conversations

cnotes automatically captures Claude conversation context in git notes, making it easy to understand the development history and reasoning behind each commit.

⭐️ cnotes is pronounced like 💵 c-notes or 🏊 cenotes

Quick Start

# Build and install
go install github.com/imjasonh/cnotes
cnotes install

# Now every git commit made through Claude will have conversation context attached!

# View conversation notes for the latest commit
cnotes show

# View notes for a specific commit  
cnotes show abc1234

# List all commits with conversation notes
cnotes list

What It Does

When you work with Claude and make git commits, cnotes automatically:

1. Detects git commit commands in your Claude conversation
2. Captures conversation context including user prompts and tool interactions
3. Attaches structured notes to the commit using git notes
4. Preserves context across rebases, squashes, and other git operations

Installation

# Install to project settings (recommended)
cnotes install

# Install globally
cnotes install --global

# Install locally  
cnotes install --local

# Uninstall
cnotes install --uninstall

This configures Claude Code to call cnotes as a hook handler when you make git commits.

Viewing Conversation Notes

Pretty-Printed Format (Recommended)

# Show notes for the latest commit
cnotes show

# Show notes for a specific commit
cnotes show abc1234

# List all commits with notes
cnotes list

Example Output

# Claude Conversation Notes

**Commit:** `abc1234 Add user authentication with password validation`
**Session ID:** `claude_session_20250121_143022`
**Timestamp:** 2025-01-21 14:30:45 EST
**Claude Version:** claude-sonnet-4-20250514
**Tools Used:** Edit, Write, Bash

## Commit Context

Git command: git commit -m "Add user authentication with password validation" Result: [main abc1234] Add user authentication with password validation

## Conversation Context

Recent user prompts:
- Add user authentication to the login form
- Make sure to use bcrypt for password hashing

Tool interactions:
- Edit: components/LoginForm.jsx
- Write: utils/auth.js
- Bash: npm install bcrypt

---
💡 *Generated by `cnotes`*

Raw Git Notes Commands

# View raw notes
git notes --ref=claude-conversations show HEAD

# View in git log
git log --show-notes=claude-conversations --oneline

Backup and Restore

cnotes includes comprehensive backup functionality to protect against data loss during rebasing, squashing, or other destructive git operations:

# Backup all conversation notes
cnotes backup my-notes-backup.json

# Restore notes from backup
cnotes restore my-notes-backup.json

# View all commits with notes
cnotes list

Automatic Protection

The system automatically:

• Warns before destructive operations like git rebase, git reset --hard
• Configures git to preserve notes during rebase operations
• Provides backup commands for manual recovery

Configuration

Customize behavior by creating .claude/notes.json:

{
  "enabled": true,
  "max_excerpt_length": 5000,
  "max_prompts": 2,
  "include_tool_output": false,
  "notes_ref": "claude-conversations",
  "exclude_patterns": ["password", "token", "key", "secret"]
}

Privacy Controls

The system includes built-in privacy protections:

• Automatically filters sensitive patterns (passwords, tokens, keys)
• Limits excerpt length to prevent excessive data storage
• Only includes conversation context from the current session
• Configurable exclusion patterns
• Option to disable entirely ("enabled": false)

How It Works

1. Hook Integration: cnotes integrates with Claude Code as a PostToolUse hook handler
2. Git Command Detection: Monitors bash commands for git commit operations
3. Context Extraction: Parses Claude transcript files to extract relevant conversation context
4. Note Creation: Stores structured JSON data using git notes --ref=claude-conversations
5. Hash Preservation: Automatically configures git to preserve notes during rewrites

Architecture

• cnotes - Main binary that handles Claude Code hook calls
• cnotes show - Pretty-print conversation notes in Markdown format
• cnotes install - Configure Claude Code to use cnotes
• cnotes backup/restore - Backup and restore conversation notes
• cnotes list - List all commits with conversation notes

Requirements

• Go 1.24+
• Claude Code CLI
• Git repository

Development

# Clone and build
git clone https://github.com/imjasonh/cnotes
cd cnotes
go build -o cnotes

# Install for development
cnotes install

# Test manually (simulates Claude Code calling it)
echo '{"hook_event_name":"PostToolUse",...}' | cnotes

Sharing Git Notes

Git notes are local by default. To share with your team:

# Push notes to remote
git push origin refs/notes/claude-conversations

# Pull notes from remote  
git fetch origin refs/notes/claude-conversations:refs/notes/claude-conversations

# Configure automatic notes syncing
git config remote.origin.fetch '+refs/notes/*:refs/notes/*'

---

⚠️ Security Notice: cnotes executes as a Claude Code hook handler. Ensure your installation is secure and trusted.