Prompter Hawk Documentation

Prompter Hawk is mission control for AI coding agents. Orchestrate multiple AI agents (Claude, OpenAI, Gemini) working in parallel on your codebase with automated task management, context sharing, and real-time monitoring.

Installation

Choose your platform to get started with Prompter Hawk:

# Clone the repository
git clone https://github.com/your-org/claude-orchestrator.git
cd claude-orchestrator

# Install globally
pip install -e .

# Run from any directory
prompter-hawk

# Clone the repository
git clone https://github.com/your-org/claude-orchestrator.git
cd claude-orchestrator

# Install dependencies
pip install -r config/requirements.txt

# Install globally
pip install -e .

# Set up API keys (see API Key Setup section)
export ANTHROPIC_API_KEY="your-key-here"

# Run Prompter Hawk
prompter-hawk

# Download the .deb package from Downloads page
sudo dpkg -i prompter-hawk_1.0.0_amd64.deb

# Install missing dependencies if needed
sudo apt-get install -f

Your First Mission

A "mission" in Prompter Hawk is a project with agents, tasks, and shared context. Here's how to create your first one:

1. Navigate to your project directory

   cd /path/to/your/project

2. Initialize a new mission

   prompter-hawk init

   This creates a .prompter-hawk/ directory with mission configuration.

3. Start Prompter Hawk

   prompter-hawk

   The web dashboard opens at http://localhost:8000

4. Add agents and tasks
   Use the dashboard to add agents and create tasks. Agents automatically pick up work when started.

Dashboard Overview

The Prompter Hawk dashboard is your mission control center. It provides real-time visibility into all agents, tasks, and progress.

Header controls: Mission name, connection status, Start/Stop All, Add Agent, Theme toggles, Team Captain, and Settings

The main dashboard showing token usage, progress tracking, and activity metrics

Key Dashboard Areas

Managing Agents

Agents are AI-powered workers that execute tasks. Each agent can use a different AI provider and has its own memory and context.

Individual agent panel showing status, controls, and memory files

Agent Status States

• Idle - Agent is ready but not currently working on a task
• Busy - Agent is actively executing a task
• Monitoring - Agent is waiting for human feedback
• Stopped - Agent service is not running

Agent Controls

Agent Memory Files

Each agent maintains persistent memory in its progress_log.md file. This includes:

• Task completion history
• Learnings from successes and failures
• Blockers and how they were resolved
• Cross-session context that persists between restarts

Task Management

Tasks are units of work assigned to agents. Prompter Hawk provides a sophisticated task management system with dependencies, priorities, and automatic retry.

The Task Bank showing different task categories and filtering options

Task Categories

Creating Tasks

Tasks can be created through:

• Dashboard UI - Click "Add Task" in the Task Bank
• CLI - Use python development/maintenance/add_task.py
• Team Captain - Automatically creates tasks when enabled
• Agent suggestions - Agents can propose tasks during execution

Task Properties

• Name - Short, descriptive title
• Description - Detailed instructions for the agent
• Priority - Critical, High, Medium, Low
• Assigned To - Specific agent or "any" for auto-assignment
• Prerequisites - Tasks that must complete first
• Human Feedback Required - Whether to request validation

Progress Tracking

Prompter Hawk provides detailed metrics on development progress, including code changes, commits, and task completion rates.

Progress metrics showing code changes, git activity, and task completions

Tracked Metrics

Parallel Execution

One of Prompter Hawk's core features is the ability to run multiple AI agents simultaneously, dramatically accelerating development.

How It Works

1. Shared workspace - All agents work in the same project directory
2. No branch merges - Agents commit directly to the main branch
3. Automatic coordination - Task dependencies prevent conflicts
4. Real-time monitoring - See all agents' progress in one dashboard

Best Practices for Parallel Work

• Divide by domain - Assign frontend, backend, tests to different agents
• Use task dependencies - Mark tasks that must complete before others can start
• Specialize agents - Give agents focused roles with clear boundaries
• Monitor conflicts - Watch for agents modifying the same files

Team Captain

The Team Captain is a special agent that monitors your mission and automatically creates and assigns tasks to keep your squad productive.

What Team Captain Does

• Monitors idle agents - Detects when agents have no work
• Creates tentative tasks - Suggests tasks based on project needs
• Assigns work - Distributes tasks to appropriate agents
• Maintains flow - Keeps the mission moving forward

Enabling Team Captain

Toggle Team Captain on/off using the button in the dashboard header. When enabled, a captain agent is added to your mission.

Human Feedback System

Agents can request human testing and validation during task execution. This creates a quality gate without interrupting your flow.

How It Works

1. Agent completes work and requests feedback
2. Request appears in "Feedback Requests" queue
3. You test at your convenience
4. Provide structured feedback
5. Agent receives response and continues

Feedback Request Properties

• Test Description - What the agent wants you to test
• Game Script - Command to run for testing
• Question - Specific question for feedback
• Response Options - Predefined answers to choose from
• Instructions - How to perform the test

Multi-Provider Support

Prompter Hawk supports multiple AI providers, allowing you to use the best model for each task and optimize costs.

Supported Providers

Mixed Backend Strategy

Mix providers in a single mission for optimal results:

• GPT-4.1 for code generation (optimized for code diffs)
• Claude Sonnet 4 for code review (superior analysis)
• GPT-5-mini for documentation and tests (90% cheaper)

Settings

Prompter Hawk settings are accessible via the gear icon in the dashboard header.

The Settings menu with visual and feature configuration options

Available Settings

Theme Options

Switch between visual themes using the theme buttons in the header:

• Umbra Theme - Dark mode with cyan accents
• Solarized Apollo - Light mode with warm tones

API Key Setup

Prompter Hawk requires API keys to communicate with AI providers. Here's how to configure them securely.

The API Key Configuration dialog showing environment variable detection

Setting Up API Keys

1. Get your API key from the provider
   • Claude: console.anthropic.com/settings/keys
   • OpenAI: platform.openai.com/api-keys
   • Gemini: aistudio.google.com/app/apikey
2. Open Prompter Hawk Settings
   Click the gear icon and navigate to backend configuration.
3. Configure your key
   Either paste your key directly, or grant consent to use an environment variable.

The Consent System

Prompter Hawk respects your privacy. When it detects an API key in your environment variables:

• It asks for your explicit consent before using it
• Your consent choice is remembered permanently
• Keys are only sent to their respective providers
• You can revoke consent anytime from Settings

Storage Locations

• API keys: ~/.prompter-hawk/api_keys.json
• Consent records: ~/.prompter-hawk/api_consent.json

Backend Providers

Configure which AI provider each agent uses. You can mix and match for optimal cost and performance.

Installing Backends

# Claude (requires Claude Max subscription OR API key)
pip install claude-code-sdk    # For Claude Max
pip install anthropic          # For API access

# OpenAI
pip install openai

# Gemini
pip install google-genai

Per-Agent Backend Configuration

Each agent can use a different backend. Configure in your mission JSON:

{
  "agents": [
    {
      "id": "coder",
      "role": "Python Developer",
      "backend": {
        "provider": "openai",
        "model": "gpt-4.1",
        "budget_limits": {
          "hourly_budget_usd": 2.0,
          "daily_budget_usd": 10.0
        }
      }
    },
    {
      "id": "reviewer",
      "role": "Code Reviewer",
      "backend": {
        "provider": "anthropic",
        "model": "claude-sonnet-4"
      }
    }
  ]
}

Budget Limits

Prevent runaway costs by setting budget limits per agent:

• hourly_budget_usd - Maximum spend per hour
• daily_budget_usd - Maximum spend per day
• monthly_budget_usd - Maximum spend per month

Tasks automatically fail when budget is exceeded.

Copy-Paste Task Examples

Here are ready-to-use task examples. Copy the description directly into the "Add Task" dialog.

Mission Templates

Use these templates as starting points for common project types.

Web Application (3 Agents)

{
  "mission_name": "my-web-app",
  "agents": [
    {
      "id": "backend-dev",
      "role": "Backend Developer - Focus on API endpoints, database, authentication",
      "backend": { "provider": "openai", "model": "gpt-4.1" }
    },
    {
      "id": "frontend-dev",
      "role": "Frontend Developer - Focus on React components, styling, UX",
      "backend": { "provider": "anthropic", "model": "claude-sonnet-4" }
    },
    {
      "id": "qa-tester",
      "role": "QA Engineer - Write tests, find bugs, ensure quality",
      "backend": { "provider": "openai", "model": "gpt-5-mini" }
    }
  ]
}

Solo Developer (2 Agents)

{
  "mission_name": "solo-project",
  "agents": [
    {
      "id": "developer",
      "role": "Full-stack developer - Implement features across the stack",
      "backend": { "provider": "anthropic", "model": "claude-sonnet-4" }
    },
    {
      "id": "reviewer",
      "role": "Code reviewer - Review changes, suggest improvements, catch bugs",
      "backend": { "provider": "openai", "model": "gpt-4o" }
    }
  ]
}

Documentation Team (2 Agents)

{
  "mission_name": "docs-project",
  "agents": [
    {
      "id": "tech-writer",
      "role": "Technical writer - Create user guides, API docs, tutorials",
      "backend": { "provider": "anthropic", "model": "claude-sonnet-4" }
    },
    {
      "id": "code-analyst",
      "role": "Code analyst - Read codebase, extract patterns, create examples",
      "backend": { "provider": "openai", "model": "gpt-5-mini" }
    }
  ]
}

CLI Commands

Global Command

# Start mission in current directory
prompter-hawk

# Initialize new mission
prompter-hawk init

# Get help
prompter-hawk --help

Mission Control

# Run a specific mission
python mission_control.py run <mission-name>

# List all missions
python mission_control.py list

# Create new mission
python mission_control.py init

# Clean temporary files
python mission_control.py clean soft

# Reset everything
python mission_control.py clean hard

Task Management

# Add a task
python development/maintenance/add_task.py --mission <name> add "Task name" "Description"

# Show current tasks
python development/maintenance/add_task.py --mission <name> show

# List agents
python development/maintenance/add_task.py --mission <name> list-agents

# List all missions
python development/maintenance/add_task.py list-missions

Troubleshooting

Common Issues

Getting Help

• Check the runtime/logs/ directory for detailed error logs
• Review .prompter-hawk/task_state.json for task status
• Enable debug mode: export DEBUG_SERVICES=true

Frequently Asked Questions

Do I need all three AI providers?

No! You only need at least one. Most users start with just Claude or OpenAI and add more as needed.

How much does it cost to use?

Prompter Hawk itself is free during beta. You pay for AI provider usage (Claude, OpenAI, etc.) based on their pricing. Use budget limits to control costs.

Can agents modify any file?

Agents are configured with boundaries and territories. By default, they can only modify files within your mission workspace. System files are protected.

What happens if an agent makes a mistake?

Use git to revert changes. Agents commit frequently with descriptive messages, making it easy to undo specific changes. The one-click retry feature lets you re-run tasks with context preserved.

Can I use Prompter Hawk offline?

No, all AI backends require internet connectivity. Future versions may support local models.

How do I upgrade?

For pip installations: pip install --upgrade prompter-hawk. For installers, download the latest version from the Downloads page.

Is my code sent to AI providers?

Yes, the code context needed for tasks is sent to whichever AI provider each agent uses. Review each provider's data handling policies.