Installation

Install warden from npm or build it from source, wire up agent hooks, and check your setup.

The npm release of @delacour/warden is pending. These commands are the intended install path and work once the first version is published. Until then, build from source.

Install warden

npm i -g @delacour/warden && warden install    # or: bun add -g @delacour/warden && warden install

warden install links ~/.local/bin/warden (what the hooks call) to the global package, so npm i -g @delacour/warden@latest upgrades both.

For a one-shot run with nothing installed globally:

npx @delacour/warden install     # or: bunx @delacour/warden install

This copies the binary to ~/.local/bin/warden and wires the hooks. It only puts warden on your PATH if ~/.local/bin is already on it, which macOS doesn't do by default. If warden isn't found afterwards, use the global install. To update a one-shot install, run warden update, which fetches it from npm, or re-run npx @delacour/warden@latest install.

The package is a small node shim plus one prebuilt binary per platform (@delacour/warden-{darwin,linux}-{arm64,x64}, an optional dependency). macOS and Linux on arm64 and x64 are supported; Windows isn't.

Choose agents

warden install            # binary + hooks for every detected agent; shows a diff, asks first
warden install --claude   # force Claude Code only: skill + hooks + argent rule
warden install --codex    # force Codex only: hooks in $CODEX_HOME/hooks.json

Every agent-config change shows a diff and asks first. --yes skips the prompt, --dry-run only prints, and a non-TTY without --yes skips. Merges are idempotent and keep all other config. See Agents for what gets installed.

Check it

warden doctor

doctor checks warden's home, the db, device tools (xcrun simctl, adb, emulator), how warden was installed (and how to upgrade it), PATH, Claude/Codex hooks and skill, and stale leases.

From source

From a checkout of the warden repo:

bun install
bun run --cwd apps/cli install:global   # local build of this checkout → ~/.local/bin/warden
warden install

~/.local/bin must be on PATH. Set WARDEN_HOME to override ~/.warden. warden update rebuilds from the checkout.

Agent skill only

For Claude Code, Codex, Cursor and others via the skills CLI:

warden skill show | pbcopy                         # raw SKILL.md to paste by hand
warden skill install                               # this binary's embedded copy, global
warden skill install --from github                 # delacournz/warden, updatable via `skills update`
warden skill install --project -a claude-code -y   # into the current project, one agent, no prompts

The skill's source is skills/warden/SKILL.md, embedded in the binary. npx is used when bunx isn't available; --dry-run prints the command.

In GitHub Actions

The repo is private, so CI installs the release binary with a token instead of npm:

- uses: delacournz/warden/.github/actions/install-warden@main
  with:
    token: ${{ secrets.WARDEN_RELEASE_TOKEN }}

WARDEN_RELEASE_TOKEN needs Contents: read on delacournz/warden (fine-grained PAT or GitHub App token). Allow the action's repo under Settings → Actions → General → Access. The action downloads warden-<os>-<arch> from the latest (or version:) release, checks checksums.txt and adds warden to PATH.

A clean macOS runner needs no setup beyond an installed iOS runtime: the profile's simulators are created on claim, cloned from a golden image built on first use (cache ~/Library/Developer/CoreSimulator/Devices to skip that next time).