codesurf-insights
Learn from conversation history to continuously improve AI coding assistant performance.
Cross-compatible: Works with both Claude Code and OpenCode.
Quick Start
Claude Code Installation
# Option 1: Symlink (recommended - always up to date)
ln -s ~/.claude/plugins/codesurf-insights ~/.claude/plugins/codesurf-insights
# Option 2: Direct path
claude --plugin-dir ~/.claude/plugins/codesurf-insights
Verify it works:
claude
# Then type: /codesurf-insights:analyze
# Should see: "Analyzing conversations..."
OpenCode Installation
# Copy to OpenCode plugins directory
mkdir -p ~/.config/opencode/plugins
cp -r ~/.claude/plugins/codesurf-insights ~/.config/opencode/plugins/
Verify it works:
opencode
# Then type: /analyze
# Should see: "Analyzing conversations..."
Commands
| Claude Code | OpenCode | Description |
|---|
/codesurf-insights:analyze [project|all] | /analyze [project|all] | Analyze conversations, extract insights |
/codesurf-insights:compact [project|all] | /compact [project|all] | Archive detritus, clean logs |
/codesurf-insights:report | /report | Generate insights summary |
Arguments
project (default): Current project onlyall: All projects globally{project-name}: Specific project by name
Features
Conversation Analysis
Extracts insights across 6 dimensions:
- User Communication: How clearly you convey requests
- Model Understanding: Where the model misunderstands
- Assumptions: Incorrect assumptions made
- Efficiency: Wasted tokens, unnecessary loops
- Lessons Learned: Actionable improvements
- Language Patterns: Terminology that helps/hurts
Automatic Learning
Post-session hook analyzes conversations and updates CLAUDE.md with lessons:
<!-- codesurf-insights: START -->
## Learned Insights (Auto-generated: 2026-01-01)
### CRITICAL: File Paths in Hooks
**cwd resets between bash calls - 23 failures from relative paths**
<!-- codesurf-insights: END -->
Log Compaction
Archives detritus (failed loops, noise, small talk) to keep logs clean and focused.
Example Output
Analysis Complete
═══════════════════════════════════════════════════════════════
Conversations analyzed: 5 (largest, 2.3MB total)
Total messages: 826
Detritus flagged: ~177 correction cycles
Insights extracted: 10 critical patterns
Top Insights:
1. [CRITICAL] File paths - use absolute (23 failures from relative)
2. [CRITICAL] Error format - [file:line] + 5 context = 92% success
3. [CRITICAL] Hook state - file-based only (cwd resets)
4. [CRITICAL] Scope - fix ONLY what's asked (18 overreach instances)
5. [EFFICIENCY] Max 1 apology (47 instances = 14K wasted tokens)
Full reports: ~/.claude/insights/reports/
├── README.md - Guide to reports
├── SUMMARY.md - 2-min overview
├── TOP-INSIGHTS.md - Top 10 actionable items
└── claude-md-additions.md - Ready-to-paste sections
CLAUDE.md updated with 10 new insights
═══════════════════════════════════════════════════════════════
Cross-Compatibility Architecture
This plugin maintains parallel folder structures for both tools:
codesurf-insights/
├── .claude-plugin/
│ └── plugin.json # Claude Code manifest
├── plugin.ts # OpenCode entry point
│
├── agent/ # OpenCode agents (EDIT THESE)
│ ├── conversation-analyzer.md
│ └── detritus-detector.md
├── agents/ # Claude Code agents (auto-synced)
│
├── command/ # OpenCode commands (EDIT THESE)
│ ├── analyze.md
│ ├── compact.md
│ └── report.md
├── commands/ # Claude Code commands (auto-synced)
│
├── skill/ # OpenCode skills (EDIT THESE)
│ └── conversation-analysis/
├── skills/ # Claude Code skills (auto-synced)
│
├── hooks/
│ └── hooks.json # Claude Code post-session hook
│
├── sync.sh # Syncs singular → plural folders
└── .githooks/
└── pre-commit # Auto-syncs before git commit
How Sync Works
- Edit files in singular folders (
agent/, command/, skill/)
- Run
./sync.sh or just commit (pre-commit hook runs sync automatically)
- Both tools get updates
| Component | Claude Code Reads | OpenCode Reads |
|---|
| Agents | agents/ | agent/ |
| Commands | commands/ | command/ |
| Skills | skills/ | skill/ |
| Hooks | hooks/hooks.json | plugin.ts |
| Manifest | .claude-plugin/plugin.json | (auto-detected) |
Configuration
Create ~/.claude/codesurf-insights.local.md to customize behavior:
# CodeSurf Insights Settings
## Analysis Depth
<!-- brief | detailed -->
depth: detailed
