cnotes/README.md

# cnotes - Git Notes for Claude Conversations

[![Test](https://github.com/imjasonh/cnotes/actions/workflows/test.yml/badge.svg)](https://github.com/imjasonh/cnotes/actions/workflows/test.yml)

**cnotes** automatically captures Claude conversation context in [git notes](https://git-scm.com/docs/git-notes) using [Claude hooks](https://docs.anthropic.com/en/docs/claude-code/hooks), making it easy to understand the development history and reasoning behind each commit. The tool shows a conversational transcript of user prompts, tool uses, and Claude's responses.

⭐️ `cnotes` is pronounced like 💵 c-notes or 🏊 [_cenotes_](https://en.wikipedia.org/wiki/Cenote)

## Quick Start

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

# Note: you may need to restart `claude` to pick up the new hooks

# 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

```bash
# 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)

```bash
# 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

```markdown
# 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

```bash
# 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:

```bash
# 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`:

```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

```bash
# 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 them with your team:

```bash
# Push notes manually
git push origin refs/notes/claude-conversations

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

### Automatic Notes Pushing (Recommended)

Configure git to automatically push notes whenever you push commits:

```bash
# Set up automatic notes pushing
git config --add remote.origin.push '+refs/notes/claude-conversations:refs/notes/claude-conversations'
```

After this one-time setup, every `git push` will automatically include your notes. This is the most reliable way to ensure notes are always synchronized with your commits.

## Chrome Extension

A Chrome extension is available to view git notes directly on GitHub commit pages. See [`chrome-extension/`](chrome-extension/) for details.

### Features
- 🔢 Shows badge indicator when commits have notes
- 📝 Displays notes in a popup when clicked
- 🏷️ Supports multiple notes refs with tabs
- ⚡ Works with any public repository

### Installation
1. Load the extension from `chrome-extension/` directory
2. Navigate to any GitHub commit page
3. Click the extension icon to view notes

---

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