Getting Started

Prerequisites

Node.js ≥ 20 and a Git repository (git init first if you don't have one yet -- PitWay refuses to run outside a Git work tree).

Install

npm install -g pitway

Initialize

Run once from the root of a Git repository:

pitway init

pitway init:

  • Creates .pitway/ -- a config.yaml and state.yaml, both empty of milestones until you add one.
  • Installs the Claude Code integration into .claude/ by default (opt out with --no-claude).
  • Add --opencode and/or --codex to also install the OpenCode (.opencode/) and Codex (.codex/) integrations -- commands, skills, and driver protocol documents, resolved from one shared common layer. See Claude Code, OpenCode, and Codex for details on each.
  • Creates root AGENTS.md/CLAUDE.md instruction files inside an explicit <!-- pitway:managed:start/end --> block, so it's safe to run against a repo that already has its own.
  • Is safe to re-run: byte-identical files are left alone, and a genuine conflict with something you've hand-edited refuses loudly rather than overwriting it.

Upgrading pitway

After npm install -g pitway pulls a newer version, run:

pitway init --reconfigure

A plain pitway init re-run only fills in files that don't exist yet -- it never updates ones you already have, so installed commands, skills, and protocol docs silently go stale after an upgrade. --reconfigure refreshes every managed integration asset to the newly installed version; .pitway/ state (milestones, contracts, tasks) is always preserved.

Explore the command surface

pitway --help

That's the full, authoritative CLI command surface and available flags.

What's next

A freshly initialized repository has no active milestone yet -- there's nothing for pitway resume to reconstruct until you've drafted and confirmed one (resume reports "No active milestone" on a fresh repo). The next step is drafting your first milestone contract and task graph.