shelf

A global cache of code reference repositories for AI agents

Install

bun install -g @rikalabs/shelf

Quick Start

# Setup agent + auto-detect project repos
shelf init
shelf init --agent claude

# Add repos by name, owner/repo, or URL
shelf add react
shelf add Effect-TS/effect
shelf add https://github.com/vercel/next.js.git --pin tag:v15.0.0

# Or use a shelffile for your project
shelf install

# Detect repos from package.json / go.mod
shelf detect
shelf detect --apply

# Keep repos fresh in the background
shelf daemon start

Agents read repos directly at ~/.agents/shelf/repos/{alias}/ using their native tools.

How It Works

┌──────────────┐       ┌──────────────┐       ┌──────────────────────────┐
│  shelf add   │──────▶│  Git Clone   │──────▶│ ~/.agents/shelf/repos/   │
│  shelffile   │       │  (shallow)   │       │   effect/                │
│  + install   │       │              │       │   react/                 │
└──────────────┘       └──────────────┘       │   ...                    │
                                              └────────────┬─────────────┘
                                                           │
                                              ┌────────────▼─────────────┐
                                              │  Agent reads directly    │
                                              │  Grep, Read, Glob, ls   │
                                              └──────────────────────────┘

Shelf manages the lifecycle — clone, pin, sync, remove. Your agent uses its own tools to explore the code. Clones are shallow by default (--depth 1, --single-branch) since repos are for code reference, not building.

Docs

• Commands — full command reference
• Shelffile — per-project repo manifests and garbage collection
• Agent Integration — setting up skill files for your agent

Development

bun test                 # run tests
bunx --bun tsc --noEmit  # typecheck

License

MIT