dennisonbertram/hdev/hetzner-dev

Plan here, build there

You do the thinking on this machine. A separate agent — Claude Code or Codex, installed on a Hetzner VM — does the building. Each slice of the plan gets its own VM, its own branch and its own PR. The job runs under systemd on the VM, so it keeps going after the SSH session ends and after the laptop closes.

Do not use this to drive a remote machine step by step. The handoff is one-shot: the remote agent gets a written brief and the repo, and nothing else.

Before anything else: is hdev installed?

Installing this skill does not install the CLI it drives. Run this first, every session, before promising the user anything:

command -v hdev

If that prints a path, skip to the Procedure. If it prints nothing, install it now — do not try to work around a missing hdev:

git clone https://github.com/dennisonbertram/hdev ~/develop/hdev

Then put it on PATH. Try a directory that is already there, so no shell profile needs editing:

mkdir -p ~/.local/bin && ln -sfn ~/develop/hdev/bin/hdev ~/.local/bin/hdev

That only works if ~/.local/bin is on PATH. Check, and fall back to the shell profile if it is not:

case ":$PATH:" in
  *":$HOME/.local/bin:"*) echo "on PATH — done" ;;
  *) echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
     echo "added to ~/.zshrc — tell the user to open a new terminal" ;;
esac

Confirm before continuing, in a login shell rather than the current one, because the current shell may have a PATH the user's next terminal will not:

zsh -lic 'command -v hdev && hdev mode'

If the user runs bash, use ~/.bashrc and bash -lic instead.

Writing to a shell profile is deliberately not pre-approved in this skill's allowed-tools, so the user is asked before it happens. Do not work around that prompt, and tell them which file you are editing.

First run: set up the stock flow with the user

Do this once per machine, before the first job. Two decisions, and they are the user's, not yours. Ask; do not pick silently.

Decision 1 — which agent runs the work

hdev login status

• Claude Code (default). Runs on the user's subscription, real enforced

subagents, safe to question mid-run. Needs hdev login.

• pi (-a pi). Runs on any model through a provider key, does not touch

the Claude window at all, and is the right tool for mechanical work. No subagent tool, and hdev ask refuses while it is running.

Most people want Claude set up regardless, and pi as well if they do volume mechanical work. Set up Claude first; it is one command.

Decision 2 — if they want pi, which model

Show them the real options and the trade-off, then let them choose:

hdev model --list

The default is `openrouter/deepseek/deepseek-v4-flash`, and most users should keep it. It costs $0.14 per million input tokens and $0.28 per million output, and it gives 1,048,576 tokens of context with a 393,216-token output limit. That is enough for any slice you should be writing.

The trade-off to explain is reasoning against price, not speed. A job runs unattended on a VM while the user does something else, so a model that answers in two seconds instead of twenty saves the user nothing. Do not recommend a model because it is fast.

Move up the catalog only for a real reason:

• The slice needs stronger reasoning than flash gives → deepseek-v4-pro,

about 8× the price.

• The work is dense code in a large file → qwen3-coder, but check its

65,536-token output limit against the size of the diff.

Once they pick:

hdev model openrouter/deepseek/deepseek-v4-flash   # or any pi model id
hdev login pi                                      # captures the credential for that provider

Check that the saved model and the captured credential agree. hdev model prints the model and hdev login status shows which provider was captured. A model whose provider has no credential fails when the job starts, not when the model is set.

hdev model saves the choice, so it is not an environment variable anyone has to remember. hdev model on its own shows what is set.

If they have no provider key, say so plainly and move on with Claude. pi is an option, not a requirement, and nothing else depends on it.

First run in a project: build it a profile

The base image has node, git, gh and the agents. It has no browser, no Docker, no Python, no Bun. A job needing those will report itself blocked, and the user finds out after waiting rather than before.

So the first time this skill is used in a repository, spend two minutes getting the environment right. Do this once per project, not once per job.

1. Read what the project actually needs. Look, do not assume:

The CI workflow is the most reliable source. It is the list someone already had to get right.

2. Check what profiles exist. hdev images. If one already covers it, use it with -p and stop here.

3. Otherwise build one. For a browser or Docker, the shipped profiles cover it. For anything else, let a job install it and capture the result:

hdev submit -k -b setup -m "Install <exact toolchain> so this project's test
suite runs. Then run the suite and report the command and the pass/fail counts.
Change no repository files."
hdev snapshot <job> <project-name>     # once it reports success
hdev submit -p <project-name> plan.md  # every later job starts there

-k keeps the VM so it can be captured. hdev snapshot scrubs credentials and the work tree first, and refuses while the job is still running.

4. Tell the user what you built and what it does not cover. Name the profile and say which of their suites still cannot run on it.

Do not skip to submitting real work on the base image and then report a pile of "could not verify" results. Getting the environment right first is cheaper than a job that runs for ten minutes and verifies nothing.

Procedure

1. Plan on this machine

Explore the codebase here, where it is cheap, and write the plan to a file. This is the normal planning work — read the code, find the real seams, decide the approach.

2. Slice the plan

Write the plan with one ## Slice: heading per independently shippable piece:

# Rate limiting rollout
 
## Slice: Add the token bucket
Implement a token bucket in `lib/ratelimit.ts`. 60 requests per minute per key.
Done when: `npm test lib/ratelimit.test.ts` passes.
 
## Slice: Wire /api/send
Call the bucket in `app/api/send/route.ts` before the handler. Return 429 with
a Retry-After header when the bucket is empty.
Done when: the new integration test passes.

A slice is only ready when it has all five of these. This list comes from the fast-efficient skill, which measured it against a cheap implementer; it applies to every remote agent here for the same reason.

1. One runnable acceptance command, and the exact numbers it must print.

Record the baseline first: 233 passed, 3 skipped. "Make the tests pass" is not an acceptance condition.

1. Tests that already exist and already fail. You write them, here, before

submitting. Run them and confirm they fail for the right reason — a 404 because the route is missing is a correct failure; a connection error is not. Push them, because the VM clones from GitHub.

1. A closed list of files the agent may create or change. Name every one.

Everything else is out of bounds and the reviewer checks it.

1. The exact contract: type signatures, field names, check order, status

codes, error strings — written out verbatim, not described. A gap in the contract becomes a gap in the code.

1. A size a reviewer will actually read. The default model allows 393,216

output tokens, so the model's limit is not what bounds a slice — the PR is. If you cannot name every file the slice touches, it is too big. Split it. Check the output limit in hdev model --list only when the user has chosen a model with a smaller one, such as qwen3-coder at 65,536.

Two more that are specific to running remotely:

• Slices must not depend on each other. They run in parallel on separate

VMs from the same base commit and produce separate PRs.

• No secrets in the text. Credentials reach the VM over SSH separately.

~/.claude/skills/fast-efficient/assets/slice-template.md is a blank packet in exactly this shape. Start from it rather than freehand.

3. Check the repo state, then submit

hdev clones from the GitHub remote, so anything uncommitted here is invisible to the remote agent. Run git status first and tell the user if the tree is dirty or the branch is unpushed.

hdev submit plan.md                 # one VM per slice, Claude Code
hdev submit -a codex plan.md        # same, using Codex
hdev submit -1 plan.md              # whole file as one job
hdev submit -m "raise the upstream timeout to 30s"   # no plan file

Always name the job

Pass `-b <short-name>` on every submit. Without it, jobs are named from the first words of the task and become unreadable — hdev-agent-0814-1357-add-src-t tells you nothing when four are running. The name flows into the job name, the branch and the PR.

hdev submit -b epic473 plan.md      # → hdev-epic473-…, branch epic473/…

Use whatever the user already calls the work: a ticket id, an epic number, a feature name. Short, lowercase, no spaces. When you submit several slices at once give them one shared prefix so they read as a set. Tell the user the names you chose — they need them for hdev status, hdev ask and hdev logs.

Other flags: -t cpx32 for a bigger VM, -p <profile> to boot from a snapshot that already has the toolchain, -e <file> to send an untracked file.

Check hdev images before submitting. If the work needs a browser, submit with -p browser rather than letting the agent install Chromium on every job. If it needs Docker, use -p docker. Naming a profile that has not been built fails, so list them first.

submit returns as soon as the jobs start. Tell the user they can close the laptop, and give them the job names.

Then start the watch loop — every time, in the same message

A submitted job with nobody watching it is a VM that bills until somebody remembers. So do not stop at "here are the job names". Start the loop as part of the same response:

/loop 10m check my hdev jobs, review anything new, and close out what is done

Say you have started it, at what interval, and that it stops on its own once every job is reaped. If the user does not want it, they will say so — but the default is that a submit is always followed by a watch.

Use dynamic mode when the job length is unknown, because it wakes on the event rather than on a timer:

/loop check my hdev jobs and tell me when they finish

The tick procedure is in "Watching jobs and closing them out" below. The important part is that nothing else deletes these VMs. There is no server-side timeout and no auto-reap. If the loop is not running and the user walks away, the VM runs until someone notices.

4. Talk to the remote agent while it works

The remote agent runs as an orchestrator: it delegates to implementer, tester and reviewer subagents and keeps its own progress notes. You can reach it at any time.