Context Shelf

Get started

A book groups the evidence for one piece of work: a question, an investigation, a project, or a decision. Start small. A schema, a query, and an error are enough to make a useful book.

1. Open Context Shelf. Find its small resting indicator at the top of the screen.
2. Create a book with a title that describes what you are working on.
3. Capture a useful excerpt. Copy text from another app and add it from the clipboard, or add a file or screenshot.
4. Inspect the capture. Give it a useful title and check its source metadata.
5. Copy context when you are ready to continue in an AI conversation.

Try the built-in example from the empty shelf to explore a database investigation, or create your own book and add your first clip.

Using the app

Keyboard shortcuts#

Click the menu-bar book icon to open the shelf. Right-click it for capture commands and Add files…. In a book, use Add clip for pasted text, clipboard, selection, screenshot, or file capture.

Capture and review#

Explicit captures give you control over what enters the shelf. Check the destination book, correct misplaced items, and edit your working context before a handoff. Capture an assistant’s useful response back into the same book to keep the next conversation grounded.

File capture accepts files up to 25 MB. Images retain their original attachment and use local OCR to make visible text searchable and useful in context. Cancelling screenshot selection adds no clip and returns a brief status message.

Automatic grouping#

Routing is a suggestion based on the content and available book context. An explicitly selected destination takes priority. Review the result: similarly named projects or repeated technical terms can create ambiguous matches.

Handoff preview and export#

Choose Build context to prepare a draft. Use Edit to record your own findings. Building context again replaces that working draft, so preserve edits you want to retain. The book menu offers Preview handoff, Export Markdown, and Export book folder. Edit the handoff preview to tailor the next conversation: both Copy context and Export Markdown use that edited preview. Export a book folder when you need the original attachments to travel with it.

What to include#

Keep your current objective, accepted findings, open questions, and supporting excerpts. Review the exported text before pasting it into another tool. A destination assistant receives only what you provide to it.

Read the complete UX brief →

CLI & MCP

The shelf executable gives scripts and AI harnesses access to the same local collection. The GUI and command line share the core persistence layer.

"/Applications/Context Shelf.app/Contents/MacOS/shelf" help
"/Applications/Context Shelf.app/Contents/MacOS/shelf" status
"/Applications/Context Shelf.app/Contents/MacOS/shelf" list

Capture and export#

For shorter commands, set a shell variable to the bundled executable. Replace the example IDs with IDs returned by your collection.

SHELF="/Applications/Context Shelf.app/Contents/MacOS/shelf"
"$SHELF" create --title "Database investigation"
"$SHELF" capture --text "customers: id, created_at, status" \
  --book BOOK_ID --title "Customer schema" \
  --source-app "Safari" --source-url "https://example.com/schema"
"$SHELF" show BOOK_ID
"$SHELF" update BOOK_ID --context "Check unmatched customer rows."
"$SHELF" export BOOK_ID --format markdown

Use capture --file PATH to import a file or capture --stdin for piped text. Set --unfiled to capture without a book. Correct a destination with move CLIP_ID --book BOOK_ID. delete BOOK_ID removes the book and moves its clips to unfiled.

Use the installed executable’s help output as the authoritative command reference for your build. Data command output is JSON, except Markdown export; failures use a nonzero exit status and an actionable error message.

Portable export and synthesis#

"$SHELF" export BOOK_ID --bundle-dir "$HOME/Desktop"
"$SHELF" synthesize BOOK_ID

A bundle creates a new folder containing context.md, book.json, and attachments/. Attachment links are relative so the whole folder can move to another device. Existing exports are preserved. --bundle-dir cannot be combined with --format.

synthesize explicitly rebuilds working context using local extractive excerpts and replaces edited context. Use it only when that replacement is wanted. MCP supports text capture; use CLI --file for attachments and --bundle-dir for portable exports. File imports are limited to 25 MB.

MCP over standard input/output#

Start the MCP server as a child process of your harness. It communicates through newline-delimited JSON-RPC on standard input/output and does not open a network listener.

{
  "mcpServers": {
    "context-shelf": {
      "command": "/Applications/Context Shelf.app/Contents/MacOS/shelf",
      "args": ["mcp"]
    }
  }
}

Available tools are shelf_list, shelf_show, shelf_create, shelf_capture, shelf_move, shelf_update, shelf_export, and shelf_synthesize. Tool arguments use names such as book_id, clip_id, source_app, and source_url.

Use MCP tool discovery to inspect the exact available tools and argument schemas. Only connect a harness you intend to give access to your context books. A connected harness can read sensitive captured content and may modify the collection through exposed tools.

Isolated collections#

CONTEXT_SHELF_HOME=/tmp/context-shelf-example \
  "/Applications/Context Shelf.app/Contents/MacOS/shelf" status

Set CONTEXT_SHELF_HOME consistently for every process that should share an isolated collection. Use a temporary collection for tests and demonstrations.

Architecture

Storage#

The normal collection lives under ~/Library/Application Support/ContextShelf. CONTEXT_SHELF_HOME overrides that location. Treat the whole collection directory as private data and include it in your backup policy. Collection directories use mode 700 and files mode 600.

Persistence contract#

shelf.json stores schema version 1 as readable JSON with ISO 8601 timestamps. Imported attachments live under attachments/. Read-modify-write transactions use a POSIX flock on .shelf.lock, followed by atomic JSON replacement. Corrupt data and unknown schema versions produce an error instead of silently starting a blank collection. There is no migration from an earlier schema in this initial version.

Deleting a book preserves its clips in unfiled. Deleting a clip removes its record but retains attachment bytes; this version does not garbage-collect unused attachments. Back up the complete directory, including attachments, rather than only the JSON file.

Routing contract#

Routing compares distinctive words and source URL hosts against books. A candidate needs a score of at least 0.60, three shared distinctive terms, and a lead of at least 0.15 over the next match. The source-host bonus is 0.05. These are heuristic scores, not probabilities. Ambiguous captures go to unfiled. An explicitly chosen book overrides inference. This is a deterministic lexical heuristic, so it can miss semantic relationships that do not share vocabulary.

Context generation#

The implementation can use Apple Foundation Models locally when available. Availability depends on the Mac and system configuration. An explicit extractive fallback keeps the utility usable without a model. No remote model API key is required.

The shared core provides an extractive synthesis of clip titles and excerpts, labeled with contextOrigin: "extractive". Exports include the objective, working context, original clips, provenance, and attachment references. Markdown-only export uses absolute local attachment links. Use a portable book folder to include the originals and relative links.

Generated context is an aid to review. It can omit important details or misinterpret evidence. Original clips remain the basis for checking a handoff.

Data contracts#

The source definitions in Sources/ShelfCore are authoritative for the installed version’s stored fields and schema handling. Agents should use the CLI or MCP instead of directly rewriting storage files.

Privacy

The collection is stored locally. Captured text, screenshots, and files can contain personal information, credentials, or internal work. Review a book before exporting it to another assistant.

• Clipboard history is opt-in. Explicit clipboard capture is the starting workflow.
• App access depends on the action. Selected-text capture requires your first-use Accessibility opt-in. Screenshot capture requires your Screen Recording opt-in; allow it in macOS and capture again. Clipboard capture works without Accessibility.
• Source information has limits. Unknown clipboard origin is labeled Clipboard; the app does not invent a source app. Selected-text capture can record an app, while precise URLs or document paths may still be unavailable. Supply missing provenance when it matters.
• Exports leave the shelf under your control. The receiving app’s privacy and retention rules apply after you paste or attach material there.

The app does not call a remote model service. Running a third-party AI harness against the MCP server gives that harness access to tool results; its own handling of those results is outside the shelf.

Development

Use macOS 26 or later and an Xcode toolchain supporting the package’s Swift version. From the repository root:

swift test
./script/build_and_run.sh
./script/build_and_run.sh --install

The build script stages dist/Context Shelf.app. Installation places the app at /Applications/Context Shelf.app. Consult the script for the current build and signing behavior.

Run the source documentation site

python3 -m http.server 8765 --directory docs

Open localhost:8765. This site uses local HTML, CSS, and JavaScript; it has no CDN, analytics, or external font dependencies.

Verification snapshot#

The source documentation records the following checks; they were not rerun for this documentation redesign. 26 automated Swift tests passed (6 capture-reader OCR/file tests, 12 core tests, and 8 CLI tests), alongside real CLI/MCP subprocess checks covering ten concurrent writers, capture, updates, portable export, protocol lifecycle, and structured errors. Native computer-use checks covered the resting indicator, shelf, persistent books, source explorer, editable handoff with exact clipboard matching, clipboard routing, and screenshot-file import with local OCR and original-image retention.

Global hotkey delivery has not been verified live through computer use. Selected-text capture and interactive screen capture remain unverified end to end because first-use Accessibility and Screen Recording permissions require user opt-in. Imported screenshot OCR has been verified.

Verification expectations#

Run the Swift tests for changes to storage, routing, export, and CLI behavior. Exercise native capture, book navigation, hover behavior, keyboard access, and export with computer use when changing the interface. Use an isolated data directory and never overwrite a user’s collection to prepare a demonstration.

Contributing#

Describe the behavior you are changing and how you verified it. Preserve source evidence, keep capture fast, make automatic decisions correctable, and document the agent contract when it changes. See AGENTS.md for repository working guidance. Context Shelf is available under the MIT license.