shelf

name

shelf

description

Access code reference repositories managed by shelf. Repos are cached at ~/.agents/shelf/repos/{alias}/ and kept in sync. Use your native tools (Grep, Read, Glob) to explore them. ALWAYS consult this skill before searching for code references, looking up how a library or framework works, grepping for implementations, reading source code from a reference repo, checking API signatures, finding usage examples in real codebases, or exploring how a dependency is structured. Trigger this skill whenever the user mentions code references, reference repos, shelf, grepping a codebase, reading library source, "how does X implement Y", "find examples of Z in the codebase", looking up types or interfaces, checking an upstream project's code, comparing implementations, or any task that benefits from consulting real source code in a cached repository — even if the user doesn't mention "shelf" by name. If the user asks you to look something up in a codebase, check an implementation, or find how something works in a library, this is the skill to use. Do NOT use for the user's own project code (use normal file tools for that), web searches, documentation lookups on the internet, or package registry queries.

Shelf — Code Reference Repos

Shelf maintains a local cache of code reference repositories at ~/.agents/shelf/repos/{alias}/. These repos let you answer questions about library internals, API surfaces, implementation patterns, and real-world usage — without searching the web or relying on training data that may be stale.

Why this matters: cached reference repos are faster and more reliable than web search for code questions. The code is local, complete, and version-pinned, so you can grep, read, and explore freely. Whenever a task involves understanding how a dependency, framework, or upstream project works, check shelf first.

Quick Start

1. Run shelf list to see which repos are available and their local paths.
2. Use your native tools on those paths:
   • Search: Grep or rg on ~/.agents/shelf/repos/{alias}/
   • Read files: Read on any file in the repo
   • Find files: Glob with patterns like ~/.agents/shelf/repos/{alias}/**/*.ts
   • Explore structure: ls ~/.agents/shelf/repos/{alias}/src/

Workflow

When the user asks about code in a reference repository:

1. Discover — Run shelf list to see available repos and their aliases. If the needed repo isn't there, ask the user if they'd like to add it with shelf add.
2. Search — Use rg (ripgrep) or Grep to find relevant code. Start broad (e.g., search for a function name, type name, or keyword), then narrow down.
3. Read — Open the relevant files and read the specific sections that answer the question.
4. Synthesize — Explain what you found, referencing file paths and line numbers so the user can verify.

Management Commands

Command	Purpose
shelf list	Show repos with local paths
shelf update [alias]	Sync one or all repos
shelf add <repo> [--alias name] [--pin ref]	Add a repo (accepts name, owner/repo, or URL)
shelf remove <alias>	Remove a repo
shelf detect [--apply]	Detect repos from project dependencies
shelf install [--dir path]	Install repos from a shelffile
shelf share [--filter aliases] [--stdout]	Generate a shelffile from current repos
shelf prune [--dry-run] [--force]	Remove unreferenced repos
shelf status	Show detailed status of all repos
shelf info <alias>	Show detailed info for a single repo
shelf pin <alias> <ref>	Pin a repo to a branch, tag, or commit
shelf alias <old> <new>	Rename a repo alias
shelf daemon start	Start background sync daemon
shelf daemon stop	Stop the daemon
shelf daemon status	Show daemon status

Adding Repos

You can add repos by name — no full URL required:

shelf add react              # resolves from built-in registry
shelf add Effect-TS/effect   # resolves owner/repo to GitHub
shelf add https://github.com/org/repo.git  # full URL

Shelffile

A shelffile is a per-project manifest declaring which reference repos the project needs:

# one repo per line: alias url [pin:type:value]
effect https://github.com/Effect-TS/effect.git pin:branch:main
react https://github.com/facebook/react.git pin:tag:v19.0.0

Run shelf install in a project directory to clone all repos from its shelffile. Run shelf share to generate a shelffile from your current repos. Run shelf detect --format shelffile to auto-generate from project dependencies.

Tips

• Pin versions for reproducibility. If the user's project depends on React 19, pin the reference repo to v19.0.0 so the code you read matches what they're actually using.
• Update before deep dives. If you're about to do extensive research in a repo, run shelf update {alias} first to make sure you're reading the latest code (unless pinned).
• Combine with project code. You can cross-reference between the user's project files and shelf repos to trace how dependencies are used — e.g., find a function signature in the shelf repo, then grep the user's project for call sites.