Getting Started with Prompter Hawk

1. Installation

Prompter Hawk is a desktop application that runs locally on your machine. Choose your platform below to get started with the v0.4.0 release.

macOS Installation (.dmg)

Download the DMG package
Get the latest release from the Downloads page or directly:

https://github.com/nlowell11/prompter-hawk-downloads/releases/download/v0.4.0/PrompterHawk.dmg
Install the application
Open the .dmg file and drag Prompter Hawk to your Applications folder.
Launch Prompter Hawk
Open from Applications or use Spotlight (Cmd+Space, type "Prompter Hawk").

The DMG package is self-contained (about 87 MB) and includes everything you need. No Python installation required.

Linux / WSL Installation (.deb)

Download the .deb package
wget https://github.com/nlowell11/prompter-hawk-downloads/releases/download/v0.4.0/prompter-hawk_0.4.0_amd64.deb
Install with dpkg
sudo dpkg -i prompter-hawk_0.4.0_amd64.deb
Run Prompter Hawk
PrompterHawk

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

WSL users: The Linux binary works great in WSL2. Access the dashboard from your Windows browser at http://localhost:8000.

Configure Your AI Backend

After installation, you'll need to connect at least one AI provider. Prompter Hawk supports Claude (Anthropic), OpenAI, and Google Gemini.

                    # Set your API key as an environment variable
export ANTHROPIC_API_KEY="your-claude-key"

# Or configure via the dashboard Settings panel
                

See the API Key Setup section in the full documentation for detailed instructions.

2. Your First Mission

A "mission" in Prompter Hawk is a project workspace where your AI agents collaborate. All agents share the same filesystem - no branch merging required.

Navigate to your project directory
cd /path/to/your/project
Initialize a new mission
prompter-hawk init

This creates a .prompter-hawk/ directory with your mission configuration, including mission.json and tasks.db for task tracking.
Start Prompter Hawk
prompter-hawk

The web dashboard opens automatically. If port 8000 is busy, it tries 8001-8100.

Run prompter-hawk help to see all available CLI commands.

3. Adding Agents

Agents are AI-powered workers that execute tasks. Each agent can use a different AI provider and maintains persistent memory between sessions.

From the Dashboard

Click "Add Agent" in the header to create a new agent. You can:

Give it a descriptive name (e.g., backend-dev, test-engineer)
Choose which AI backend to use (Claude, OpenAI, or Gemini)
Set a custom system prompt to specialize its behavior

Agent Capabilities

Persistent Memory

Each agent maintains a progress_log.md that persists between sessions.

Auto-Restart

Agents automatically restart on failure with full context preserved.

Multi-Provider

Mix Claude, OpenAI, and Gemini agents in the same mission.

Task Creation

Agents can propose new tasks via MCP tools (shown as "tentative" for approval).

4. Running Tasks

Tasks are units of work assigned to agents. Prompter Hawk tracks status (pending, in-progress, completed, failed, blocked) and handles dependencies automatically.

Creating Tasks from CLI

                    # Assign to a specific agent
prompter-hawk task @backend-dev "implement login endpoint"

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

# Unassigned (auto-assigned when agent available)
prompter-hawk task "update docs" -c documentation
                

Creating Tasks from Dashboard

Click "Add Task" in the Task Bank view. Set the name, description, priority, and optionally assign to a specific agent or mark prerequisites.

Task Features

Prerequisites - Tasks can depend on other tasks. Blocked tasks wait automatically.
Priority levels - Critical, High, Medium, Low.
Categories - Feature, Bugfix, or Documentation (affects validation).
One-click retry - Failed tasks can be retried with full context preserved.
Recurring tasks - Schedule tasks to run hourly, daily, weekly, or on custom intervals.

Watching Progress

Once agents are started, they automatically pick up pending tasks and work in parallel. The dashboard shows real-time status:

Agents Panel - See which agents are idle, working, or stopped.
Task Bank - Track pending, in-progress, completed, and blocked tasks.
Analytics Tab - Monitor token usage, code changes, and task completions.
Timeline View - Gantt chart showing task execution over time.

5. What's Next

Now that you have the basics, explore these features:

Team Captain - Enable autonomous task creation when agents go idle.
Human Feedback System - Queue up testing requests from agents.
Multi-Provider Strategies - Optimize cost by mixing AI backends.
Copy-Paste Task Examples - Ready-to-use task templates.
Running Parallel Agents Guide - Deep dive into parallel orchestration.

Start small: Begin with 2-3 agents and gradually increase as you learn how to coordinate them effectively.