clawd

Clawd

Clawd is an intelligent orchestrator for the Claude Code CLI that transforms complex development tasks into automated, multi-phase project execution. It generates comprehensive project plans and executes them step-by-step, tracking progress and adapting along the way.

Why Clawd?

If you're a Claude Pro subscriber using Claude Code, you've likely encountered these limitations:

• 💸 Claude API Not Included - The Claude API requires separate payment and usage-based billing, even with a Pro subscription. Clawd leverages your existing Claude Pro subscription through Claude Code, so you're not paying twice.

• ⏹️ Claude Code Eventually Stops - Claude Code has context limits and will pause execution, requiring you to manually reprompt it to continue. This interrupts your flow and requires constant supervision.

• 📝 Incomplete Task Execution - Claude Code often completes part of a task but doesn't see it through to the end. You give it a complex request, it makes progress, then stops before finishing—leaving you to figure out what's left and reprompt.

• 🚀 Why Not Automate It? - Clawd solves all of this by automatically breaking down your project into phases, executing each step, tracking completion, and reprompting as needed—all without your intervention. Set it and forget it (or watch it work in interactive mode).

In short: Clawd lets you use your Claude Pro subscription to build entire projects autonomously, without hitting API limits, manually reprompting, or babysitting incomplete executions.

Features

• 🎯 Intelligent Planning - Automatically breaks down complex prompts into structured, multi-phase project plans
• 🔄 Iterative Execution - Spawns Claude Code instances to execute each task sequentially
• 📊 Progress Tracking - Real-time updates to plan files with checkboxes showing completion status
• ♾️ Perpetual Mode - Continuously researches and adds new features when projects complete
• 🖥️ Interactive TUI - Full terminal interface with scrollable logs, keyboard controls, and live prompting
• ✅ Smart Evaluation - Automatically evaluates progress and determines when tasks are complete
• 🔌 Plugin System - Extend Clawd with custom hooks and behaviors
• 📝 Configurable Prompts - Override any prompt template to customize Claude's behavior

Prerequisites

• Node.js (v18 or higher with ESM support)
• Claude Code CLI - Must be installed and available in your PATH (installation guide)

⚠️ IMPORTANT: Clawd requires Claude Code to run with the dangerously-skip-permissions flag enabled. This allows Clawd to execute commands without manual approval prompts. Use at your own risk - only run Clawd in trusted environments and review the generated project plans before execution.

Installation

npm install -g clawd

Quick Start

The simplest way to use Clawd is to run it without any arguments:

clawd

This starts interactive mode where you'll be prompted for what you want to build. Alternatively, provide your project description directly:

clawd "Build a REST API with Express and PostgreSQL"

Clawd will:

• Generate a PROJECT_PLAN.md with phases and tasks
• Execute each task using Claude Code
• Evaluate task completion
• Track progress with checkboxes
• Continue until complete

Architecture

Clawd follows a Plan → Exec → Eval → Complete workflow:

• Plan - Initialize or load project plan, parse into tasks
• Exec - Execute each task with Claude Code
• Eval - Evaluate if task was completed successfully
• Complete - When all tasks are done, evaluate if project is truly complete

Each step is hookable via the plugin system, allowing you to customize Clawd's behavior.

Core Concepts

Project Plans

Plans are stored in PROJECT_PLAN.md:

# Project Brief
[Description of what needs to be built]

# Goal
[Clear end goal statement]

# Phases

## Phase 1: Setup
- [ ] Initialize project structure
- [ ] Install dependencies
- [ ] Configure environment

## Phase 2: Implementation
- [ ] Create database schema
- [ ] Build API endpoints
- [ ] Implement business logic

As tasks complete, checkboxes are automatically marked: - [x] Completed task

Plugins

Create plugins in .clawd/plugins/ to hook into Clawd's lifecycle:

// .clawd/plugins/my-plugin.js
export default {
  name: 'my-plugin',
  hooks: {
    'post:exec': async (context) => {
      // Run after each task execution
      console.log(`Task completed: ${context.task.description}`)
      return context
    }
  }
}

Available hooks:

• pre:plan / post:plan - Before/after plan initialization
• pre:exec / post:exec - Before/after task execution
• pre:eval / post:eval - Before/after task evaluation
• pre:complete / post:complete - Before/after project completion check

Configurable Prompts

Override any prompt by creating .clawd/prompts/<name>.md:

# Copy a prompt to customize it
clawd prompts copy plan-init

# Edit .clawd/prompts/plan-init.md
# Your changes will be used instead of the built-in prompt

CLI Reference

Main Command

clawd [prompt] [options]

Arguments:

• [prompt] - Project description (optional - you will be prompted if omitted)

Options:

• -p, --perpetual - Enable perpetual mode (continuously add features)
• --non-interactive - Disable terminal UI, use standard output

Examples:

clawd                                    # Interactive mode with prompt
clawd "Build a task manager"             # Direct prompt
clawd --non-interactive "Build an API"   # Non-interactive mode
clawd -p "Build a blog"                  # Perpetual mode

Prompts Management

# List all available prompts
clawd prompts list

# Copy a specific prompt for editing
clawd prompts copy plan-init

# Copy all prompts
clawd prompts copy --all

Plugin Management

# List loaded plugins and their hooks
clawd plugins list

# Create a new plugin from template
clawd plugins create my-plugin

Project Initialization

# Initialize .clawd/ directory structure
clawd init

This creates:

• .clawd/prompts/ - For custom prompt overrides
• .clawd/plugins/ - For custom plugins

Plugin Examples

Git Plugin

Automatically commit after each successful task:

// .clawd/plugins/git.js
import { exec } from 'child_process'
import { promisify } from 'util'

const execAsync = promisify(exec)

export default {
  name: 'git',
  hooks: {
    'post:exec': async (context) => {
      if (context.exitCode === 0) {
        try {
          await execAsync('git add -A')
          await execAsync(`git commit -m "feat: ${context.task.description}"`)
          console.log('✓ Changes committed')
        } catch (error) {
          console.log('No changes to commit')
        }
      }
      return context
    }
  }
}

Notification Plugin

Send notifications when tasks complete:

// .clawd/plugins/notifications.js
import notifier from 'node-notifier'

export default {
  name: 'notifications',
  hooks: {
    'post:eval': async (context) => {
      if (context.result.complete) {
        notifier.notify({
          title: 'Clawd',
          message: `Task completed: ${context.task.description}`
        })
      }
      return context
    },
    'post:complete': async (context) => {
      if (context.isComplete) {
        notifier.notify({
          title: 'Clawd',
          message: '🎉 Project Complete!'
        })
      }
      return context
    }
  }
}

Logging Plugin

Enhanced logging with timestamps:

// .clawd/plugins/detailed-logging.js
import fs from 'fs/promises'

export default {
  name: 'detailed-logging',
  hooks: {
    'post:exec': async (context) => {
      const log = {
        timestamp: new Date().toISOString(),
        task: context.task.description,
        exitCode: context.exitCode,
        output: context.output
      }

      await fs.appendFile(
        'clawd-detailed.log',
        JSON.stringify(log) + '\n'
      )

      return context
    }
  }
}

Perpetual Mode

Enable continuous development that never stops:

clawd --perpetual "Build a web scraper"

How it works:

• When the initial plan completes, Claude evaluates the entire project
• If more work is needed, Claude adds new phases/tasks to the plan
• Execution continues indefinitely with expanded scope
• Stop anytime with Ctrl+C

Interactive TUI Features

TUI Features:

• Scrollable log area showing all output
• Status bar with current phase and keyboard shortcuts
• Loading indicators for long operations
• Auto-detection of existing PROJECT_PLAN.md

Keyboard Commands:

• p - Queue a prompt for the next iteration
• SPACE - Pause execution (shows menu: continue/prompt/quit)
• ESC - Cancel current task (requires confirmation)
• ? or h - Show help
• q - Quit
• Ctrl+C - Exit immediately
• Mouse wheel or arrow keys - Scroll through logs

Logs

Clawd maintains detailed logs:

• Console/TUI - Real-time colored output showing current progress
• clawd.log - Detailed execution log of all operations
• clawd-error.log - Error-specific logging for troubleshooting

File Structure

clawd/
├── src/
│   ├── core/              # Core modules (plan, exec, eval, complete)
│   ├── plugin-system/     # Plugin loader and hook manager
│   ├── index.js           # CLI entry point
│   ├── prompt-loader.js   # Prompt template system
│   ├── logger.js          # Logging system
│   └── tui.js             # Terminal UI
├── prompts/               # Built-in prompt templates
├── templates/             # Plugin template
└── .clawd/                # User customizations (created in projects)
    ├── prompts/           # User prompt overrides
    └── plugins/           # User plugins

Development & Contributing

Setup for Development

git clone <repository-url>
cd clawd
npm install
npm link

Testing

npm test

Commit Messages

This project uses Conventional Commits:

git commit -m "feat: add new feature"
git commit -m "fix: resolve bug"
git commit -m "docs: update README"

Advanced Patterns

Custom LLM Adapters

Clawd uses an adapter pattern to support any LLM provider. By default, it uses the Claude Code CLI, but you can easily swap in a different LLM.

Creating a Custom Adapter

Create a file at .clawd/adapter.js in your project:

import { LLMAdapter } from "../node_modules/clawd/src/adapters/base.js";

export default class MyLLMAdapter extends LLMAdapter {
  async execute(prompt, captureOutput = true) {
    // Call your LLM API and return the response
    const response = await fetch('https://api.your-llm.com/v1/chat', {
      method: 'POST',
      headers: { 'Authorization': `Bearer ${process.env.API_KEY}` },
      body: JSON.stringify({ prompt })
    });
    return await response.text();
  }

  async executeWithTUI(prompt, tui) {
    const output = await this.execute(prompt);
    if (tui) tui.writeOutput(output);
    return { exitCode: 0, output };
  }

  getName() {
    return "My Custom LLM";
  }
}

Adapter Examples

OpenAI GPT-4:

export default class OpenAIAdapter extends LLMAdapter {
  async execute(prompt) {
    const response = await fetch('https://api.openai.com/v1/chat/completions', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.OPENAI_API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        model: 'gpt-4',
        messages: [{ role: 'user', content: prompt }]
      })
    });
    const data = await response.json();
    return data.choices[0].message.content;
  }
}

Local Ollama:

export default class OllamaAdapter extends LLMAdapter {
  async execute(prompt) {
    const response = await fetch('http://localhost:11434/api/generate', {
      method: 'POST',
      body: JSON.stringify({
        model: 'codellama',
        prompt: prompt,
        stream: false
      })
    });
    const data = await response.json();
    return data.response;
  }
}

Using runPrompt() in Plugins

All plugin hooks receive a runPrompt() function in their context, allowing plugins to execute additional LLM queries:

export default {
  name: 'my-plugin',
  hooks: {
    'post:eval': async (context) => {
      if (!context.result.complete) {
        // Use the current LLM adapter to get suggestions
        const suggestion = await context.runPrompt(
          `Suggest a fix for: ${context.result.feedback}`
        );
        context.logger.info(`Suggestion: ${suggestion}`);
      }
      return context;
    }
  }
}

Advanced Plugin Patterns

Self-Healing Plugin - Automatically attempts to fix failed tasks:

export default {
  name: 'self-healing',
  hooks: {
    'post:eval': async (context) => {
      if (!context.result.complete && context.task.retryCount < 3) {
        context.logger.info('[self-healing] Analyzing failure...');

        const analysis = await context.runPrompt(`
          A task failed with this feedback: "${context.result.feedback}"

          Analyze the issue and provide a specific action plan to fix it.
          Be concise and actionable.
        `);

        context.logger.info(`[self-healing] Analysis: ${analysis}`);

        // Store retry count on task
        context.task.retryCount = (context.task.retryCount || 0) + 1;
      }
      return context;
    }
  }
}

Code Review Plugin - Reviews code after each task:

import { exec } from 'child_process';
import { promisify } from 'util';

const execAsync = promisify(exec);

export default {
  name: 'code-reviewer',
  hooks: {
    'post:exec': async (context) => {
      if (context.exitCode === 0) {
        // Get git diff of changes
        const { stdout } = await execAsync('git diff HEAD');

        if (stdout) {
          const review = await context.runPrompt(`
            Review this code change for quality and potential issues:

            ${stdout}

            Provide a brief review focusing on:
            - Code quality
            - Potential bugs
            - Best practices
          `);

          context.logger.info(`[code-review] ${review}`);
        }
      }
      return context;
    }
  }
}

Adaptive Planning Plugin - Adjusts plan based on progress:

export default {
  name: 'adaptive-planner',
  hooks: {
    'post:complete': async (context) => {
      if (!context.isComplete) {
        // Ask LLM to suggest plan improvements
        const suggestion = await context.runPrompt(`
          Project: ${context.projectBrief}
          Goal: ${context.goal}

          The project evaluation shows it's incomplete.
          Current plan has ${context.plan.tasks.length} tasks.

          Suggest 2-3 additional tasks that would help complete the project.
          Format as a numbered list.
        `);

        context.logger.info(`[adaptive-planner] Suggestions: ${suggestion}`);
      }
      return context;
    }
  }
}

Context-Aware Prompt Modifier - Modifies prompts before execution:

export default {
  name: 'context-enhancer',
  hooks: {
    'pre:exec': async (context) => {
      // Add project-specific context to every prompt
      const projectContext = `
        IMPORTANT: This project uses TypeScript with strict mode.
        Always include type annotations and handle errors properly.
      `;

      context.prompt = projectContext + '\n\n' + context.prompt;

      context.logger.debug('[context-enhancer] Enhanced prompt with project context');
      return context;
    }
  }
}

Configurable Prompts

Override any built-in prompt by creating matching files in .clawd/prompts/:

# Copy a prompt to customize it
clawd prompts copy plan-init

# Edit .clawd/prompts/plan-init.md
# Add your custom instructions, examples, or constraints

Example custom prompt (.clawd/prompts/plan-init.md):

Create a project plan for: {{userPrompt}}

IMPORTANT CONSTRAINTS:
- Use Python 3.11+
- Follow PEP 8 style guide
- Include comprehensive docstrings
- Add type hints to all functions
- Use pytest for all tests

Format the plan as follows:
# Project Brief
[Description]

# Goal
[End goal]

# Phases
## Phase 1: [Name]
- [ ] Task 1
- [ ] Task 2

Troubleshooting

Claude Code not found

Ensure Claude Code CLI is installed and in your PATH:

which claude

If not found, install from: https://docs.claude.com/en/docs/claude-code

Rate limiting

Clawd automatically handles rate limits by waiting and retrying. You'll see wait time estimates in the output.

Plugins not loading

Ensure your plugin exports a default object with name and hooks:

export default {
  name: 'my-plugin',
  hooks: {
    // Your hooks here
  }
}

Check clawd.log for plugin loading errors.

License

MIT