Development docsTracks main. Use your release’s bundled docs for its exact behavior; back up your store before upgrading.

$ man bs — a shelf for work worth keeping

A home for work that outlives the session.

Notes, snippets, prompts, design docs, and handoffs—kept on your machine, shared by people and agents.

Agents let us pursue more work in parallel: more sessions, more worktrees, more repositories. bitshelf gives the work you choose to keep a common home outside any one of them—ordinary Markdown files with conventions that both you and your agents can follow.

Get started Use with agents

Know what you need? Browse the recipes →

Markdown
JSON output
No database
No daemon

zsh — ~/src

# session A, in a research worktree
api-wt $ bs add notes/pagination-research \
    --tags api --file findings.md
notes/pagination-research

# three days later, another repository
web $ bs search pagination
notes/pagination-research
web $ bs show notes/pagination-research --body
# Cursor pagination
Use opaque cursors; page size 50.
web $

Early 0.1.x releases. Back up your store before upgrading or running destructive commands. This site tracks main and may describe unreleased work; use the documentation bundled with your release for its exact contract.

The problem

Useful work now outlives the conversation that produced it—and it’s easy to lose.

01A context window is filling up, and there’s an insight worth keeping for a session you haven’t started.
02You built a nice component before realizing the task no longer needs it.
03Research done in a throwaway worktree needs to reach a session in a different one.
04Design documents should inform implementation across sessions and repositories.

bitshelf gives that work a home outside any one session. You or your agent deliberately put something on a shelf; later, from any context, either of you finds it, reads it, and builds on it. The executable is bs.

Three ideas

01 / Outlive

Information outlives the session

Keep a note, a handoff, a design doc, or a piece of code independently of the conversation, repository, or worktree it came from.

02 / Share

People and agents use the same material

A shelf is ordinary Markdown in a directory you own. You browse and edit it in your editor; agents use the same bs commands with JSON output.

03 / Shape

Each shelf has its own conventions

A shelf can describe, in plain language, how its contents should be written, updated, and found—and enforce structure such as required tags.

The loop

Keep it. Find it from somewhere else. Use it again.

Save something in one session. Days later, in another worktree or repository, find it, read it, and build on it rather than duplicating it. The second use is the payoff.

With the agent skill installed, the same loop is a request:

session A“save these pagination findings to bs”

session B“check bs for our pagination research”

Walk through the loop →

Deliberate, not automatic memory

Nothing is saved unless you, or an agent you asked, saves it. Nothing is loaded into a conversation unless it’s looked up. Agents disclose the store to themselves progressively:

1
bs shelf list
Discover which shelves exist and what each is for.
2
bs context SHELF
Load a shelf’s guidance only when it’s relevant.
3
bs search QUERY
Find candidates by ID, title, tags, and body.
4
bs show ID
Read just the bits that were chosen.

You stay in control of what’s kept, and what’s kept stays inspectable.

Why not just a folder of Markdown?

It is a folder of Markdown.

Browse it, grep it, back it up, or commit it to Git, with or without bs. No account, database, or background service. What bs adds is what makes that folder dependable for both people and agents.

~/bitshelf

~/bitshelf/
├── notes/
│   ├── bs.toml         # settings
│   └── bits/
│       └── pagination-research.md
└── handoffs/
    ├── bs.toml
    ├── SHELF.md        # conventions
    └── bits/
        └── docs-rewrite.md

Conventions agents actually load: bs context hands an agent a shelf’s full guidance and requirements before it writes.
Structure that’s checked: Shelves can require titles or tags and restrict tag values, for example to known repository names. Invalid saves are rejected.
Stable identifiers and JSON: Every bit is shelf/name, and store commands have structured JSON output for agents and scripts.
Exact content: Prompts and code are stored byte-for-byte; metadata lives in frontmatter.
Discovery you control: An archive shelf can stay out of default results while remaining accessible.

Recipes

Shape shelves around the work you repeat.

Each recipe starts from an outcome, shows the finished experience, and separates what bs enforces from what a shelf’s conventions ask of the people and agents using it.

How agents use shelves →

StartGet started→AgentsUsing with agents→InstallInstall bs→ReferenceBehavior and limits→