dawn-cli-agent

Horizon's Dawn Agents

Horizon's Dawn Agents work in parallel to turn feature requests into PRs with velocity and confidence.

Dawn Agents are self-documenting, self-improving, and understand your team's tooling, tribal knowledge, and preferences.

Dawn Agents focus on building systems and procedures that give engineers high confidence in PR quality without manual code review. These systems include robust testing suites, comprehensive success criteria, and human-in-the-loop when clarity is needed.

Quick Start

1. Install

npm install -g dawn-cli-agent

2. Configure environment

Create a .env file in your project root:

# Required
DAYTONA_API_KEY=...
ANTHROPIC_API_KEY=...
GITHUB_TOKEN=...

# Optional
DAWN_CLAUDE_MODEL=claude-opus-4-6     # Model to use
DAWN_MAX_CONCURRENCY=1                # Parallel tasks
DAWN_MERGE_MODE=pr                    # "pr" | "auto" | "direct"
DAWN_POLL_INTERVAL=5000               # Poll interval (ms)
DAWN_MAX_ITERATIONS=Infinity          # Max loop iterations

3. Add tasks

Create a request_queue/ directory and add markdown files — one per task:

---
title: Fix the login bug
description: The login form crashes when email contains a +
repo: https://github.com/your-org/your-repo
status: Needs Oneshot
---

Additional context for the agent goes here in the markdown body.

4. Run

dawn

Dawn picks up every actionable task in request_queue/, spins up isolated Daytona sandboxes, runs Claude, and opens PRs on the target repos.

Task File Reference

Task files live in request_queue/*.md. Each file has YAML frontmatter that drives the pipeline.

Required Fields

Field	Type	Description
title	string	Short task name
description	string	What the agent should do
repo	string	Target GitHub repo URL
status	string	Pipeline entry point (see statuses below)

Optional Fields

Field	Type	Description
id	string	Unique task ID (auto-generated as AGI-N if omitted)
number_of_sandboxes	number	Sandbox instances to create (default 1)
depends_on	string or array	Task ID(s) that must reach Done before this task runs
group	string	Branch naming group (dawn/{group})
variant_hint	string	Execution variant hint ("pty" or "exec")

Generated Fields (written by Dawn at runtime)

Field	Type	Set when
branch_name	string	Sandbox starts
commit_hash	string	Work completes
pr_url	string	PR is created
preview_url	string	Live preview available
last_summary	string	Each stage completes
last_error	string	A stage fails
artifacts	object	Stage produces output ({ "Research": "path" })

Status Values

Starting statuses — set one of these to queue a task:

Status	Pipeline
Needs Research	Full pipeline: Research → Specification → Plan → Implement → Validate → PR
Needs Oneshot	Single-shot: one Claude invocation → PR

You can also enter the full pipeline at any stage: Needs Specification, Needs Plan, Needs Implement, Needs Validate.

Runtime statuses (set automatically by Dawn):

Status	Meaning
* In Progress	Stage currently executing
Done	Task completed
Awaiting Merge	PR created, awaiting merge
Blocked	Stage failed
Needs Human Review	Paused for human review
Needs Human Decision	Paused for human decision

How It Works

Dawn is an automated orchestration agent that takes software tasks from a markdown queue, runs them through a multi-stage AI pipeline in isolated cloud sandboxes, and delivers pull requests.

Architecture

request_queue/*.md            Daytona Sandbox
┌──────────────┐         ┌─────────────────────────┐
│  Task (YAML  │         │  Node.js container       │
│  frontmatter │────────▶│  ├── cloned repo         │
│  + markdown) │         │  ├── claude CLI           │
└──────────────┘         │  └── gh CLI               │
       ▲                 └──────────┬────────────────┘
       │  status update             │  WORK_RESULT
       └────────────────────────────┘

Core Loop

The SandboxQueueProcessor continuously polls for work:

                        ┌─────────────────────┐
                        │  Load all tasks from │
                        │  request_queue/*.md  │
                        └─────────┬───────────┘
                                  ▼
                        ┌─────────────────────┐
                        │  Filter eligible:    │
                        │  • actionable status │
                        │  • not already active│
                        │  • deps all Done     │
                        └─────────┬───────────┘
                                  ▼
                   ┌──────────────────────────────┐
                   │  Dispatch up to maxConcurrency│
                   │  tasks in parallel             │
                   └──────────────┬────────────────┘
                                  ▼
              ┌───────────────────┴───────────────────┐
              ▼                                       ▼
   ┌─────────────────────┐               ┌───────────────────┐
   │   FULL PIPELINE      │               │   ONE-SHOT        │
   │   (status: Needs     │               │   (status: Needs  │
   │    Research)          │               │    Oneshot)       │
   └─────────┬────────────┘               └─────────┬─────────┘
              │                                      │
              ▼                                      │
   Research ──▶ Specification                        │
       ──▶ Plan ──▶ Implement                        │
              ──▶ Validate                           │
              │                                      │
              ▼                                      ▼
   ┌──────────────────────────────────────────────────────────┐
   │  Terminal task + code-producing stage?                    │
   │  YES → inject merge instructions → Claude opens PR       │
   │  NO  → advance status, continue pipeline                 │
   └────────────────────────┬─────────────────────────────────┘
                            ▼
              ┌──────────────────────────┐
              │  Parse WORK_RESULT:      │
              │  • next_status           │
              │  • branch_name           │
              │  • pr_url                │
              │  • preview_url           │
              │  • artifacts             │
              └────────────┬─────────────┘
                           ▼
              ┌──────────────────────────┐
              │  Update task frontmatter │
              │  → loop back to top      │
              └──────────────────────────┘

Pathway: Full Pipeline vs One-Shot

The pathway is determined by the task's initial status: in its YAML frontmatter:

Pathway	Starting Status	Stages	Use Case
Full Pipeline	Needs Research	Research → Specification → Plan → Implement → Validate → PR	Complex features requiring design
One-Shot	Needs Oneshot	Single Claude invocation → PR	Well-defined bug fixes, small changes

Each stage transitions through an In Progress status while executing: Needs X → X In Progress → Needs Y (next stage) or Done / Blocked

A task can also enter Needs Human Review or Needs Human Decision to pause for external input.

Stage Pipeline

Each stage runs Claude with a stage-specific prompt in the same sandbox:

Stage	What Claude Does
Research	Analyzes the repo and requirements
Specification	Designs the UX/interaction model
Plan	Creates a technical implementation plan
Implement	Writes code, runs tests locally
Validate	Verifies quality and test coverage
PR/Merge	Opens a pull request on GitHub

Only Implement, Validate, and Oneshot are code-producing stages — these trigger auto-merge logic on terminal tasks.

Sandbox Lifecycle & Preview URLs

For each dispatched task, a single Daytona sandbox handles all of its stages:

┌─ Sandbox Boot ───────────────────────────────────────────────┐
│  1. Create Daytona sandbox (Node.js + git + gh + claude)     │
│  2. Clone target repo, checkout/create feature branch        │
│  3. Generate signed preview URLs for ports 3000, 5173, 8080  │
│     (valid 72 hours)                                         │
└──────────────────────────────┬────────────────────────────────┘
                               ▼
┌─ Stage Execution (repeats per stage) ────────────────────────┐
│  1. Build prompt with task context + prior stage artifacts    │
│  2. Inject {{PREVIEW_URL}} and {{PREVIEW_URLS}} into prompt  │
│  3. Run Claude via PTY, stream output in real-time           │
│  4. Parse WORK_RESULT block from output                      │
│  5. Resolve localhost URLs → signed Daytona preview URLs     │
│     (e.g. localhost:5173 → https://5173-xxx.proxy.daytona.io)│
└──────────────────────────────┬────────────────────────────────┘
                               ▼
┌─ Cleanup ────────────────────────────────────────────────────┐
│  preview_url in WORK_RESULT?                                 │
│  YES → keep sandbox alive (user deletes from Daytona dash)   │
│  NO  → delete sandbox immediately                            │
└──────────────────────────────────────────────────────────────┘

Preview URLs let reviewers interact with running apps (e.g. a Vite dev server) before merging — the sandbox stays alive so the URL keeps working.

Known Issues

• Daytona sandboxes can get stuck in "spawning" state — Occasionally, sandbox creation fails to complete and hangs indefinitely. Restarting Dawn to rerun the task usually resolves this.