Installation

shelf is one self-contained binary for macOS, Linux and Windows. It does not need Node, Bun or a network connection to run.

With npm

npm install -g @limyuquan/shelf
shelf setup

The npm package is a small launcher plus one platform package per OS and CPU, listed as optional dependencies, so npm downloads only the binary for your machine. There are no install scripts. Node 18 or later runs the launcher.

If npm was told to skip optional dependencies (--no-optional, --omit=optional), the launcher can't find a binary and says so:

shelf: no prebuilt binary for linux-x64 (@limyuquan/shelf-linux-x64 is not installed).
Reinstall without --no-optional / --omit=optional, or download a binary from the GitHub release.

Binaries

Download an archive for your platform from the releases page:

Each release also has a SHA256SUMS file. Check your download against it, then put the binary on your PATH:

sha256sum --check --ignore-missing SHA256SUMS   # macOS: shasum -a 256 --check --ignore-missing SHA256SUMS
tar -xzf shelf-linux-x64.tar.gz
mv shelf ~/.local/bin/
shelf --version

macOS quarantine

The binaries are not code-signed yet. macOS quarantines files downloaded with a browser and refuses to run them. Clear the flag once:

xattr -d com.apple.quarantine shelf

Installs through npm, or downloads with curl, are not affected.

From source

shelf is built with Bun (the version is pinned in package.json, currently 1.4.2):

git clone https://github.com/limyuquan/shelf.git
cd shelf
bun install
bun run build        # produces dist/shelf

bun run build:all cross-compiles every platform into dist/. See Contributing for the development workflow.

Set up

Run shelf setup once after installing, and again after every upgrade:

$ shelf setup
Shelf home: /home/me/.shelf
Library:    /home/me/.shelf/library
Installed the shelf skill at:
  /home/me/.agents/skills/shelf/SKILL.md
  /home/me/.claude/skills/shelf/SKILL.md

Hooks (renew skills when used, report loans needing attention):
  Claude Code: hooks installed (/home/me/.claude/settings.json)
  Codex: hooks installed (/home/me/.codex/hooks.json)
Codex runs new hooks only after you trust them: open `/hooks` in Codex once.

It does three things, all safe to repeat:

1. Creates the shelf home (~/.shelf, or $SHELF_HOME) with library/, objects/ and a config.json holding every default.
2. Installs the bundled shelf skill in your user-level skill directories, so agents in every project know shelf exists. It costs about 66 tokens of context per session.
3. Installs hooks in Claude Code and Codex, if they are installed, so loans renew when agents use skills.

Codex runs new hooks only after you trust them: open /hooks in Codex once. To skip the hooks, run shelf setup --no-hooks. See shelf setup for details.

Then check everything with:

shelf doctor

Upgrading

Install the new version the same way you installed the old one (npm install -g @limyuquan/shelf, or replace the binary), then run:

shelf setup

This refreshes the bundled skill and points the hooks at the new binary. The hooks call the binary by its absolute path, so moving or replacing the binary at a different path leaves them pointing at the old one; shelf doctor reports this and shelf doctor --fix repairs it.

Your library, revisions, loans and config are kept across upgrades. The database migrates itself the first time the new version opens it.

Uninstalling

1. Remove the hooks while shelf is still installed:

   terminal

   shelf setup --no-hooks

   This removes only shelf's entries from ~/.claude/settings.json and ~/.codex/hooks.json.

2. In each project, decide what happens to borrowed skills. shelf detach <name> keeps the files as ordinary project files; shelf return <name> removes them. Then delete .agents/shelf.lock.json. shelf projects lists every project.

3. Delete the bundled skill: ~/.agents/skills/shelf/ and ~/.claude/skills/shelf/ (and the same folder under any other harness that shelf setup listed).

4. Back up your library if you want to keep your skills (~/.shelf/library holds plain skill folders), then delete ~/.shelf.

5. Remove the binary: npm uninstall -g @limyuquan/shelf, or delete the file.

See Files for everything shelf writes.