From 443592d6c77e437a4aecf4d533c75d9e1daec5f4 Mon Sep 17 00:00:00 2001 From: Harivansh Rathi Date: Wed, 31 Dec 2025 00:39:19 +0530 Subject: [PATCH] continual learning setup --- README.md | 159 +++++++++++++++++++++++++++++ commands/retrospective.md | 73 +++++++++++++ commands/setup-agent.md | 73 +++++++++++++ hooks/session-end.sh | 47 +++++++++ install.sh | 136 ++++++++++++++++++++++++ settings.json | 15 +++ skills/codebase-agent/SKILL.md | 31 ++++++ skills/codebase-agent/learnings.md | 44 ++++++++ 8 files changed, 578 insertions(+) create mode 100644 README.md create mode 100644 commands/retrospective.md create mode 100644 commands/setup-agent.md create mode 100755 hooks/session-end.sh create mode 100755 install.sh create mode 100644 settings.json create mode 100644 skills/codebase-agent/SKILL.md create mode 100644 skills/codebase-agent/learnings.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..10c778a --- /dev/null +++ b/README.md @@ -0,0 +1,159 @@ +# Continual Learning System for Claude Code + +A self-improving coding agent that learns from every session. Patterns, failures, edge cases, and insights are automatically extracted and stored, making the agent smarter over time. + +## How It Works + +``` +Session 1: You code with Claude + | + v +SessionEnd Hook fires + | + v +/retrospective extracts learnings + | + v +learnings.md is updated + | + v +Session 2: Agent applies learnings from Session 1 + | + v +(repeat - agent gets smarter each session) +``` + +## Quick Start + +### 1. Install + +```bash +# Clone this repo +git clone https://github.com/YOUR_ORG/continual-learning.git +cd continual-learning + +# Install to your project +./install.sh /path/to/your/project +``` + +### 2. Set Up the Agent + +```bash +cd /path/to/your/project +claude + +# In Claude Code, run: +> /setup-agent +``` + +This analyzes your codebase and configures the agent with project-specific context. + +### 3. Start Coding + +Just work normally with Claude Code. After each session: +- The `SessionEnd` hook automatically runs +- `/retrospective` analyzes what happened +- New learnings are added to `learnings.md` +- Next session benefits from accumulated knowledge + +## What Gets Installed + +``` +your-project/ ++-- .claude/ + +-- skills/ + | +-- codebase-agent/ + | +-- SKILL.md # Main agent skill + | +-- learnings.md # Accumulated learnings (grows over time) + | + +-- commands/ + | +-- setup-agent.md # /setup-agent - Initial setup + | +-- retrospective.md # /retrospective - Extract learnings + | + +-- hooks/ + | +-- session-end.sh # Auto-triggers after sessions + | + +-- settings.json # Hook configuration +``` + +## Manual Commands + +While learning happens automatically, you can also trigger it manually: + +- `/setup-agent` - Re-analyze codebase and update skill context +- `/retrospective` - Manually run learning extraction + +## Customization + +### Adjust the Skill + +Edit `.claude/skills/codebase-agent/SKILL.md` to: +- Add project-specific instructions +- Modify the agent's behavior +- Include additional context + +### Adjust Learning Extraction + +Edit `.claude/commands/retrospective.md` to: +- Change what categories of learnings to extract +- Modify the format of learnings +- Adjust selectivity (what gets saved vs skipped) + +### Disable Automatic Learning + +Remove the hook from `.claude/settings.json` to disable automatic learning. +You can still run `/retrospective` manually when you want. + +## Requirements + +- Claude Code (latest version) +- `jq` command-line tool (for parsing JSON in hooks) + +Install jq if needed: +```bash +# macOS +brew install jq + +# Ubuntu/Debian +apt-get install jq +``` + +## How Learnings Are Structured + +Learnings in `learnings.md` are organized into categories: + +- **Patterns**: Successful approaches to reuse +- **Failures**: Mistakes to avoid +- **Edge Cases**: Tricky scenarios to remember +- **Technology Insights**: Framework/library-specific knowledge +- **Conventions**: Project coding conventions + +Each learning follows this format: + +```markdown +### [Short Title] +- **Context**: When this applies +- **Learning**: The insight +- **Example**: Code snippet (optional) +``` + +## Philosophy + +This system is based on the idea that: + +1. **Agents should learn** - Not just follow static instructions +2. **Every session has insights** - Patterns, failures, edge cases +3. **Compounding knowledge** - Each session builds on previous ones +4. **Human-readable memory** - Learnings are plain markdown, easy to review/edit +5. **Shareable knowledge** - Commit learnings.md to git for team benefit + +## Contributing + +1. Fork the repo +2. Make changes +3. Test by installing to a real project +4. Submit a PR + +## License + +MIT diff --git a/commands/retrospective.md b/commands/retrospective.md new file mode 100644 index 0000000..78708fe --- /dev/null +++ b/commands/retrospective.md @@ -0,0 +1,73 @@ +--- +description: Analyze the current session and extract learnings to memory +allowed-tools: Read, Edit +--- + +# Session Retrospective + +Analyze this coding session and extract valuable learnings to improve future sessions. + +## Your Task + +### 1. Review What Happened This Session + +Reflect on the session: +- What code was written or modified? +- What problems were solved? +- What approaches were tried (both successful and unsuccessful)? +- Were there any surprises or unexpected behaviors? + +### 2. Identify Learnings + +Extract insights in these categories: + +**Patterns (what worked well)**: +- Successful approaches that should be reused +- Code patterns that solved problems effectively +- Workflows that were efficient + +**Failures (what to avoid)**: +- Approaches that didn't work +- Bugs that were encountered and their root causes +- Time wasted on wrong paths +- Assumptions that turned out to be wrong + +**Edge Cases**: +- Tricky scenarios discovered +- Non-obvious behavior found +- Boundary conditions that matter + +**Technology Insights**: +- Framework/library-specific knowledge gained +- API quirks discovered +- Performance considerations learned + +### 3. Update learnings.md + +Edit `.claude/skills/codebase-agent/learnings.md` and add new entries under the appropriate sections. + +Use this format for each entry: + +```markdown +### [Short Descriptive Title] +- **Context**: When does this apply? +- **Learning**: What is the insight? +- **Example**: (optional) Code snippet or concrete example +- **Session**: [Date or brief session description] +``` + +### 4. Quality Guidelines + +Be selective about what to add: +- **Add** genuinely useful, project-specific insights +- **Skip** general programming knowledge (things any developer would know) +- **Skip** one-time fixes that won't recur +- **Avoid** duplicating existing entries +- **Merge** with existing entries if they're related + +## Output + +Summarize: +1. How many learnings were added (and to which categories) +2. Brief description of the most important insights +3. Any patterns emerging across sessions diff --git a/commands/setup-agent.md b/commands/setup-agent.md new file mode 100644 index 0000000..1b2ab7f --- /dev/null +++ b/commands/setup-agent.md @@ -0,0 +1,73 @@ +--- +description: Analyze codebase and set up the learning agent (run once after install) +allowed-tools: Read, Grep, Glob, Edit +--- + +# Initial Codebase Assessment + +You are setting up the continual learning agent for this codebase. This is a one-time setup that analyzes the project and configures the agent. + +## Your Task + +### 1. Analyze the Codebase Structure + +Explore the project to understand: +- **Directory structure**: What are the key directories and their purposes? +- **Tech stack**: What languages, frameworks, and libraries are used? +- **Configuration files**: Find package.json, tsconfig.json, pyproject.toml, Cargo.toml, etc. +- **Build tools**: How is the project built and tested? +- **Entry points**: Where does the application start? + +### 2. Discover Conventions + +Look for patterns in the existing code: +- **Code style**: Indentation, naming conventions, file organization +- **Architectural patterns**: MVC, component-based, microservices, etc. +- **Testing patterns**: How are tests structured? What testing frameworks? +- **Documentation patterns**: How is code documented? + +### 3. Update the Skill File + +Edit `.claude/skills/codebase-agent/SKILL.md` and replace the `## Codebase Context` section with your findings: + +```markdown +## Codebase Context + +### Architecture +[Brief overview of the architecture] + +### Tech Stack +- **Language(s)**: [e.g., TypeScript, Python] +- **Framework(s)**: [e.g., React, FastAPI] +- **Key Libraries**: [important dependencies] + +### Key Directories +- `src/` - [purpose] +- `tests/` - [purpose] +- [etc.] + +### Build & Test Commands +- Build: `[command]` +- Test: `[command]` +- Lint: `[command]` + +### Conventions +- [Convention 1] +- [Convention 2] +``` + +### 4. Initialize Learnings + +Edit `.claude/skills/codebase-agent/learnings.md` and add any initial observations: +- Obvious patterns you notice in the code +- Potential edge cases visible in the structure +- Tech stack insights that would be helpful to remember + +## Output + +After completing the assessment: +1. Summarize what you learned about the codebase +2. Confirm the skill file has been updated +3. Note any initial learnings added + +The agent is now ready for coding. Future sessions will automatically accumulate more learnings! diff --git a/hooks/session-end.sh b/hooks/session-end.sh new file mode 100755 index 0000000..fb4dd83 --- /dev/null +++ b/hooks/session-end.sh @@ -0,0 +1,47 @@ +#!/bin/bash +# SessionEnd Hook - Triggers learning extraction +# +# This hook runs automatically after each Claude Code session. +# It spawns a background process to analyze the session and update learnings. +# + +# Read hook input from stdin (JSON with session info) +INPUT=$(cat) + +# Extract transcript path using jq (required dependency) +if ! command -v jq &> /dev/null; then + # jq not available, skip silently + exit 0 +fi + +TRANSCRIPT=$(echo "$INPUT" | jq -r '.transcript_path // empty') +SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty') +PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}" + +# Validate transcript exists +if [ -z "$TRANSCRIPT" ] || [ ! -f "$TRANSCRIPT" ]; then + exit 0 +fi + +# Only run retrospective if session was substantial (more than 10 lines) +LINE_COUNT=$(wc -l < "$TRANSCRIPT" 2>/dev/null || echo "0") +if [ "$LINE_COUNT" -lt 10 ]; then + exit 0 +fi + +# Check if learnings.md exists (system is properly set up) +LEARNINGS_FILE="$PROJECT_DIR/.claude/skills/codebase-agent/learnings.md" +if [ ! -f "$LEARNINGS_FILE" ]; then + exit 0 +fi + +# Run retrospective in background using claude -p +# This uses Claude Code's existing authentication +( + claude -p "Run /retrospective to analyze the session and extract learnings. The session transcript is at: $TRANSCRIPT" \ + --cwd "$PROJECT_DIR" \ + 2>/dev/null +) & + +# Exit immediately - don't wait for background process +exit 0 diff --git a/install.sh b/install.sh new file mode 100755 index 0000000..f5205af --- /dev/null +++ b/install.sh @@ -0,0 +1,136 @@ +#!/bin/bash +# Continual Learning System Installer +# +# Usage: +# curl -fsSL https://raw.githubusercontent.com/YOUR_ORG/continual-learning/main/install.sh | bash +# or: ./install.sh [target-dir] +# +# This installer: +# 1. Copies skills, commands, and hooks to your project's .claude/ directory +# 2. Configures the SessionEnd hook +# 3. Prompts you to run /setup-agent to initialize the agent +# + +set -e + +# Colors for output +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +NC='\033[0m' # No Color + +# Determine target directory +TARGET_DIR="${1:-.}" +TARGET_DIR=$(cd "$TARGET_DIR" && pwd) + +# Determine script location (for local installs) +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" + +echo -e "${GREEN}Continual Learning System Installer${NC}" +echo "Installing to: $TARGET_DIR" +echo "" + +# Check if .claude directory exists +if [ -d "$TARGET_DIR/.claude" ]; then + echo -e "${YELLOW}Warning: .claude directory already exists${NC}" + read -p "Continue and merge files? (y/n) " -n 1 -r + echo + if [[ ! $REPLY =~ ^[Yy]$ ]]; then + echo "Aborted." + exit 1 + fi +fi + +# Create directory structure +echo "Creating directory structure..." +mkdir -p "$TARGET_DIR/.claude/skills/codebase-agent" +mkdir -p "$TARGET_DIR/.claude/commands" +mkdir -p "$TARGET_DIR/.claude/hooks" + +# Copy files +echo "Copying files..." + +# Function to copy file from local or download from remote +copy_file() { + local src="$1" + local dest="$2" + + if [ -f "$SCRIPT_DIR/$src" ]; then + # Local install + cp "$SCRIPT_DIR/$src" "$dest" + else + # Remote install - would need to update with actual repo URL + echo -e "${RED}Error: Source file not found: $src${NC}" + echo "For remote installation, update REPO_URL in this script." + exit 1 + fi +} + +copy_file "skills/codebase-agent/SKILL.md" "$TARGET_DIR/.claude/skills/codebase-agent/SKILL.md" +copy_file "skills/codebase-agent/learnings.md" "$TARGET_DIR/.claude/skills/codebase-agent/learnings.md" +copy_file "commands/setup-agent.md" "$TARGET_DIR/.claude/commands/setup-agent.md" +copy_file "commands/retrospective.md" "$TARGET_DIR/.claude/commands/retrospective.md" +copy_file "hooks/session-end.sh" "$TARGET_DIR/.claude/hooks/session-end.sh" + +# Make hook executable +chmod +x "$TARGET_DIR/.claude/hooks/session-end.sh" + +# Handle settings.json merge +echo "Configuring hooks..." +SETTINGS_FILE="$TARGET_DIR/.claude/settings.json" + +if [ -f "$SETTINGS_FILE" ]; then + # Merge with existing settings + echo -e "${YELLOW}Existing settings.json found. Please manually add the hook configuration:${NC}" + echo "" + cat << 'EOF' +Add to your .claude/settings.json: + +{ + "hooks": { + "SessionEnd": [ + { + "hooks": [ + { + "type": "command", + "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/session-end.sh\"", + "timeout": 60 + } + ] + } + ] + } +} +EOF + echo "" +else + # Create new settings.json + cat > "$SETTINGS_FILE" << 'EOF' +{ + "hooks": { + "SessionEnd": [ + { + "hooks": [ + { + "type": "command", + "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/session-end.sh\"", + "timeout": 60 + } + ] + } + ] + } +} +EOF +fi + +echo "" +echo -e "${GREEN}Installation complete!${NC}" +echo "" +echo "Next steps:" +echo " 1. cd $TARGET_DIR" +echo " 2. Run: claude" +echo " 3. Type: /setup-agent" +echo "" +echo "This will analyze your codebase and set up the learning agent." +echo "After that, the agent will automatically learn from each session!" diff --git a/settings.json b/settings.json new file mode 100644 index 0000000..300c00d --- /dev/null +++ b/settings.json @@ -0,0 +1,15 @@ +{ + "hooks": { + "SessionEnd": [ + { + "hooks": [ + { + "type": "command", + "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/session-end.sh\"", + "timeout": 60 + } + ] + } + ] + } +} diff --git a/skills/codebase-agent/SKILL.md b/skills/codebase-agent/SKILL.md new file mode 100644 index 0000000..f2f3994 --- /dev/null +++ b/skills/codebase-agent/SKILL.md @@ -0,0 +1,31 @@ +--- +name: codebase-agent +description: | + Expert coding agent for this codebase. Learns from every session to improve + code quality, catch edge cases, and apply proven patterns. Use for ANY coding + task: writing, debugging, refactoring, testing. Accumulates project knowledge. +allowed-tools: Read, Write, Edit, Bash, Grep, Glob +--- + +# Codebase Expert Agent + +You are an expert coding agent that learns and improves over time. + +## Accumulated Learnings + +Reference [learnings.md](learnings.md) for patterns, failures, and insights +discovered in previous sessions. Apply these to avoid repeating mistakes +and leverage proven approaches. + +## Behavior + +1. **Check learnings first**: Before implementing, scan learnings.md for relevant patterns and failures +2. **Apply proven patterns**: Use approaches that worked in past sessions +3. **Follow conventions**: Adhere to project conventions discovered in learnings +4. **Note discoveries**: When you find something new (pattern, failure, edge case), mention it + +## Codebase Context + + + + diff --git a/skills/codebase-agent/learnings.md b/skills/codebase-agent/learnings.md new file mode 100644 index 0000000..cd1e5d6 --- /dev/null +++ b/skills/codebase-agent/learnings.md @@ -0,0 +1,44 @@ +# Accumulated Learnings + +This file is automatically updated after each coding session. +The SessionEnd hook triggers `/retrospective` which analyzes the session and adds new learnings here. + +--- + +## Patterns (What Works) + +Successful approaches and code patterns that should be reused. + + + +--- + +## Failures (What to Avoid) + +Approaches that failed, bugs encountered, and time-wasting paths. + + + +--- + +## Edge Cases + +Tricky scenarios and non-obvious behaviors discovered during development. + + + +--- + +## Technology Insights + +Framework-specific knowledge, library quirks, and API insights. + + + +--- + +## Conventions + +Project-specific coding conventions and style guidelines. + +