https://github.com/gitstq/agentscribe
๐ AI็ผ็ ไปฃ็ไผ่ฏ่ฎฐๅฝไธๆบ่ฝๅๆๅทฅๅ
ท - Record, analyze and visualize AI coding agent sessions (Claude Code, Cursor, Windsurf, Copilot) ๐ป
https://github.com/gitstq/agentscribe
ai analytics claude-code cli code-analysis cursor developer-tools productivity python session-recorder
Last synced: 3 days ago
JSON representation
๐ AI็ผ็ ไปฃ็ไผ่ฏ่ฎฐๅฝไธๆบ่ฝๅๆๅทฅๅ ท - Record, analyze and visualize AI coding agent sessions (Claude Code, Cursor, Windsurf, Copilot) ๐ป
- Host: GitHub
- URL: https://github.com/gitstq/agentscribe
- Owner: gitstq
- License: mit
- Created: 2026-06-14T16:17:21.000Z (10 days ago)
- Default Branch: main
- Last Pushed: 2026-06-14T16:19:53.000Z (10 days ago)
- Last Synced: 2026-06-14T18:13:21.284Z (10 days ago)
- Topics: ai, analytics, claude-code, cli, code-analysis, cursor, developer-tools, productivity, python, session-recorder
- Language: Python
- Homepage: https://github.com/gitstq/agentscribe
- Size: 97.7 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.en.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# ๐ AgentScribe
> **AI Coding Agent Session Recorder & Analytics Tool**
> Record, analyze and visualize AI coding agent sessions (Claude Code, Cursor, Windsurf, Copilot)
---
## ๐ Introduction
**AgentScribe** is a **session recording and analytics tool** designed for AI coding agents. It records, replays, and analyzes your interactions with AI coding agents (such as Claude Code, Cursor, Windsurf, GitHub Copilot, Codex, and more), helping you to:
- ๐ **Understand Agent Behavior** - Track decision processes and tool calls in every session
- ๐ฐ **Optimize Token Costs** - Count token consumption, estimate usage costs
- ๐ **Retrospective Sessions** - Quickly search and replay past coding sessions
- ๐ **Generate Analytics Reports** - Output beautiful HTML visualization reports
- ๐ง **Discover Usage Patterns** - Identify high-frequency tool calls and coding patterns
> **Design Philosophy:** Local-first, data privacy paramount. All session data is stored in your local SQLite database โ no network required, no data leakage risk.
---
## โจ Key Features
| Feature | Description |
|---------|-------------|
| ๐ฌ **Session Recording** | Interactively record complete AI coding agent sessions including user messages, AI responses, and tool calls |
| ๐ **Session List** | Browse historical sessions by time, agent, model, and more |
| ๐ **Detail View** | Dive into each message's content, token consumption, and tool call details |
| ๐ **Global Statistics** | Aggregate token, cost, and duration statistics across all sessions |
| ๐ **HTML Reports** | Generate beautiful interactive HTML analytics reports for sharing and archiving |
| ๐พ **Data Export** | Export sessions in JSON and Markdown formats |
| ๐ค **Multi-Agent Support** | Compatible with Claude Code, Cursor, Windsurf, GitHub Copilot, Codex and more |
| ๐ฅ๏ธ **Interactive Dashboard** | Built-in interactive CLI dashboard for one-stop session management |
| ๐ท๏ธ **Tag System** | Add custom tags to sessions for easy categorization and retrieval |
| ๐งน **Data Management** | Session deletion and batch cleanup functionality |
---
## ๐ Quick Start
### Prerequisites
- Python 3.10+
- pip (Python package manager)
### One-Click Install
```bash
# Option 1: pip install (recommended)
pip install agentscribe
# Option 2: Install from source
git clone https://github.com/gitstq/agentscribe.git
cd agentscribe
pip install -e .
# Option 3: Use install script
chmod +x scripts/install.sh
./scripts/install.sh
```
### Verify Installation
```bash
agentscribe --version
agentscribe --help
```
---
## ๐ Usage Guide
### ๐ List Sessions
```bash
# List recent 20 sessions
agentscribe list
# Filter by specific agent
agentscribe list --agent claude-code
# JSON format output
agentscribe list --json
```
### ๐ฌ Record a New Session
```bash
# Interactive recording
agentscribe record
# Specify agent and model
agentscribe record --agent cursor --model gpt-4o --project /path/to/project
# Add tags
agentscribe record --tag frontend --tag refactor
```
### ๐ View Session Details
```bash
# View specific session details
agentscribe view session_20260614_1a2b3c4d
# JSON format output
agentscribe view session_20260614_1a2b3c4d --json
```
### ๐ View Statistics
```bash
# View global statistics
agentscribe stats
```
### ๐ Generate Report
```bash
# Generate HTML analytics report
agentscribe report
# Specify output path and auto-open
agentscribe report --output ./report.html --open
```
### ๐พ Export Session
```bash
# Export as JSON
agentscribe export session_20260614_1a2b3c4d
# Export as Markdown
agentscribe export session_20260614_1a2b3c4d --format markdown
```
### ๐๏ธ Delete Session
```bash
agentscribe delete session_20260614_1a2b3c4d
```
### ๐ฅ๏ธ Interactive Dashboard
```bash
# Start interactive mode
agentscribe dashboard
```
---
## ๐ก Design Philosophy & Roadmap
### Design Principles
1. **Local-First** - All data stored in local SQLite, no network required, privacy secure
2. **CLI Native** - Powerful command-line interface suitable for developer daily workflow
3. **Modular Architecture** - Storage, analysis, and reporting modules are independent and extensible
4. **Open Formats** - Support JSON/Markdown/HTML multiple data export formats
### Architecture
```
agentscribe/
โโโ agentscribe/ # Core package
โ โโโ cli.py # CLI entry point (Click framework)
โ โโโ storage.py # SQLite storage engine
โ โโโ analyzer.py # Analysis engine (cost/pattern/stats)
โ โโโ reporter.py # HTML report generator
โ โโโ models.py # Data models
โ โโโ config.py # Configuration management
โ โโโ utils.py # Utility functions
โโโ tests/ # Unit tests
โโโ scripts/ # Install scripts
โโโ setup.py # Build configuration
โโโ requirements.txt # Dependency management
```
### Roadmap
- **v0.2.0** - Automatic agent session sniffing (no manual recording)
- **v0.3.0** - Cross-session pattern recognition and smart suggestions
- **v0.4.0** - Multi-user/team collaboration support
- **v0.5.0** - Web visualization dashboard
- **v1.0.0** - Stable release, plugin ecosystem
---
## ๐ฆ Build & Deploy
### Build Distribution Package
```bash
# Install build tools
pip install build
# Build source and wheel packages
python -m build
# Artifacts in dist/
ls dist/
```
### Run Tests
```bash
# Install test dependencies
pip install pytest flake8
# Run all tests
pytest tests/ -v
# Run code linting
flake8 agentscribe/
```
---
## ๐ค Contributing
Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
- ๐ **Report Bugs** - [Create an Issue](https://github.com/gitstq/agentscribe/issues/new?template=bug_report.md)
- ๐ก **Feature Requests** - [Submit a Feature Request](https://github.com/gitstq/agentscribe/issues/new?template=feature_request.md)
- ๐ **Improve Docs** - Help us improve documentation quality
- ๐ง **Submit Code** - Submit a Pull Request to fix issues or add features
---
## ๐ License
This project is open-sourced under the [MIT License](LICENSE).
---
AgentScribe โ Make every AI coding agent interaction traceable ๐
GitHub ยท
Issues ยท
Releases