harper-local-dev

Original：🇺🇸 English

Translated

1 scriptsChecked / no sensitive code detected

Guidelines for running Harper on a developer machine, covering isolated dev instances, parallel instances across git worktrees, loopback address allocation, and per-instance data roots. Triggers on tasks involving local Harper dev servers, running several Harper instances at once, git worktrees, port conflicts (EADDRINUSE), dev-mode reload loops, or running a Harper dev server under an AI-agent sandbox.

6installs

Sourceharperfast/skills

Added on2026-10-09

NPX Install

npx skill4agent add harperfast/skills harper-local-dev

SKILL.md Content

View Translation Comparison →

Harper Local Development

Guidelines for running and managing Harper on a developer machine. Where

harper-best-practices

covers how to build a Harper application, this skill covers the environment you build it in: how dev instances are started, isolated from one another, and cleaned up.

When to Use

Reference these guidelines when:

Running more than one Harper dev instance on the same machine (one per git worktree, branch, or agent session)
Diagnosing
```
EADDRINUSE
```
on Harper's default ports, or a dev server that reloads in a loop
Setting up a project's
```
npm run dev
```
so that it is safe to run in parallel
Pointing tooling (agents, browsers, test scripts) at the right dev instance for the current worktree
Letting a sandboxed AI agent (e.g. Claude Code with the sandbox enabled) start and reach a dev instance

How It Works

Identify the shared state two Harper processes would contend for (ports, data root, file watcher).
Consult the relevant rule under "Quick Reference" below and read its rule file.
Prefer the ready-to-copy scripts under
```
scripts/
```
over writing your own wrapper.

Examples

See the concrete examples embedded in each rule (wrapper scripts,

package.json

wiring, and debugging commands), plus the reference implementations in

scripts/

.

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	Dev Instances	HIGH	`dev-`

Quick Reference

1. Dev Instances (HIGH)

```
running-dev-instances-in-worktrees
```
— Run multiple Harper dev instances in parallel from git worktrees with isolated data roots and loopback addresses.

How to Use

Read individual rule files for detailed explanations and code examples:

rules/running-dev-instances-in-worktrees.md

Full Compiled Document

For the complete guide with all rules expanded:

AGENTS.md