Configuration

The file

The config is config.json in the shelf home: ~/.shelf/config.json, or $SHELF_HOME/config.json when SHELF_HOME is set. shelf setup creates it with every default:

{
  "loanDays": 30,
  "maxLoanDays": 90,
  "dueSoonDays": 7,
  "allowAgentImports": false,
  "hooks": true,
  "mode": "copy",
  "targets": [
    ".agents/skills",
    ".claude/skills"
  ]
}

Edit it with any editor; there is no shelf config command. Every command reads it when it starts. shelf ui reads it once at startup, so restart the dashboard after editing it. Missing keys take their defaults, so a file with only the keys you change works too. Without a file, every default applies.

shelf setup only ever changes the hooks key in an existing file; everything else you set is kept.

Keys

loanDays

The default loan length, in days: how long a new loan lasts, and how far a use or a renewal moves the due date. A skill can override it with shelf loan-days. Always capped at maxLoanDays.

maxLoanDays

No command sets a due date more than this many days from now (borrow --days, renew, due, loan-days all fail with LOAN_LIMIT past it). Lowering it doesn't shorten existing loans, but skill loan lengths above it are capped from then on.

dueSoonDays

A loan is due-soon when it is due within this many days. It then shows in shelf status next steps, the session-start note and the dashboard's Attention page. 0 turns the state off.

allowAgentImports

When false, agents (actors starting with agent:) may review skills from git sources but not import them: shelf add --yes of a new skill and shelf pull --yes fail with NOT_ALLOWED. Set it to true only if you want agents to widen your library on their own. See Importing skills.

hooks

Whether shelf's harness hooks should be installed. shelf setup sets it (--no-hooks writes false), and shelf doctor checks the hooks only when it is true. Editing it by hand doesn't install or remove hooks; run shelf setup or shelf setup --no-hooks.

mode

copy gives every target its own copy of a borrowed skill. link keeps one copy in the first target and makes the others relative symlinks to it (junctions on Windows). Applies to new loans; shelf borrow --link chooses link mode for one loan. See Harnesses.

targets

The project-relative directories borrowed skills are written into, at least one. A project can override it with shelf targets, which stores its own list in the lockfile. Changing this key doesn't move existing loans; shelf targets --reset in a project applies it there.

Examples

Longer loans, warned about two weeks ahead:

{ "loanDays": 60, "dueSoonDays": 14 }

One copy per project, also written for Kiro:

{ "mode": "link", "targets": [".agents/skills", ".claude/skills", ".kiro/skills"] }

Invalid config

A config that isn't valid JSON, or has a value of the wrong type, makes every command fail with INVALID_ARGUMENT (exit 2) until it is fixed:

$ shelf status
error: Invalid config /home/me/.shelf/config.json: ✖ Invalid input: expected number, received string
  → at loanDays

Unknown keys are ignored.

Settings that aren't in the config

Related

• Environment, Files, Lockfile