Hatch - Cloud Development CLI

Hatch provisions exe.dev VMs with GitHub, Vercel, and Convex integration.

Hatch is installed at

~/.hatch-cli

pnpm dev

Commands

List projects and VMs

cd ~/.hatch-cli && pnpm dev list --json

Use first to find project names. Returns JSON with projects array and vms array.

Check status of VMs, spikes, and PRs

cd ~/.hatch-cli && pnpm dev status --json

Returns dashboard with VM liveness, spike progress, and PR review/CI status.

Options:

• --json

  - Output as JSON (recommended for agents)

• --project <name>

  - Filter to a specific project

Use after starting a spike to check progress, PR review status, and CI checks. Automatically detects if a "running" spike has actually completed.

Create new project

cd ~/.hatch-cli && pnpm dev new <project-name> --dry-run
cd ~/.hatch-cli && pnpm dev new <project-name> --confirm <token>

Creates a new project with GitHub repo, Vercel deployment, and Convex backend. Takes 5-10 minutes. Returns Vercel URL when complete.

Options:

• --dry-run

  - Show what will be created and get a confirmation token

• --confirm <token>

  - Execute with a token from

  --dry-run

• -f, --force

  - Skip confirmation (interactive terminal only)

Create feature VM (interactive development)

cd ~/.hatch-cli && pnpm dev feature <name> --project <project> --dry-run
cd ~/.hatch-cli && pnpm dev feature <name> --project <project> --confirm <token>

Creates isolated VM with git branch and a separate Convex project for isolation. Returns SSH host and preview URL. User will SSH in and drive development with Claude Code.

Options:

• --dry-run

  - Show what will be created and get a confirmation token

• --confirm <token>

  - Execute with a token from

  --dry-run

• -f, --force

  - Skip confirmation (interactive terminal only)

Autonomous spike (fire and forget)

cd ~/.hatch-cli && pnpm dev spike <name> --project <project> --prompt "<instructions>" --dry-run
cd ~/.hatch-cli && pnpm dev spike <name> --project <project> --prompt "<instructions>" --confirm <token>

Creates VM, runs Claude Agent SDK autonomously, creates PR when done.

Options:

• --wait

  - Block until spike completes (default: return immediately)

• --timeout <minutes>

  - Max time when using

  --wait

  (default: 240)

• --json

  - Output result as JSON

• --dry-run

  - Show what will be created and get a confirmation token

• --confirm <token>

  - Execute with a token from

  --dry-run

• -f, --force

  - Skip confirmation (interactive terminal only)

Show detailed spike progress

cd ~/.hatch-cli && pnpm dev progress <feature> --project <project>

Shows detailed spike progress for a feature VM including plan steps checklist and recent log activity.

Options:

• --json

  - Output as JSON (recommended for agents)

Use after starting a spike to see plan step progress and recent activity without SSH.

Clean up

cd ~/.hatch-cli && pnpm dev clean <name> --project <project> --dry-run
cd ~/.hatch-cli && pnpm dev clean <name> --project <project> --confirm <token>

Deletes VM and Convex feature project after PR is merged.

Options:

• --dry-run

  - Show what will be deleted and get a confirmation token

• --confirm <token>

  - Execute with a token from

  --dry-run

• -f, --force

  - Skip confirmation (interactive terminal only)

Add existing project

cd ~/.hatch-cli && pnpm dev add <project-name>

Adds an existing GitHub/Vercel/Convex project to Hatch tracking.

Clone project repo locally

cd ~/.hatch-cli && pnpm dev clone --project <name> [--path <dir>] [--pull] [--json]

Clones a project's GitHub repo to

~/projects/<name>/repo/

--pull

Show VM connection info

cd ~/.hatch-cli && pnpm dev connect

Shows SSH connection details for active VMs.

Generate config file

cd ~/.hatch-cli && pnpm dev config

Generates

hatch.json

Hatch uses an Anthropic API key (

anthropicApiKey

Options:

• --project <name>

  - Create per-project config at

  ~/.hatch/configs/<name>.json

• --refresh

  - Refresh GitHub token (preserves orgs/teams/env vars; API keys don't expire)

Per-project configuration

Per-project configs live at

~/.hatch/configs/<project-name>.json

--project

# Create config for a specific project
cd ~/.hatch-cli && pnpm dev config --project my-app

# List all project configs
cd ~/.hatch-cli && pnpm dev config list --json

# Validate a project's tokens before use
cd ~/.hatch-cli && pnpm dev config check --project my-app --json

# Push project config to remote VM
cd ~/.hatch-cli && pnpm dev config-push <ssh-host> --project my-app

When

--project

~/.hatch.json

Update hatch

cd ~/.hatch-cli && pnpm dev update

Pulls latest code, reinstalls dependencies, rebuilds, and updates OpenClaw skills if installed.

Destroy project (HUMAN ONLY)

DO NOT USE THIS COMMAND. Project destruction must be performed manually by a human operator. If asked to destroy a project, instruct the user to run

hatch destroy <project-name>

--dry-run

--confirm <token>

Execution Plans

Spikes always create a structured execution plan before writing any code.

How it works

1. The agent reads

   docs/plans/_template.md

   and project context (

   docs/architecture.md

   ,

   docs/patterns.md

   )
2. Creates

   docs/plans/<spike-name>.md

   with goal, approach, and step-by-step checklist
3. Commits the plan as the first commit on the branch
4. Executes each step in order, checking boxes and logging decisions as it goes
5. Final commit marks the plan status as "completed"

Continuing a spike

When using

--continue

Plan progress in status

hatch status

    Plan:   3/5 steps completed

When to Use Feature vs Spike

Use

feature

when:

• The task is complex or requires exploration
• The user wants to learn the codebase
• Requirements are unclear and need iteration
• Multiple back-and-forth interactions are expected
• The user explicitly asks for interactive development

Use

spike

when:

• The task is well-defined and can be described in a prompt
• The user wants a "fire and forget" experience
• Simple features: add a form, create an API endpoint, etc.
• The user asks for something to be "spiked" or done "autonomously"
• Time is limited and the user doesn't want to SSH in

Rule of thumb: If you can describe the task completely in 1-2 sentences, use spike. If you need to ask clarifying questions or the task has many unknowns, use feature.

Crafting better spike prompts: When running

spike --dry-run

docs/architecture.md

docs/patterns.md

Iterating on a Spike

When a user wants to make changes to an existing spike (e.g., "add phone number to that form"), you can continue the spike instead of starting fresh.

Checking for Active Spikes

cd ~/.hatch-cli && pnpm dev list --json

Look for VMs with

spikeStatus: "completed"

Continuing a Spike

cd ~/.hatch-cli && pnpm dev spike <feature> --project <project> --continue <vm-name> --prompt "additional changes"

Options:

• --continue <vm-name>

  - Continue an existing spike on the specified VM

• --wait

  - Block until iteration completes

• --json

  - Output result as JSON

What Happens on Continuation

The agent will:

1. Load context of all previous prompts from

   ~/spike-context.json

2. Make changes based on the new prompt
3. Add new commits to the existing branch
4. Push to update the existing PR (no new PR created)

When to Ask About Continuation

When the user's request relates to a recently completed spike:

1. Check for active spikes in the same project
2. Ask: "You have an active spike 'feature-name' with PR at [url]. Continue that spike with additional changes, or start a new one?"
3. If continuing, use

   --continue <vm-name>

Continuation Limitations

• Can only continue spikes with

  spikeStatus: "completed"

• Cannot continue while a spike is still running
• If VM is unreachable, user must clean and start fresh

Monitoring Spike Progress

After starting a spike, monitor with these SSH commands:

# Human-readable log (best for following along)
ssh <vm>.exe.xyz 'tail -f ~/spike.log'

# Structured progress events (JSON lines)
ssh <vm>.exe.xyz 'tail -f ~/spike-progress.jsonl'

# Check if done
ssh <vm>.exe.xyz 'test -f ~/spike-done && echo "Done" || echo "Running"'

# Get final result (includes cost)
ssh <vm>.exe.xyz 'cat ~/spike-result.json'

# Get PR URL
ssh <vm>.exe.xyz 'cat ~/pr-url.txt'

Spike Output Files

The spike writes these files to the VM home directory:

~/spike.log

~/spike-progress.jsonl

~/spike-result.json

~/spike-done

~/pr-url.txt

Observability (Structured Logs)

Generated projects include structured logging. In development, the server logger writes JSON log entries to

~/.harness/logs/app.jsonl

Log Query Commands

Run these from the project root on the VM:

pnpm harness:logs

pnpm harness:logs:errors

pnpm harness:logs:slow

pnpm harness:logs:summary

pnpm harness:logs:clear

Additional flags:

--route <path>

--since <5m|1h|30s>

--limit <n>

--json

Cost Tracking

Spikes track token usage and cost in

~/spike-result.json

{
  "status": "completed",
  "sessionId": "session_abc123",
  "cost": {
    "inputTokens": 45000,
    "outputTokens": 12000,
    "totalUsd": 0.0234
  }
}

Report costs to the user when a spike completes.

Environment Safety

CRITICAL: Always confirm with the human before taking action. Never run provisioning, destructive, or deployment commands without first showing the human exactly what you plan to do and getting explicit approval.

Commands that create, modify, or destroy resources (

new

spike

feature

clean

destroy

--dry-run

--confirm <token>

Pre-flight check (required before any provisioning command)

Before running

hatch new

hatch feature

hatch spike

hatch clean

hatch add

1. Gather context: Run

   hatch list --json

   and

   hatch config check --project <name> --json

   to understand the current state.
2. Show the human a summary that includes:
   • The exact command you plan to run (with

     --dry-run

     )
   • Which project and config will be used (

     ~/.hatch/configs/<name>.json

     or

     ~/.hatch.json

     )
   • Which GitHub org, Vercel team, and Convex deployment will be affected
   • For spikes: the full prompt text
   • For clean: what resources will be deleted (VM name, Convex project)
3. Run with

   --dry-run

   to get a confirmation token, then run with

   --confirm <token>

   after human approval.

General rules

• Never assume config: Always pass

  --project <name>

  explicitly. Do not rely on the global fallback when per-project configs exist.
• Cross-check project names: The

  --project

  value must match both the project name in

  hatch list

  and the config filename in

  ~/.hatch/configs/

  . Mismatches mean wrong credentials.
• NEVER run

  hatch destroy

  : This command permanently deletes Convex and Vercel projects. Only a human operator should run destroy. If a user asks you to destroy a project, tell them to run the command manually.

Workflows

Every workflow follows the same pattern: gather context → show the human → get approval → execute. For spikes specifically: gather context → read local repo → draft prompt → iterate with human on prompt → execute.

Create new project

# 1. Check which config will be used
cd ~/.hatch-cli && pnpm dev config list --json

# 2. Show the human: "I'll create project 'my-app' using config ~/.hatch/configs/my-app.json
#    (GitHub org: X, Vercel team: Y). This provisions a temporary VM. Proceed?"

# 3. Dry run to get a confirmation token:
cd ~/.hatch-cli && pnpm dev new my-app --dry-run

# 4. After approval, confirm with the token:
cd ~/.hatch-cli && pnpm dev new my-app --confirm <token>

Share Vercel URL when complete.

Manual feature development

# 1. Gather context
cd ~/.hatch-cli && pnpm dev list --json
cd ~/.hatch-cli && pnpm dev config check --project my-app --json

# 2. Show the human: "I'll create feature VM 'my-feature' for project 'my-app'
#    using config ~/.hatch/configs/my-app.json (GitHub: org/my-app, Convex: my-app).
#    This creates a VM, git branch, and isolated Convex project. Proceed?"

# 3. Dry run to get a confirmation token:
cd ~/.hatch-cli && pnpm dev feature my-feature --project my-app --dry-run

# 4. After approval, confirm with the token:
cd ~/.hatch-cli && pnpm dev feature my-feature --project my-app --confirm <token>

Share SSH host so user can connect with Claude Code.

Autonomous spike

# 1. Gather context
cd ~/.hatch-cli && pnpm dev list --json
cd ~/.hatch-cli && pnpm dev config check --project my-app --json

# 2. Show the human: "I'll spike 'my-feature' on project 'my-app'
#    using config ~/.hatch/configs/my-app.json.
#    Prompt: 'Add contact form'
#    This creates a VM, runs Claude autonomously, and opens a PR. Proceed?"

# 3. Dry run to get a confirmation token (also clones/pulls repo locally):
cd ~/.hatch-cli && pnpm dev spike my-feature --project my-app --prompt "Add contact form" --dry-run
# The dry-run output includes a "Local mirror" path (e.g. ~/projects/my-app/repo/).
# Read the local repo to understand the codebase before crafting your spike prompt.
# Key files to check: docs/architecture.md, docs/patterns.md, CLAUDE.md, and relevant source files.

# 4. Draft a detailed prompt based on what you learned from the codebase, then
#    SHOW IT TO THE HUMAN for review before executing. Example:
#
#    "Here's the spike prompt I'd like to run:
#
#    Add a contact form to the /contact page. Use the existing FormCard component
#    from packages/ui/src/components/form-card.tsx. Fields: name, email, message.
#    Submit via a Convex mutation in convex/contact.ts. Add success toast using
#    the existing useToast hook.
#
#    Want me to adjust anything before I run it?"
#
# Iterate with the human until they approve the prompt.

# 5. After the human approves the prompt, confirm with the token:
cd ~/.hatch-cli && pnpm dev spike my-feature --project my-app --prompt "<final approved prompt>" --confirm <token>

# 6. Check status (VM liveness, spike progress, PR review/CI)
cd ~/.hatch-cli && pnpm dev status --project my-app --json

# 7. Optionally monitor progress
ssh <vm>.exe.xyz 'tail -f ~/spike.log'

# 8. Check for completion
ssh <vm>.exe.xyz 'test -f ~/spike-done && cat ~/spike-result.json'

# 9. Clean up after PR is merged (dry-run first, then confirm)
cd ~/.hatch-cli && pnpm dev clean my-feature --project my-app --dry-run
cd ~/.hatch-cli && pnpm dev clean my-feature --project my-app --confirm <token>

Share PR URL when complete.

Blocking spike (wait for completion)

cd ~/.hatch-cli && pnpm dev spike my-feature --project my-app --prompt "Add contact form" --wait --json

Returns full result including PR URL and cost when done.

Anthropic API Key

Spikes use the

anthropicApiKey

~/.hatch/configs/<name>.json

claude

Error Handling

If a spike fails:

1. Check

   ~/spike.log

   for error details
2. The VM remains running for debugging
3. User can SSH in and fix issues manually
4. Or clean up with

   cd ~/.hatch-cli && pnpm dev clean

   and try again

If the spike command itself fails (before agent starts):

• The command automatically rolls back and deletes the VM
• Check error message for the cause (missing config, auth failure, network issues, etc.)
• For auth failures: update

  anthropicApiKey

  in the project config (

  ~/.hatch/configs/<name>.json

  ) and retry

Important: Do Not Modify VM Code Directly

NEVER SSH into a spike VM to make code changes directly. This bypasses the Claude agent running on the VM which has full project context, proper tooling, and tracks its work.

Instead:

• Use

  hatch spike --continue <vm-name> --prompt "description of changes"

  to iterate
• The agent on the VM has Claude Code with Bash, Read, Write, Edit, Glob, and Grep tools
• Direct SSH modifications will conflict with the agent's work and won't be tracked

You may SSH into VMs only for read-only monitoring (e.g.,

tail -f ~/spike.log