Skip to content
xiv

Getting Started

Prerequisites, installation, and setting up xiv with xiv init and xiv update.

Prerequisites

RequirementWhyNeeded for
bunThe CLI runs from source under bun; xiv init also runs bun install inside SMITHERS_HOMEeverything
gh CLI, authenticatedOpening, reading, and pushing PRsship, the pr family, stack push / stack review
claude and codex CLIs, logged inThe agents the workflows driveany workflow that runs agent steps
Linear MCP configured on those agentsIssues are the unit of work — workflows fetch them over MCPimplement, ship, stack plan / build
jj (Jujutsu) on PATH (brew install jj)The rebase engine for stacked features, run colocated with gitxiv stack only
A git repo on its base branchCommands act on the repo you invoke them from (default base main; --base otherwise)every workflow command

You do not install Smithers separately. The engine (smithers-orchestrator) is a dependency of the workflow pack: xiv init copies the pack into SMITHERS_HOME and runs bun install there, and workflows execute through that copy's own node_modules/.bin/smithers.

Environment

VariableDefaultMeaning
SMITHERS_HOME~/.smithersWhere the managed pack, engine, and all run state live. If HOME is unset you must set this explicitly.
SMITHERS_TARGET_CWD(set by xiv)The repo a workflow operates on — always the directory you invoked the command from (or --cwd for dev/check). You never set this yourself.

Model-tier variables (XIV_TIER, XIV_MODEL_HEAVY, XIV_AGENT_MAX_USD, …) are covered in Model tiers.

Installation

Installing means cloning the repo — the xiv command runs straight from the clone's source:

git clone https://github.com/jacobdcastro/xiv.git && cd xiv
bun install
bun link

bun link points the xiv command at this repo's src/cli.ts. There is no build or publish step — the CLI runs from source, so pulling new CLI code takes effect immediately. The clone can live anywhere (nothing depends on its path); wherever you keep it becomes the machine's canonical copy. Only the pack and skills need an explicit install step, which is what init and update do.

xiv init and xiv update — the two layers

Both commands install the same two layers; init is the first-time run, update is every run after (they share an implementation).

LayerSourceDestinationRead by
Workflow packpack/ in this repoSMITHERS_HOMEthe Smithers engine, when running a workflow
Skillsskills/ in this repoyour agent directories, via the skills CLIthe agent driving xiv
xiv init                 # first time: pack + skills
xiv update               # after pulling changes: pack + skills
xiv update --no-skills   # pack only (offline, or keep the agents' current skills)

What each half does:

  • Pack: every file under pack/ is hashed and copied into SMITHERS_HOME, a manifest is written to .xiv/manifest.json, and bun install runs there. If a managed file in SMITHERS_HOME was edited since the last install, the drifted copy is backed up to .xiv/backups/<timestamp>/ before being overwritten — see Managed files.
  • Skills: installed with npx skills@latest add <repo-root> --skill '*' --global. It installs all of this repo's skills but prompts you for which agents to install into — that choice is deliberately never auto-answered.

Two behaviors worth knowing:

First run

From the repo you want worked on:

cd /path/to/target-repo
xiv implement ENG-123

This launches the linear-implement workflow against that repo: fetch ENG-123 from Linear, plan, then loop implement → validate → review on a dedicated branch until validation passes and the local review isn't requesting changes — up to 3 passes by default (--max-iterations, clamped 1–10). Everything stays local; nothing is pushed.

While it runs, observe rather than wait:

xiv ps        # what's running
xiv logs      # stream a run's logs
xiv ui        # live graph in the browser
xiv panic     # cancel ALL runs immediately (alias for xiv down)

When you want the same work to end in a PR, use xiv ship ENG-123 — implement plus opening a PR and settling its CI and comments. From there:

Suggest changes to this page