clawdbot/skills/self-improving-agent/references/clawdbot-integration.md

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:

{
  "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.

# 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.

# 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.

# 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:

### 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

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:

## [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:

## Testing
- Playwright debugging: use `--headed` flag

In ~/clawd/TOOLS.md:

## 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