codesurf-insights

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 only
• all: 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

1. Edit files in singular folders (agent/, command/, skill/)
2. Run ./sync.sh or just commit (pre-commit hook runs sync automatically)
3. 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