Claude Conversation Tracker

中文使用指南 · 中文README

A highly abstract, platform-agnostic conversation tracking plugin for Claude Code and other AI code assistants. This plugin automatically tracks conversation rounds, categorizes changes by impact level, creates git branches with proper Claude attribution, and generates comprehensive conversation summaries.

🚀 Features

• Universal Compatibility: Designed to work with Claude Code, Cursor, VS Code, and other AI assistants
• Intelligent Change Analysis: Categorizes changes as high-impact (breaking), mid-level (potentially misleading), or low-level (confident)
• Automatic Git Integration: Creates branches, commits with Claude attribution, and pushes changes
• Merge Request Automation: Supports GitHub, GitLab, Azure DevOps, and custom providers
• Comprehensive Documentation: Generates structured .talk files with conversation summaries
• Highly Configurable: Extensive configuration options for different team workflows

📦 Installation

npm install claude-conversation-tracker

🛠️ Quick Start

One‑liner (curl)

Initialize in the current repo:

curl -fsSL https://unpkg.com/claude-conversation-tracker@latest/scripts/install.sh | bash

Start a monitored session immediately:

curl -fsSL https://unpkg.com/claude-conversation-tracker@latest/scripts/monitor.sh | bash -s -- "Refactor utils and add tests"

Zero‑install (npx)

# Setup current repo (copies hooks, creates .talk/ and .claudeconfig)
npx claude-conversation-tracker init

# Start auto-tracking watcher (safe defaults: no auto-commit/MR)
npx claude-conversation-tracker monitor "Refactor utils and add tests"

Claude Code Integration

1. Install the package:

   npm install -g claude-conversation-tracker

2. Configure Claude Code hooks in your settings.json:

   {
     "hooks": [
       {
         "matcher": { "event": "SessionStart" },
         "script": "claude-code-hook.js",
         "function": "handleHook"
       },
       {
         "matcher": {
           "event": "PostToolUse",
           "tool": ["Edit", "MultiEdit", "Write", "NotebookEdit"]
         },
         "script": "claude-code-hook.js",
         "function": "handleHook"
       },
       {
         "matcher": { "event": "SessionEnd" },
         "script": "claude-code-hook.js",
         "function": "handleHook"
       }
    ]

}

3. **Copy the hook script to your project (optional if you used npx init):**
 ```bash
cp node_modules/claude-conversation-tracker/claude-code-hook.js .

Or simply run: npx claude-conversation-tracker init

4. Config precedence and overrides (Claude Code):
   • The hook loads configuration in this order (highest wins):
     • Environment variables (TRACKER_*)
     • .talk/config.json (or .talk/config)
     • conversation-tracker.config.json
     • Built-in defaults
   • You can set TRACKER_TALK_DIR to point to a non-default .talk directory.

Codex CLI Integration

If you’re using Codex CLI or another tool that can invoke external scripts on events, use the provided codex-hook.js adapter:

1. Call the script with start, action, or end events (or pass-through SessionStart, PostToolUse, SessionEnd):

   node codex-hook.js start '{"initialMessage":"My task"}'
   node codex-hook.js action path/to/action.json
   node codex-hook.js end

2. Each action call should include a JSON payload with at least a tool object when available, e.g.:

   {
     "tool": { "name": "Edit", "parameters": { "file_path": "src/app.ts", "old_string": "...", "new_string": "..." } },
     "result": { "ok": true }
   }

The adapter maps to the same internal handler used for Claude Code hooks and will track changes identically.

Auto-Tracking for Codex

• Auto-start on first action: If an action arrives without a prior start, the tracker starts a conversation automatically.
• One-command watcher (recommended): use npm run track:auto "My task" or ./codex-autotrack.sh "My task" to start a background watcher that:
  • Starts a session (if not already active)
  • Detects file changes via git and emits action events with diffs
  • Ends the session when the shell exits

Example:

# Start a tracked shell and watch file changes
npm run track:auto "Refactor utils and add tests"

# or
./codex-autotrack.sh "Refactor utils and add tests"

# Make edits as usual; the watcher logs actions automatically
# When done, exit the shell (or run explicitly):
node codex-hook.js end

GitLab Quick Setup (MRs auto-created)

• Requirements:

  • git remote points at your GitLab (e.g. [email protected]:org/repo.git or self-hosted)
  • Install and login: glab auth login --hostname <your-gitlab-host>

• Configure the tracker (defaults are adjustable via JSON or env vars):

  • In conversation-tracker.config.json set:
    • "mergeRequestProvider": "gitlab"
    • "autoCreateMR": true
  • Or use environment variables for easy, per-session tweaks:

export TRACKER_MR_PROVIDER=gitlab
export TRACKER_AUTO_CREATE_MR=true
export TRACKER_DEFAULT_TARGET_BRANCH=main   # or master

With this, ending a session will push the branch and create a merge request using glab.

Environment Overrides (easy config for others)

Both hooks (claude-code-hook.js and codex-hook.js) honor the following env vars which override file configs:

• TRACKER_ENABLED (true/false)
• TRACKER_MR_PROVIDER (github|gitlab|azure|custom|none)
• TRACKER_AUTO_CREATE_MR (true/false)
• TRACKER_DEFAULT_TARGET_BRANCH (e.g., main/master)
• TRACKER_AUTO_CREATE_BRANCH (true/false)
• TRACKER_AUTO_COMMIT (true/false)
• TRACKER_TRACK_ALL_TOOLS (true/false)
• TRACKER_PREFER_LOW_LEVEL (true/false)
• TRACKER_AUTHOR_NAME, TRACKER_AUTHOR_EMAIL
• TRACKER_BRANCH_PREFIX, TRACKER_TALK_DIR

This makes it simple for teammates to adapt behavior without editing files.

Team defaults with .env:

• Create a .env file (see .env.example) to define your team’s default flags. The watcher auto-loads .env and passes variables to the hook.

Common flags:

• TRACKER_AUTO_CREATE_BRANCH, TRACKER_AUTO_COMMIT, TRACKER_AUTO_CREATE_MR
• TRACKER_MR_PROVIDER (github|gitlab|azure|custom|none), TRACKER_DEFAULT_TARGET_BRANCH
• TRACKER_AUTHOR_NAME, TRACKER_AUTHOR_EMAIL, TRACKER_TALK_DIR

Per‑project config (.talk/config.json):

• Place a JSON file at .talk/config.json (or .talk/config) in your repo to set project‑level defaults that all teammates inherit. Both hooks read this automatically and merge it after the root conversation-tracker.config.json and before env overrides.

Example .talk/config.json:

{
  "authorName": "Your Team AI",
  "authorEmail": "[email protected]",
  "autoCreateBranch": true,
  "autoCommit": true,
  "autoCreateMR": false,
  "mergeRequestProvider": "gitlab",
  "defaultTargetBranch": "main"
}

Precedence (highest wins):

• Environment variables (TRACKER_*)
• .talk/config.json
• conversation-tracker.config.json
• Built-in defaults

Programmatic Usage

import {
  ConversationTracker,
  ConfigManager,
  GitProviderFactory,
  MergeRequestProviderFactory
} from 'claude-conversation-tracker';

// Initialize with custom configuration
const config = new ConfigManager({
  branchPrefix: 'ai-conversation-',
  authorName: 'AI Assistant',
  autoCreateMR: true
});

// Create providers
const gitProvider = await GitProviderFactory.create();
const mrProvider = await MergeRequestProviderFactory.autoDetect();

// Initialize tracker
const tracker = new ConversationTracker(
  gitProvider,
  mrProvider,
  talkManager,
  changeAnalyzer,
  config.getConfig()
);

// Start tracking
const conversationId = await tracker.startConversation('Add new feature');

// Track changes
await tracker.trackToolUse({
  name: 'Edit',
  parameters: { file_path: 'src/feature.js' },
  filePath: 'src/feature.js'
});

// End conversation
const summary = await tracker.endConversation();

🔧 Configuration

Default Configuration

{
  enabled: true,
  autoCreateBranch: true,
  autoCommit: true,
  autoCreateMR: true,
  // Prefer classifying as Low-Level unless breaking
  preferLowLevel: true,
  // Track all tool uses, not only edits
  trackAllTools: true,

  branchPrefix: 'claude-conv-',
  talkDirectory: '.talk',

  authorName: 'Claude',
  authorEmail: '[email protected]',
  defaultTargetBranch: 'main',

  gitProvider: 'git',
  mergeRequestProvider: 'github'
}

Platform-Specific Hooks

{
  platformHooks: {
    'claude-code': {
      sessionStart: 'SessionStart',
      toolUse: 'PostToolUse',
      sessionEnd: 'SessionEnd'
    },
    'cursor': {
      sessionStart: 'onSessionStart',
      toolUse: 'onFileChange',
      sessionEnd: 'onSessionEnd'
    },
    'vscode': {
      sessionStart: 'onDidStartSession',
      toolUse: 'onDidExecuteCommand',
      sessionEnd: 'onDidEndSession'
    }
  }
}

📁 Generated Structure

.talk/
├── conversations/
│   ├── 2025-09-22T09-19-58-055Z.md
│   ├── 2025-09-22T14-30-15-123Z.md
│   └── ...
├── templates/
│   └── conversation-template.md
└── index.md

Example Conversation File

# Conversation Summary - 9/22/2025 9:19:58 AM

**ID:** 2025-09-22T09-19-58-055Z
**Branch:** `claude-conv-2025-09-22T09-19-58-055Z`
**Commit:** `abc123def456`

## Initial Prompt
Add authentication middleware to the API

## High-Level Breaking Changes ⚠️
- **package.json**: Added new authentication dependencies

## Mid-Level Changes ⚡
- **middleware/auth.js**: Implemented JWT authentication logic

## Low-Level Confident Changes ✅
- **routes/api.js**: Added authentication middleware to routes
- **tests/auth.test.js**: Added comprehensive test suite

## Files Modified
- `package.json`
- `src/middleware/auth.js`
- `src/routes/api.js`
- `tests/auth.test.js`

## Summary Statistics
- **Total Changes:** 4
- **Files Modified:** 4
- **Breaking Changes:** 1
- **Feature Changes:** 1
- **Safe Changes:** 2

🔍 Change Impact Classification

High-Level (⚠️) Breaking Changes

• Package/dependency modifications
• API-breaking changes
• Architecture changes
• Configuration changes

Mid-Level (⚡) Potentially Misleading

• Complex logic modifications
• New feature implementations
• Significant refactoring
• Algorithm changes

Low-Level (✅) Confident Changes

• Bug fixes
• Documentation updates
• Code formatting
• Simple feature additions

🌐 Platform Support

Git Providers

• ✅ Standard Git: Works with any git repository
• ✅ GitHub: Full integration with gh CLI
• ✅ GitLab: Full integration with glab CLI
• ✅ Azure DevOps: Integration with az CLI
• ✅ Custom: Configurable custom commands

Merge Request Providers

• ✅ GitHub: Automatic PR creation
• ✅ GitLab: Automatic MR creation
• ✅ Azure DevOps: Automatic PR creation
• ✅ Custom: Configurable custom commands
• ✅ None: Disable MR creation

AI Code Assistants

• ✅ Claude Code: Native hook integration
• ✅ Cursor: Hook-based integration
• ✅ VS Code Extensions: Event-based integration
• ✅ Custom: Programmatic API usage

🧪 Testing

Run the test suite:

npm test
# or
node test-runner.js

Test hook integration:

node claude-code-hook.js --test

📝 API Reference

Core Classes

• ConversationTracker: Main tracking orchestrator
• ConfigManager: Configuration management
• ChangeAnalyzer: Change impact analysis
• TalkFileManager: File and directory management
• GitProvider: Git operations abstraction
• MergeRequestProvider: MR/PR creation abstraction

Key Methods

// Start conversation tracking
startConversation(initialPrompt: string): Promise<string>

// Track individual tool usage
trackToolUse(toolUse: IToolUse): Promise<void>

// End conversation and generate summary
endConversation(): Promise<IConversationSummary>

// Analyze change impact
analyzeChange(toolUse: IToolUse): Promise<IChange>

🤝 Contributing

1. Fork the repository
2. Create your feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

📄 License

PolyForm Noncommercial License 1.0.0 — see the LICENSE file for details.

🆘 Support

• Create an issue on GitHub
• Check the documentation
• Join our community discussions

Generated with ❤️ for the AI coding community