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

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