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:

# Requires Python 3.10+ and pip installed

# Navigate to your project and start
cd C:\path\to\your\project
prompter-hawk init
prompter-hawk

# Download from the Downloads page or directly:
# https://github.com/nlowell11/prompter-hawk-downloads/releases/download/v0.2.5/PrompterHawk.dmg

# After downloading:
# 1. Open the .dmg file
# 2. Drag Prompter Hawk to your Applications folder
# 3. Launch from Applications or Spotlight

# Requires Python 3.10+ and pip installed

# Navigate to your project and start
cd /path/to/your/project
prompter-hawk init
prompter-hawk

# Option 1: Claude Max Plan (recommended)
pip install claude-code-sdk
claude login

# Option 2: API keys via environment variables
export ANTHROPIC_API_KEY="your-claude-key"
export OPENAI_API_KEY="your-openai-key"

# Or configure via the web UI Settings panel

# Download the latest .deb package
wget https://github.com/nlowell11/prompter-hawk-downloads/releases/download/v2.1.3-linux/prompter-hawk_2.1.3_amd64.deb

# Install it
sudo dpkg -i prompter-hawk_2.1.3_amd64.deb

# Run Prompter Hawk
PrompterHawk

# Requires Python 3.10+ and pip installed

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

# Run Prompter Hawk
prompter-hawk

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 including mission.json, task_state.json, and agent memory folders.

3. Start Prompter Hawk

   prompter-hawk

   The web dashboard opens at http://localhost:8000 (or next available port 8001-8100 if busy).

4. Add agents and tasks
   Use the dashboard to add agents and create tasks. You can also create tasks from the command line:

   prompter-hawk task @my-agent "implement login feature" -d "Create the auth system"

   Agents automatically pick up pending tasks 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 prompter-hawk task @agent "name" -d "description" (see CLI Commands)
• Team Captain - Automatically creates tentative tasks when enabled
• Agent suggestions - Agents can propose tasks during execution via MCP tools

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

Live Peek

Live Peek lets you see exactly what your agents are thinking and doing in real-time. Watch their reasoning, tool calls, and decisions as they work.

What You Can See

• Agent Reasoning - The AI's internal thought process as it works through tasks
• Tool Calls - Every file read, write, and command executed
• Model Info - Which AI model is being used for each response
• Message History - Full conversation between you and the agent

Using Live Peek

1. Click on any running agent in the dashboard
2. The agent panel expands to show real-time activity
3. Tool calls stream live as the agent works
4. Click on any task to see its full message history

Task Message History

For any task (including completed ones), you can view:

• Full conversation - All messages exchanged during execution
• Tool call details - Expandable sections showing what tools were called
• Prompt sections - Collapsible system prompts and context
• Model information - Which model handled each response

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-4o for code generation (best balance of quality and speed)
• claude-sonnet-4 for code review (superior analysis and reasoning)
• gpt-4o-mini for documentation and tests (fast and cost-effective)
• gemini-2.5-flash for high-volume, low-cost tasks

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 (default)
• Apollo Theme - Warm, amber-toned dark mode
• Solarized Apollo - Light mode with warm tones

Themes apply consistently across all UI elements including dialogs, folder pickers, and mission creation screens.

Animation Effects

The dashboard includes optional visual effects:

• Matrix particles - Ambient background animation
• Perlin noise effects - Smooth, organic background patterns
• Border effects - Animated borders on active elements

Toggle animations in Settings if you prefer a more minimal interface or need better performance.

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 or via the dashboard UI:

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

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-4o" }
    },
    {
      "id": "frontend-dev",
      "role": "Frontend Developer - Focus on React components, styling, UX",
      "backend": { "provider": "anthropic", "model": "claude-sonnet-4-20250514" }
    },
    {
      "id": "qa-tester",
      "role": "QA Engineer - Write tests, find bugs, ensure quality",
      "backend": { "provider": "openai", "model": "gpt-4o-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-20250514" }
    },
    {
      "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-20250514" }
    },
    {
      "id": "code-analyst",
      "role": "Code analyst - Read codebase, extract patterns, create examples",
      "backend": { "provider": "openai", "model": "gpt-4o-mini" }
    }
  ]
}

CLI Commands

After installing via the DMG (macOS) or .deb package (Linux), you get the global prompter-hawk command.

Quick Commands (Recommended)

These commands auto-detect your mission from the current directory:

# Start mission in current directory
prompter-hawk

# Initialize new mission
prompter-hawk init

# Show mission status summary
prompter-hawk status

# Get help
prompter-hawk help

Task Management

Create and manage tasks from the command line:

# Create task assigned to specific agent
prompter-hawk task @frontend-dev "fix button alignment"

# Create task with description and priority
prompter-hawk task @qa-tester "test login flow" -d "Verify all auth paths work" -p high

# Create unassigned task (auto-assigned when agent available)
prompter-hawk task "update docs" -d "Add API reference" -c documentation

# List all tasks
prompter-hawk tasks

# List tasks by status
prompter-hawk tasks pending
prompter-hawk tasks completed

# List tasks by agent
prompter-hawk tasks @frontend-dev

Task Options

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 has a free tier for getting started, plus a paid plan at $24/month for unlimited agents and missions. You also 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 the Linux .deb package or macOS DMG, download and install the latest version from our Downloads page. The new version will replace the old one.

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.