thoughtwave

AI agent orchestration framework using the Claude Agent SDK. You are the CEO - your Chief of Staff coordinates specialized agents to execute your vision and get things done.

Installation

npm install thoughtwave

Overview

Instead of working with a single AI assistant, Thoughtwave gives you a coordinated team of specialists, each optimized for specific tasks. The team composition is fully configurable—you define the specialists that make sense for your workflow.

How It Works

1. You (the CEO) set direction via CLI (e.g., "Review the auth module and fix any issues")
2. Chief of Staff analyzes your request and breaks it into tasks
3. Chief of Staff directs appropriate specialists to execute
4. Specialists execute their assigned tasks independently
5. Chief of Staff synthesizes results and reports back to you

Usage

npx thoughtwave                        # Start in read-only mode
npx thoughtwave --allow-writes         # Enable file modifications
npx thoughtwave --config my-team.json  # Load custom team configuration
npx thoughtwave --log-dir ./my-logs    # Custom log directory

CLI Options

| Option | Description | | ------------------ | ------------------------------------------------------------------------------------ | | --config <path> | Path to team configuration JSON file | | --allow-writes | Enable write operations (Edit, Write, Bash). Without this flag, agents are read-only | | --log-dir <path> | Directory for session logs (defaults to ./logs) | | --print, -p | Process a single prompt and exit (non-interactive mode) |

Team Configuration

Thoughtwave is a generic orchestration framework—the team members are entirely up to you. Define specialists that match your needs: security auditors, test writers, documentation authors, data analysts, or any other role.

Teams are defined in a JSON file with the following structure:

{
  "members": [
    {
      "name": "code-reviewer",
      "description": "Expert code reviewer who analyzes code for bugs and best practices",
      "systemPrompt": "You are an expert code reviewer...",
      "tools": ["Read", "Glob", "Grep"],
      "model": "haiku"
    },
    {
      "name": "implementer",
      "description": "Senior developer who implements features and fixes",
      "systemPrompt": "You are a senior developer...",
      "tools": ["Read", "Write", "Edit", "Bash", "Glob", "Grep"],
      "model": "sonnet"
    }
  ]
}

Member Properties

| Property | Description | | -------------- | ----------------------------------------------------------------------------------------- | | name | Identifier used for delegation | | description | What the agent specializes in (shown to the Chief of Staff) | | systemPrompt | Instructions for the agent's behavior | | tools | Available tools: Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch | | model | Claude model: haiku (fast/cheap), sonnet (balanced), opus (powerful), or inherit |

Example Teams

Code Review Team:

{
  "members": [
    { "name": "reviewer", "description": "Code reviewer", "tools": ["Read", "Glob", "Grep"], "model": "haiku" },
    { "name": "implementer", "description": "Developer", "tools": ["Read", "Write", "Edit", "Bash"], "model": "sonnet" }
  ]
}

Security Audit Team:

{
  "members": [
    {
      "name": "security-auditor",
      "description": "Security specialist",
      "tools": ["Read", "Glob", "Grep"],
      "model": "sonnet"
    },
    {
      "name": "researcher",
      "description": "Vulnerability researcher",
      "tools": ["Read", "WebSearch", "WebFetch"],
      "model": "haiku"
    }
  ]
}

Features

• Configurable teams - Define any team structure via JSON
• Safety modes - Read-only by default; opt-in to writes
• Session logging - All interactions logged to JSONL for audit/debugging
• Conversation continuity - Sessions persist for multi-turn workflows
• Visual feedback - Clear CLI output showing which agent is working

Use Cases

• Code reviews across large codebases
• Research + implement workflows (researcher gathers info, implementer acts)
• Complex refactoring where planning, review, and implementation benefit from separation
• Security audits with specialized scanning and remediation agents
• Documentation with research and writing specialists

Programmatic Usage

import { runThoughtwave } from 'thoughtwave'

await thoughtwave({
  configPath: './my-team.json',
  logDir: './logs',
  allowWrites: true,
})

License

MIT