# Installation (/docs/installation)



<Callout type="warn">
  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](#from-source).
</Callout>

<Steps>
  <Step>
    ### Install warden [#install-warden]

    ```bash
    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:

    ```bash
    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.
  </Step>

  <Step>
    ### Choose agents [#choose-agents]

    ```bash
    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](/docs/guides/agents) for what gets installed.
  </Step>

  <Step>
    ### Check it [#check-it]

    ```bash
    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.
  </Step>
</Steps>

## From source [#from-source]

From a checkout of the warden repo:

```bash
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 [#agent-skill-only]

For Claude Code, Codex, Cursor and others via the [`skills`](https://github.com/vercel-labs/skills) CLI:

```bash
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 [#in-github-actions]

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

```yaml
- 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).