04Agents · Overview

Create, monitor, review, clean, purge.

An agent's whole relationship with Artshelf fits in five stages. Each stage has its own page with the exact commands; this page is the contract that ties them together.

One simple loop runs the whole shelf, four moves: Capture automatically (register eligible artifacts at creation with artshelf put, or state the skip reason), Review calmly (read-only and dry-run only; turn the output into a decision packet - nothing moves), Approve exactly (a human approves one exact reviewed ledger or registry plus plan id or record ids), and Verify quiet (re-run a read-only check after every approved mutation). The five stages below are the mechanics behind those moves.

Workflow summary

4.1 Create artshelf put <path> --reason <why> --ttl <ttl>Register a temporary file while you still remember why it exists, or state the reason for skipping it. 4.2 Monitor artshelf review --all --jsonCheck the shelf on a schedule with read-only commands, and stay quiet when everything is clear. 4.3 Review artshelf cleanup --dry-run --jsonUse inspect plus cleanup, registry-prune, reconcile, and dispose dry-runs, then turn the output into an ArtshelfReviewReport decision packet a human can approve. 4.4 Clean artshelf cleanup --execute --plan-id <id>Run cleanup or dispose plans the human approved, resolve confirmed ids, and verify the next review is quiet. 4.5 Purge artshelf trash purge --execute --plan-id <id>Clear old trash through its own separately reviewed purge plan. Physical deletion never piggybacks on the cleanup plan that trashed the file.

Clean trashes; Purge deletes. Cleanup quarantines artifacts into Artshelf trash, and only a separate, separately reviewed purge plan removes them for good — a second approval boundary before destructive deletion.

Operating principles

agents remember: use the portable skill so final, status, and handoff turns check artifacts
crons only read: scheduled jobs may validate, review, dry-run, and report, but never execute; set ARTSHELF_NO_UPDATE_CHECK=1 when they must avoid npm network checks and update-cache writes
humans approve: mutation needs exact approval targets: ledger path, reviewed plan id, or record id list

Render modes

review, status, doctor, ledgers prune --dry-run, dispose --dry-run, and per-record get --inspect share agent-oriented render modes so the same data fits both people and agents. Reach for --agent when an agent decides and acts; reach for --json for full record, plan, or health detail. On get, --agent requires --inspect.

default: human render: scannable grouped counts, attention states, and a short next action for a person at the terminal
--agent: a deterministic, token-efficient decision packet (single-line compact JSON) with health, counts, classifications, blockers, record recommendations, approval targets where applicable, and a verification command
--json: the backward-compatible public audit contract: complete machine-readable JSON for debugging and integrations

UI sessions

artshelf ui starts or resumes a durable browser review session for the agent-mediated loop. artshelf ui dashboard --json returns the read-only multi-ledger review buckets, including needs-context, cleanup, resolve, trash, purge candidates, registry/reconcile problems, and recent receipts. artshelf ui detail <record-id> --ledger <path> --json returns the read-only artifact detail drawer with path label, inspect-card output, provenance, audit trail, existence facts, needs-context badge, and last action. Both views are metadata-only and never preview file contents. artshelf ui serve [--scope user|repo] [--port <port>] [--json] hosts those dashboard and detail views as a local browser page for a human reviewer; it binds to loopback (127.0.0.1) only, recomputes live state per request, requires the active UI session capability token printed in the serve URL, serves no script and no file contents, and supports --json for a compact launch packet. The dashboard stays display-only, while the detail drawer adds scriptless forms that capture lightweight human triage intents - inspect, comment, keep/trash/resolve/defer, and dry-run request - recording each as a pending event in the durable session log for the agent to act on after approval. The served bundle workbench at GET /bundle/<bundle-id> shows the selected exact targets, reviewed-only rows, and exact action from an immutable approval snapshot. With the active token, its scriptless form can submit a revised non-empty subset through POST /approve, creating a new immutable approval snapshot and pending approval event without editing the original bundle or executing a workflow. The session command defaults to user-level multi-ledger review and stores session state under ~/.artshelf/ui; use --scope repo or --ledger <path> when the review needs a narrower target.

The browser records exact-target triage intents, the agent polls with artshelf ui poll <session-id> --json, runs existing approval-gated commands only after exact human approval, replies with artshelf ui reply, and closes with artshelf ui end. The browser captures triage intents and approval bundles only and never mutates ledgers, files, trash, or plans directly. artshelf ui bundle <session-id> [<bundle-id>] --json is the agent's read surface over persisted approval bundles: with a bundle id it loads one immutable snapshot plus its resolved deliberate selection so the agent can revalidate live state before execution; with no bundle id it lists the session's approved bundles. It never executes a bundle.

Treat the session token printed by artshelf ui and artshelf ui serve as a secret same-machine browser capability; ending the session revokes future browser writes and served dashboard/detail/bundle access while keeping the audit trail readable.

The mental model

Green path Artifact is due, the dry-run plan is reviewed, and the approval target is exact.
Review first Artifact needs a human look, a retention change, or a keep/snooze decision.
Blocked Registry is stale, a path is suspicious, or the action would delete without a purge plan. Missing registrations use a reviewed registry-prune plan, not hand-edited JSON.

Portable skill

The repo ships a portable skill at skills/artshelf. Agents that support local skills can copy or reference the whole directory directly, including the bundled report renderer, schema, and example copies.