Initial commit with translated description
This commit is contained in:
311
references/clawdbot-integration.md
Normal file
311
references/clawdbot-integration.md
Normal file
@@ -0,0 +1,311 @@
|
||||
# Clawdbot Integration Guide
|
||||
|
||||
Complete setup and usage guide for integrating the self-improvement skill with Clawdbot's distributed learning model.
|
||||
|
||||
## Overview
|
||||
|
||||
Clawdbot is a terminal-based AI coding assistant that uses workspace-based prompt injection. Unlike Claude Code's hook system, Clawdbot injects context from workspace files at session start and supports inter-agent communication.
|
||||
|
||||
## Architecture Comparison
|
||||
|
||||
| Feature | Claude Code | Clawdbot |
|
||||
|---------|------------|----------|
|
||||
| Learning storage | `.learnings/` in project | Workspace files (`~/clawd/`) |
|
||||
| Activation | Hooks (UserPromptSubmit) | Workspace injection at start |
|
||||
| Promotion targets | `CLAUDE.md`, `AGENTS.md` | `SOUL.md`, `TOOLS.md`, `AGENTS.md` |
|
||||
| Inter-agent comms | Not built-in | `sessions_*` tools |
|
||||
| Skill registry | Manual / agentskills.io | ClawdHub integration |
|
||||
|
||||
## Workspace Setup
|
||||
|
||||
### Default Structure
|
||||
|
||||
```
|
||||
~/clawd/ # Configurable via ~/.clawdbot/clawdbot.json
|
||||
├── AGENTS.md # Multi-agent coordination patterns
|
||||
├── SOUL.md # Behavioral guidelines and personality
|
||||
├── TOOLS.md # Tool capabilities and MCP gotchas
|
||||
├── skills/ # ClawdHub skills cache
|
||||
│ └── <skill-name>/
|
||||
│ └── SKILL.md
|
||||
└── sessions/ # Auto-managed session transcripts
|
||||
└── <session-id>.jsonl
|
||||
```
|
||||
|
||||
### Configuration
|
||||
|
||||
Edit `~/.clawdbot/clawdbot.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"workspace": "~/clawd",
|
||||
"model": "claude-sonnet-4-20250514",
|
||||
"inject_files": ["AGENTS.md", "SOUL.md", "TOOLS.md"],
|
||||
"session_history": true
|
||||
}
|
||||
```
|
||||
|
||||
## Injected Prompt Files
|
||||
|
||||
### AGENTS.md
|
||||
|
||||
Purpose: Multi-agent workflows and delegation patterns.
|
||||
|
||||
```markdown
|
||||
# Agent Coordination
|
||||
|
||||
## Delegation Rules
|
||||
- Use explore agent for open-ended codebase questions
|
||||
- Use research-agent for external documentation lookup
|
||||
- Use Plan agent before complex implementations
|
||||
|
||||
## Session Handoff
|
||||
When delegating to another session:
|
||||
1. Provide full context in the handoff message
|
||||
2. Include relevant file paths
|
||||
3. Specify expected output format
|
||||
```
|
||||
|
||||
### SOUL.md
|
||||
|
||||
Purpose: Behavioral guidelines and communication style.
|
||||
|
||||
```markdown
|
||||
# Behavioral Guidelines
|
||||
|
||||
## Communication Style
|
||||
- Be direct and concise
|
||||
- Avoid unnecessary caveats and disclaimers
|
||||
- Use technical language appropriate to context
|
||||
|
||||
## Decision Making
|
||||
- Prefer simple solutions over clever ones
|
||||
- Ask clarifying questions early
|
||||
- Explain trade-offs when presenting options
|
||||
|
||||
## Error Handling
|
||||
- Admit mistakes promptly
|
||||
- Provide corrected information immediately
|
||||
- Log significant errors to learnings
|
||||
```
|
||||
|
||||
### TOOLS.md
|
||||
|
||||
Purpose: Tool capabilities, MCP server knowledge, integration gotchas.
|
||||
|
||||
```markdown
|
||||
# Tool Knowledge
|
||||
|
||||
## MCP Servers
|
||||
|
||||
### atlassian
|
||||
- Use `search` for general queries across Jira/Confluence
|
||||
- Only use `searchJiraIssuesUsingJql` when JQL syntax is explicitly needed
|
||||
- CloudId can be extracted from URLs (tool handles conversion)
|
||||
- Page IDs are in URL path: `/pages/123456789/`
|
||||
|
||||
### leanix
|
||||
- Use external_id (not internal id) for lookups
|
||||
- expand_teams/expand_apps for nested data
|
||||
|
||||
## Built-in Tools
|
||||
|
||||
### Bash
|
||||
- Prefer specialized tools over bash (Read over cat, Glob over find)
|
||||
- Use for git operations, npm/pnpm, docker commands
|
||||
|
||||
### Task
|
||||
- Use explore agent for codebase questions
|
||||
- Use research-agent for external docs
|
||||
```
|
||||
|
||||
## Learning Workflow
|
||||
|
||||
### Capturing Learnings
|
||||
|
||||
1. **In-session**: Log to `.learnings/` as usual (project-specific)
|
||||
2. **Cross-project**: Promote to workspace files (clawdbot)
|
||||
|
||||
### Promotion Decision Tree
|
||||
|
||||
```
|
||||
Is the learning project-specific?
|
||||
├── Yes → Promote to CLAUDE.md or .learnings/
|
||||
└── No → Is it behavioral/style-related?
|
||||
├── Yes → Promote to SOUL.md
|
||||
└── No → Is it tool/MCP-related?
|
||||
├── Yes → Promote to TOOLS.md
|
||||
└── No → Promote to AGENTS.md (workflow)
|
||||
```
|
||||
|
||||
### Promotion Format Examples
|
||||
|
||||
**From learning:**
|
||||
> MCP atlassian server: search tool is for general queries. Only use JQL/CQL tools when user explicitly mentions JQL or CQL syntax.
|
||||
|
||||
**To TOOLS.md:**
|
||||
```markdown
|
||||
### atlassian
|
||||
- `search`: Use for general queries (default)
|
||||
- `searchJiraIssuesUsingJql`: Only when JQL explicitly requested
|
||||
- `searchConfluenceUsingCql`: Only when CQL explicitly requested
|
||||
```
|
||||
|
||||
## Inter-Agent Communication
|
||||
|
||||
Clawdbot provides tools for cross-session communication:
|
||||
|
||||
### sessions_list
|
||||
|
||||
View active and recent sessions:
|
||||
```
|
||||
sessions_list --active
|
||||
sessions_list --recent 10
|
||||
```
|
||||
|
||||
### sessions_history
|
||||
|
||||
Read transcript from another session:
|
||||
```
|
||||
sessions_history --session <session-id> --last 50
|
||||
```
|
||||
|
||||
### sessions_send
|
||||
|
||||
Send message to another session:
|
||||
```
|
||||
sessions_send --to <session-id> --message "Learning: API requires X-Custom-Header"
|
||||
```
|
||||
|
||||
### Learning Sharing Pattern
|
||||
|
||||
When discovering something valuable in session A:
|
||||
|
||||
1. Check if other sessions are working on related code:
|
||||
```
|
||||
sessions_list --active
|
||||
```
|
||||
|
||||
2. Share the learning:
|
||||
```
|
||||
sessions_send --to session-b --message "FYI: Discovered that the auth API requires refresh tokens every 30min"
|
||||
```
|
||||
|
||||
3. Log to workspace file if broadly applicable:
|
||||
- Edit `~/clawd/TOOLS.md` or appropriate file
|
||||
|
||||
## ClawdHub Integration
|
||||
|
||||
ClawdHub is Clawdbot's skill registry (similar to agentskills.io).
|
||||
|
||||
### Installing Skills
|
||||
|
||||
```bash
|
||||
clawd skill install <skill-name>
|
||||
```
|
||||
|
||||
Skills are cached in `~/clawd/skills/`.
|
||||
|
||||
### Publishing Skills
|
||||
|
||||
1. Create skill following agentskills.io spec
|
||||
2. Register with ClawdHub
|
||||
3. Skills become available to all Clawdbot users
|
||||
|
||||
### Skill Compatibility
|
||||
|
||||
Skills from this repo are compatible with:
|
||||
- Claude Code (via hooks)
|
||||
- Codex CLI (via hooks)
|
||||
- Clawdbot (via ClawdHub)
|
||||
- GitHub Copilot (via manual setup)
|
||||
|
||||
## Hybrid Setup: Claude Code + Clawdbot
|
||||
|
||||
When using both tools on the same codebase:
|
||||
|
||||
### Recommended Division
|
||||
|
||||
| Concern | Where to Store |
|
||||
|---------|---------------|
|
||||
| Project conventions | `CLAUDE.md` (in repo) |
|
||||
| Project learnings | `.learnings/` (in repo) |
|
||||
| Personal preferences | `SOUL.md` (clawdbot workspace) |
|
||||
| Tool knowledge | `TOOLS.md` (clawdbot workspace) |
|
||||
| Cross-project workflows | `AGENTS.md` (clawdbot workspace) |
|
||||
|
||||
### Sync Strategy
|
||||
|
||||
High-value learnings should exist in both:
|
||||
|
||||
1. Log to `.learnings/` first (project context)
|
||||
2. If broadly applicable, also add to clawdbot workspace
|
||||
3. Use consistent formatting for easy grep
|
||||
|
||||
### Example Dual Promotion
|
||||
|
||||
Learning: "Playwright tests require --headed flag for debugging"
|
||||
|
||||
**In `.learnings/LEARNINGS.md`:**
|
||||
```markdown
|
||||
## [LRN-20250126-001] correction
|
||||
|
||||
**Status**: promoted
|
||||
**Promoted**: CLAUDE.md, TOOLS.md (clawdbot)
|
||||
|
||||
### Summary
|
||||
Playwright tests require --headed flag for visual debugging
|
||||
|
||||
### Details
|
||||
...
|
||||
```
|
||||
|
||||
**In `CLAUDE.md`:**
|
||||
```markdown
|
||||
## Testing
|
||||
- Playwright debugging: use `--headed` flag
|
||||
```
|
||||
|
||||
**In `~/clawd/TOOLS.md`:**
|
||||
```markdown
|
||||
## Playwright
|
||||
- Debug mode: `npx playwright test --headed`
|
||||
- Trace viewer: `npx playwright show-trace trace.zip`
|
||||
```
|
||||
|
||||
## Detection Triggers for Clawdbot
|
||||
|
||||
### Standard Triggers (same as Claude Code)
|
||||
- User corrections
|
||||
- Command failures
|
||||
- API errors
|
||||
- Knowledge gaps
|
||||
|
||||
### Clawdbot-Specific Triggers
|
||||
|
||||
| Trigger | Action |
|
||||
|---------|--------|
|
||||
| MCP server error | Log to TOOLS.md with server name |
|
||||
| Session handoff confusion | Log to AGENTS.md with delegation pattern |
|
||||
| Model behavior surprise | Log to SOUL.md with expected vs actual |
|
||||
| ClawdHub skill issue | Log to TOOLS.md or report upstream |
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Workspace files not injected
|
||||
|
||||
Check `~/.clawdbot/clawdbot.json`:
|
||||
- Verify `workspace` path exists
|
||||
- Verify `inject_files` includes desired files
|
||||
|
||||
### Session communication fails
|
||||
|
||||
- Verify target session is active: `sessions_list --active`
|
||||
- Check session ID is correct
|
||||
- Session may have ended
|
||||
|
||||
### Learning not persisting
|
||||
|
||||
Clawdbot doesn't auto-persist learnings. You must:
|
||||
1. Explicitly write to workspace files
|
||||
2. Or use `.learnings/` for project-specific storage
|
||||
374
references/examples.md
Normal file
374
references/examples.md
Normal file
@@ -0,0 +1,374 @@
|
||||
# Entry Examples
|
||||
|
||||
Concrete examples of well-formatted entries with all fields.
|
||||
|
||||
## Learning: Correction
|
||||
|
||||
```markdown
|
||||
## [LRN-20250115-001] correction
|
||||
|
||||
**Logged**: 2025-01-15T10:30:00Z
|
||||
**Priority**: high
|
||||
**Status**: pending
|
||||
**Area**: tests
|
||||
|
||||
### Summary
|
||||
Incorrectly assumed pytest fixtures are scoped to function by default
|
||||
|
||||
### Details
|
||||
When writing test fixtures, I assumed all fixtures were function-scoped.
|
||||
User corrected that while function scope is the default, the codebase
|
||||
convention uses module-scoped fixtures for database connections to
|
||||
improve test performance.
|
||||
|
||||
### Suggested Action
|
||||
When creating fixtures that involve expensive setup (DB, network),
|
||||
check existing fixtures for scope patterns before defaulting to function scope.
|
||||
|
||||
### Metadata
|
||||
- Source: user_feedback
|
||||
- Related Files: tests/conftest.py
|
||||
- Tags: pytest, testing, fixtures
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
## Learning: Knowledge Gap (Resolved)
|
||||
|
||||
```markdown
|
||||
## [LRN-20250115-002] knowledge_gap
|
||||
|
||||
**Logged**: 2025-01-15T14:22:00Z
|
||||
**Priority**: medium
|
||||
**Status**: resolved
|
||||
**Area**: config
|
||||
|
||||
### Summary
|
||||
Project uses pnpm not npm for package management
|
||||
|
||||
### Details
|
||||
Attempted to run `npm install` but project uses pnpm workspaces.
|
||||
Lock file is `pnpm-lock.yaml`, not `package-lock.json`.
|
||||
|
||||
### Suggested Action
|
||||
Check for `pnpm-lock.yaml` or `pnpm-workspace.yaml` before assuming npm.
|
||||
Use `pnpm install` for this project.
|
||||
|
||||
### Metadata
|
||||
- Source: error
|
||||
- Related Files: pnpm-lock.yaml, pnpm-workspace.yaml
|
||||
- Tags: package-manager, pnpm, setup
|
||||
|
||||
### Resolution
|
||||
- **Resolved**: 2025-01-15T14:30:00Z
|
||||
- **Commit/PR**: N/A - knowledge update
|
||||
- **Notes**: Added to CLAUDE.md for future reference
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
## Learning: Promoted to CLAUDE.md
|
||||
|
||||
```markdown
|
||||
## [LRN-20250115-003] best_practice
|
||||
|
||||
**Logged**: 2025-01-15T16:00:00Z
|
||||
**Priority**: high
|
||||
**Status**: promoted
|
||||
**Promoted**: CLAUDE.md
|
||||
**Area**: backend
|
||||
|
||||
### Summary
|
||||
API responses must include correlation ID from request headers
|
||||
|
||||
### Details
|
||||
All API responses should echo back the X-Correlation-ID header from
|
||||
the request. This is required for distributed tracing. Responses
|
||||
without this header break the observability pipeline.
|
||||
|
||||
### Suggested Action
|
||||
Always include correlation ID passthrough in API handlers.
|
||||
|
||||
### Metadata
|
||||
- Source: user_feedback
|
||||
- Related Files: src/middleware/correlation.ts
|
||||
- Tags: api, observability, tracing
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
## Learning: Promoted to AGENTS.md
|
||||
|
||||
```markdown
|
||||
## [LRN-20250116-001] best_practice
|
||||
|
||||
**Logged**: 2025-01-16T09:00:00Z
|
||||
**Priority**: high
|
||||
**Status**: promoted
|
||||
**Promoted**: AGENTS.md
|
||||
**Area**: backend
|
||||
|
||||
### Summary
|
||||
Must regenerate API client after OpenAPI spec changes
|
||||
|
||||
### Details
|
||||
When modifying API endpoints, the TypeScript client must be regenerated.
|
||||
Forgetting this causes type mismatches that only appear at runtime.
|
||||
The generate script also runs validation.
|
||||
|
||||
### Suggested Action
|
||||
Add to agent workflow: after any API changes, run `pnpm run generate:api`.
|
||||
|
||||
### Metadata
|
||||
- Source: error
|
||||
- Related Files: openapi.yaml, src/client/api.ts
|
||||
- Tags: api, codegen, typescript
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
## Error Entry
|
||||
|
||||
```markdown
|
||||
## [ERR-20250115-A3F] docker_build
|
||||
|
||||
**Logged**: 2025-01-15T09:15:00Z
|
||||
**Priority**: high
|
||||
**Status**: pending
|
||||
**Area**: infra
|
||||
|
||||
### Summary
|
||||
Docker build fails on M1 Mac due to platform mismatch
|
||||
|
||||
### Error
|
||||
```
|
||||
error: failed to solve: python:3.11-slim: no match for platform linux/arm64
|
||||
```
|
||||
|
||||
### Context
|
||||
- Command: `docker build -t myapp .`
|
||||
- Dockerfile uses `FROM python:3.11-slim`
|
||||
- Running on Apple Silicon (M1/M2)
|
||||
|
||||
### Suggested Fix
|
||||
Add platform flag: `docker build --platform linux/amd64 -t myapp .`
|
||||
Or update Dockerfile: `FROM --platform=linux/amd64 python:3.11-slim`
|
||||
|
||||
### Metadata
|
||||
- Reproducible: yes
|
||||
- Related Files: Dockerfile
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
## Error Entry: Recurring Issue
|
||||
|
||||
```markdown
|
||||
## [ERR-20250120-B2C] api_timeout
|
||||
|
||||
**Logged**: 2025-01-20T11:30:00Z
|
||||
**Priority**: critical
|
||||
**Status**: pending
|
||||
**Area**: backend
|
||||
|
||||
### Summary
|
||||
Third-party payment API timeout during checkout
|
||||
|
||||
### Error
|
||||
```
|
||||
TimeoutError: Request to payments.example.com timed out after 30000ms
|
||||
```
|
||||
|
||||
### Context
|
||||
- Command: POST /api/checkout
|
||||
- Timeout set to 30s
|
||||
- Occurs during peak hours (lunch, evening)
|
||||
|
||||
### Suggested Fix
|
||||
Implement retry with exponential backoff. Consider circuit breaker pattern.
|
||||
|
||||
### Metadata
|
||||
- Reproducible: yes (during peak hours)
|
||||
- Related Files: src/services/payment.ts
|
||||
- See Also: ERR-20250115-X1Y, ERR-20250118-Z3W
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
## Feature Request
|
||||
|
||||
```markdown
|
||||
## [FEAT-20250115-001] export_to_csv
|
||||
|
||||
**Logged**: 2025-01-15T16:45:00Z
|
||||
**Priority**: medium
|
||||
**Status**: pending
|
||||
**Area**: backend
|
||||
|
||||
### Requested Capability
|
||||
Export analysis results to CSV format
|
||||
|
||||
### User Context
|
||||
User runs weekly reports and needs to share results with non-technical
|
||||
stakeholders in Excel. Currently copies output manually.
|
||||
|
||||
### Complexity Estimate
|
||||
simple
|
||||
|
||||
### Suggested Implementation
|
||||
Add `--output csv` flag to the analyze command. Use standard csv module.
|
||||
Could extend existing `--output json` pattern.
|
||||
|
||||
### Metadata
|
||||
- Frequency: recurring
|
||||
- Related Features: analyze command, json output
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
## Feature Request: Resolved
|
||||
|
||||
```markdown
|
||||
## [FEAT-20250110-002] dark_mode
|
||||
|
||||
**Logged**: 2025-01-10T14:00:00Z
|
||||
**Priority**: low
|
||||
**Status**: resolved
|
||||
**Area**: frontend
|
||||
|
||||
### Requested Capability
|
||||
Dark mode support for the dashboard
|
||||
|
||||
### User Context
|
||||
User works late hours and finds the bright interface straining.
|
||||
Several other users have mentioned this informally.
|
||||
|
||||
### Complexity Estimate
|
||||
medium
|
||||
|
||||
### Suggested Implementation
|
||||
Use CSS variables for colors. Add toggle in user settings.
|
||||
Consider system preference detection.
|
||||
|
||||
### Metadata
|
||||
- Frequency: recurring
|
||||
- Related Features: user settings, theme system
|
||||
|
||||
### Resolution
|
||||
- **Resolved**: 2025-01-18T16:00:00Z
|
||||
- **Commit/PR**: #142
|
||||
- **Notes**: Implemented with system preference detection and manual toggle
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
## Learning: Promoted to Skill
|
||||
|
||||
```markdown
|
||||
## [LRN-20250118-001] best_practice
|
||||
|
||||
**Logged**: 2025-01-18T11:00:00Z
|
||||
**Priority**: high
|
||||
**Status**: promoted_to_skill
|
||||
**Skill-Path**: skills/docker-m1-fixes
|
||||
**Area**: infra
|
||||
|
||||
### Summary
|
||||
Docker build fails on Apple Silicon due to platform mismatch
|
||||
|
||||
### Details
|
||||
When building Docker images on M1/M2 Macs, the build fails because
|
||||
the base image doesn't have an ARM64 variant. This is a common issue
|
||||
that affects many developers.
|
||||
|
||||
### Suggested Action
|
||||
Add `--platform linux/amd64` to docker build command, or use
|
||||
`FROM --platform=linux/amd64` in Dockerfile.
|
||||
|
||||
### Metadata
|
||||
- Source: error
|
||||
- Related Files: Dockerfile
|
||||
- Tags: docker, arm64, m1, apple-silicon
|
||||
- See Also: ERR-20250115-A3F, ERR-20250117-B2D
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
## Extracted Skill Example
|
||||
|
||||
When the above learning is extracted as a skill, it becomes:
|
||||
|
||||
**File**: `skills/docker-m1-fixes/SKILL.md`
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: docker-m1-fixes
|
||||
description: "Fixes Docker build failures on Apple Silicon (M1/M2). Use when docker build fails with platform mismatch errors."
|
||||
---
|
||||
|
||||
# Docker M1 Fixes
|
||||
|
||||
Solutions for Docker build issues on Apple Silicon Macs.
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Error | Fix |
|
||||
|-------|-----|
|
||||
| `no match for platform linux/arm64` | Add `--platform linux/amd64` to build |
|
||||
| Image runs but crashes | Use emulation or find ARM-compatible base |
|
||||
|
||||
## The Problem
|
||||
|
||||
Many Docker base images don't have ARM64 variants. When building on
|
||||
Apple Silicon (M1/M2/M3), Docker attempts to pull ARM64 images by
|
||||
default, causing platform mismatch errors.
|
||||
|
||||
## Solutions
|
||||
|
||||
### Option 1: Build Flag (Recommended)
|
||||
|
||||
Add platform flag to your build command:
|
||||
|
||||
\`\`\`bash
|
||||
docker build --platform linux/amd64 -t myapp .
|
||||
\`\`\`
|
||||
|
||||
### Option 2: Dockerfile Modification
|
||||
|
||||
Specify platform in the FROM instruction:
|
||||
|
||||
\`\`\`dockerfile
|
||||
FROM --platform=linux/amd64 python:3.11-slim
|
||||
\`\`\`
|
||||
|
||||
### Option 3: Docker Compose
|
||||
|
||||
Add platform to your service:
|
||||
|
||||
\`\`\`yaml
|
||||
services:
|
||||
app:
|
||||
platform: linux/amd64
|
||||
build: .
|
||||
\`\`\`
|
||||
|
||||
## Trade-offs
|
||||
|
||||
| Approach | Pros | Cons |
|
||||
|----------|------|------|
|
||||
| Build flag | No file changes | Must remember flag |
|
||||
| Dockerfile | Explicit, versioned | Affects all builds |
|
||||
| Compose | Convenient for dev | Requires compose |
|
||||
|
||||
## Performance Note
|
||||
|
||||
Running AMD64 images on ARM64 uses Rosetta 2 emulation. This works
|
||||
for development but may be slower. For production, find ARM-native
|
||||
alternatives when possible.
|
||||
|
||||
## Source
|
||||
|
||||
- Learning ID: LRN-20250118-001
|
||||
- Category: best_practice
|
||||
- Extraction Date: 2025-01-18
|
||||
```
|
||||
223
references/hooks-setup.md
Normal file
223
references/hooks-setup.md
Normal file
@@ -0,0 +1,223 @@
|
||||
# Hook Setup Guide
|
||||
|
||||
Configure automatic self-improvement triggers for AI coding agents.
|
||||
|
||||
## Overview
|
||||
|
||||
Hooks enable proactive learning capture by injecting reminders at key moments:
|
||||
- **UserPromptSubmit**: Reminder after each prompt to evaluate learnings
|
||||
- **PostToolUse (Bash)**: Error detection when commands fail
|
||||
|
||||
## Claude Code Setup
|
||||
|
||||
### Option 1: Project-Level Configuration
|
||||
|
||||
Create `.claude/settings.json` in your project root:
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"UserPromptSubmit": [
|
||||
{
|
||||
"matcher": "",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "./skills/self-improvement/scripts/activator.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"PostToolUse": [
|
||||
{
|
||||
"matcher": "Bash",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "./skills/self-improvement/scripts/error-detector.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Option 2: User-Level Configuration
|
||||
|
||||
Add to `~/.claude/settings.json` for global activation:
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"UserPromptSubmit": [
|
||||
{
|
||||
"matcher": "",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "~/.claude/skills/self-improvement/scripts/activator.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Minimal Setup (Activator Only)
|
||||
|
||||
For lower overhead, use only the UserPromptSubmit hook:
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"UserPromptSubmit": [
|
||||
{
|
||||
"matcher": "",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "./skills/self-improvement/scripts/activator.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Codex CLI Setup
|
||||
|
||||
Codex uses the same hook system as Claude Code. Create `.codex/settings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"UserPromptSubmit": [
|
||||
{
|
||||
"matcher": "",
|
||||
"hooks": [
|
||||
{
|
||||
"type": "command",
|
||||
"command": "./skills/self-improvement/scripts/activator.sh"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## GitHub Copilot Setup
|
||||
|
||||
Copilot doesn't support hooks directly. Instead, add guidance to `.github/copilot-instructions.md`:
|
||||
|
||||
```markdown
|
||||
## Self-Improvement
|
||||
|
||||
After completing tasks that involved:
|
||||
- Debugging non-obvious issues
|
||||
- Discovering workarounds
|
||||
- Learning project-specific patterns
|
||||
- Resolving unexpected errors
|
||||
|
||||
Consider logging the learning to `.learnings/` using the format from the self-improvement skill.
|
||||
|
||||
For high-value learnings that would benefit other sessions, consider skill extraction.
|
||||
```
|
||||
|
||||
## Verification
|
||||
|
||||
### Test Activator Hook
|
||||
|
||||
1. Enable the hook configuration
|
||||
2. Start a new Claude Code session
|
||||
3. Send any prompt
|
||||
4. Verify you see `<self-improvement-reminder>` in the context
|
||||
|
||||
### Test Error Detector Hook
|
||||
|
||||
1. Enable PostToolUse hook for Bash
|
||||
2. Run a command that fails: `ls /nonexistent/path`
|
||||
3. Verify you see `<error-detected>` reminder
|
||||
|
||||
### Dry Run Extract Script
|
||||
|
||||
```bash
|
||||
./skills/self-improvement/scripts/extract-skill.sh test-skill --dry-run
|
||||
```
|
||||
|
||||
Expected output shows the skill scaffold that would be created.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Hook Not Triggering
|
||||
|
||||
1. **Check script permissions**: `chmod +x scripts/*.sh`
|
||||
2. **Verify path**: Use absolute paths or paths relative to project root
|
||||
3. **Check settings location**: Project vs user-level settings
|
||||
4. **Restart session**: Hooks are loaded at session start
|
||||
|
||||
### Permission Denied
|
||||
|
||||
```bash
|
||||
chmod +x ./skills/self-improvement/scripts/activator.sh
|
||||
chmod +x ./skills/self-improvement/scripts/error-detector.sh
|
||||
chmod +x ./skills/self-improvement/scripts/extract-skill.sh
|
||||
```
|
||||
|
||||
### Script Not Found
|
||||
|
||||
If using relative paths, ensure you're in the correct directory or use absolute paths:
|
||||
|
||||
```json
|
||||
{
|
||||
"command": "/absolute/path/to/skills/self-improvement/scripts/activator.sh"
|
||||
}
|
||||
```
|
||||
|
||||
### Too Much Overhead
|
||||
|
||||
If the activator feels intrusive:
|
||||
|
||||
1. **Use minimal setup**: Only UserPromptSubmit, skip PostToolUse
|
||||
2. **Add matcher filter**: Only trigger for certain prompts:
|
||||
|
||||
```json
|
||||
{
|
||||
"matcher": "fix|debug|error|issue",
|
||||
"hooks": [...]
|
||||
}
|
||||
```
|
||||
|
||||
## Hook Output Budget
|
||||
|
||||
The activator is designed to be lightweight:
|
||||
- **Target**: ~50-100 tokens per activation
|
||||
- **Content**: Structured reminder, not verbose instructions
|
||||
- **Format**: XML tags for easy parsing
|
||||
|
||||
If you need to reduce overhead further, you can edit `activator.sh` to output less text.
|
||||
|
||||
## Security Considerations
|
||||
|
||||
- Hook scripts run with the same permissions as Claude Code
|
||||
- Scripts only output text; they don't modify files or run commands
|
||||
- Error detector reads `CLAUDE_TOOL_OUTPUT` environment variable
|
||||
- All scripts are opt-in (you must configure them explicitly)
|
||||
|
||||
## Disabling Hooks
|
||||
|
||||
To temporarily disable without removing configuration:
|
||||
|
||||
1. **Comment out in settings**:
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
// "UserPromptSubmit": [...]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
2. **Or delete the settings file**: Hooks won't run without configuration
|
||||
Reference in New Issue
Block a user