🔍 CCTrace

cctrace — Record and replay your Claude Code sessions, making every prompt and output traceable and reviewable.

CCTrace is a developer tool for recording and replaying Claude Code (and other LLM) interactions, including prompts, responses, and file changes.

✨ Features

• 📝 Complete Recording: Captures every prompt input, LLM output, and file change
• 🔍 Smart Replay: Quick location of historical records by time, file, or conversation
• 📊 Data Analysis: Token consumption statistics and interaction analysis
• 🌐 Web Interface: Intuitive visual interface for viewing and searching interaction history
• 🚀 Lightweight: Local SQLite storage with no additional services required

🛠️ Tech Stack

• CLI: TypeScript + Node.js + Commander.js + Prisma
• Frontend: Vue 3 + Vite + TypeScript
• Database: SQLite + Prisma ORM
• Monitoring: Chokidar (file changes) + custom parser

📦 Installation

Prerequisites

• Node.js >= 18.0.0
• npm or yarn

Install from NPM

npm install -g cctrace

Install from Source

git clone https://github.com/labspc/cctrace.git
cd cctrace
npm install
npm run build
npm link

🚀 Usage

CLI Commands

Start Monitoring

# Monitor current directory
cctrace start

# Monitor specific directory
cctrace start -p /path/to/project

View Sessions

# Show recent 10 sessions
cctrace list

# Show recent 20 sessions
cctrace list -l 20

View Session Details

cctrace show <session-id>

Web Interface

1. Start the web interface:

# Navigate to your ccreplay installation
cd node_modules/cctrace/src/web
npm run dev

2. Open browser: http://localhost:5173

Interactive Mode

When running cctrace start, you enter interactive mode:

• :prompt <text> - Record user input prompt
• :response <text> - Record AI response
• :tokens <number> - Set token count for this interaction
• :save - Save current interaction to database
• :quit - Exit monitoring

Usage Example

1. Start monitoring:

cctrace start

2. In interactive mode:

:prompt Create a React component for user login
:response I'll help you create a React login component...
:tokens 245
:save

3. File changes are automatically detected and recorded

4. Use the web interface to view and analyze interaction history

🎯 Use Cases

1. Code Auditing: Track the generation process and context of code segments
2. Learning Review: Analyze which prompt writing styles are more effective
3. Error Tracking: Quickly locate when and how bugs were introduced
4. Team Collaboration: Share and summarize LLM-assisted development experiences

📁 Project Structure

cctrace/
├── dist/            # Built CLI tool
├── prisma/          # Database models
├── src/
│   ├── cli/         # CLI implementation
│   ├── core/        # Core functionality
│   ├── database/    # Database connection
│   └── web/         # Vue frontend project
└── docs/            # Documentation

🔧 Development

Development Environment

1. Start CLI development mode:

npm run dev

2. Start frontend development:

npm run web:dev

Database Operations

# Generate Prisma Client
npm run db:generate

# Push schema to database
npm run db:push

# Migrate database
npm run db:migrate

🤝 Contributing

Issues and Pull Requests are welcome!

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

📄 License

MIT License - see the LICENSE file for details.

👨‍💻 Author

Created by labspc (labspc.com)

🔮 Roadmap

• [ ] Support for more LLM tools (GPT, Gemini, etc.)
• [ ] Team collaboration features
• [ ] AI-driven prompt optimization suggestions
• [ ] Enhanced data visualization
• [ ] Plugin system

Version: v202508
Homepage: https://github.com/labspc/cctrace
Issues: https://github.com/labspc/cctrace/issues