BitPub Integrations — one install, every agent learns it

01 CC Claude Code Native skill · gold standard

Claude Code

Claude Code reads SKILL.md files from ~/.claude/skills/ automatically. The universal install already dropped the BitPub skill there. Restart Claude Code and the next time you mention saving context, remembering decisions, or restoring a session, the agent shells out to bitpub natively.

Why native skills, not MCP? Claude Code already has a shell tool — calling bitpub save directly is faster, streams stderr, and survives across versions. The skill describes when to use BitPub (long sessions, multi-agent handoffs, persistent memory) and how. No tool registration, no JSON-RPC envelope, no per-project config.

              terminal · verify the skill landed
              bash
              
            
$ bitpub skills list
  BitPub skill installation status:
 
  [✓] Claude Code (user)         ~/.claude/skills/bitpub/SKILL.md
  [✓] Cursor (user)              ~/.cursor/skills-cursor/bitpub/SKILL.md
  [✓] Codex (user)               ~/.codex/skills/bitpub/SKILL.md
  [✓] AGENTS.md (project)        ./AGENTS.md

Where the skill landed

~/.claude/skills/bitpub/SKILL.md

Project-scoped also works: ./.claude/skills/bitpub/SKILL.md (auto-installed if the dir exists).

Smoke test

Save a checkpoint of what we discussed so a fresh Claude session can pick it up later — call it session-handoff.

The skill ships with two recommended slash-commands you can wire into Claude Code if you want them: /catch-up and /save-checkpoint. They're optional — the agent will still use bitpub natively without them.

02 C Cursor Native skill · gold standard

Cursor

Cursor's agent reads SKILL.md files from ~/.cursor/skills-cursor/. After the universal install, the BitPub skill is in place — Composer, Agent mode, and CLI agents all see it. Reload the window (Cmd+Shift+P → Reload Window) and shared memory is on.

Why native skills, not MCP? Cursor agents already have shell access. Calling bitpub save directly is zero-overhead and the skill ships with the right framing — when to save, when to call catch-up, how to scope to group: vs private:. The ./AGENTS.md section dropped by bitpub init reinforces it project-by-project.

              ~/.cursor/skills-cursor/bitpub/SKILL.md · what Cursor sees
              markdown
            
---
name: bitpub
description: Persistent shared memory across agents and sessions.
              Use when saving findings, restoring context, or
              handing off between sessions/agents.
---
 
# BitPub
 
Use the `bitpub` CLI for persistent memory across sessions:
 
- `bitpub save <name> <value>`  · save a slice to your private namespace
- `bitpub load <name>`         · read a slice back
- `bitpub recent`              · list recent slices in this workspace
- `bitpub catch-up`            · bootstrap context on a fresh session
 
When to use BitPub: long-running tasks, multi-agent handoffs, …

Where the skill landed

~/.cursor/skills-cursor/bitpub/SKILL.md

Reinforced per-project by ./AGENTS.md. Cursor reads both on session start.

Smoke test

Save a note about the BitPub setup using bitpub, then close this window, reopen Cursor, and ask "bitpub catch-up" to recall.

Reload after install. Cursor caches skills at session start. Cmd+Shift+P → Reload Window (or restart) is enough — no further config. If you'd rather expose BitPub as MCP tool buttons in Composer, see the MCP escape hatch.

03 $ Codex CLI Native skill + AGENTS.md

Codex CLI

Codex picks up BitPub through two channels: the user-level skill at ~/.codex/skills/bitpub/SKILL.md (auto-discovered every session) and the project-level ./AGENTS.md section that bitpub init writes. Either alone is enough — together they cover every working directory.

Codex pioneered AGENTS.md. Every Codex session reads AGENTS.md from the cwd up to the repo root. The BitPub block teaches Codex about bitpub save / load / recent / catch-up in plain prose — no tool registration, no MCP runtime. The skill at ~/.codex/skills/ covers the case where you're working outside an BitPub-aware repo.

              ./AGENTS.md · the section bitpub init wrote
              markdown
            
# AGENTS.md
 
## BitPub
 
This workspace is wired to BitPub. Use the `bitpub` CLI to
save findings, restore context, and hand off between sessions:
 
- `bitpub save <name> <value>` — save a slice (encrypted, private)
- `bitpub load <name>`        — read a slice back
- `bitpub recent`             — list recent slices in this workspace
- `bitpub catch-up`           — bootstrap context on a fresh session
 
For the full skill: `~/.claude/skills/bitpub/SKILL.md` (or run
`bitpub skills install`).

Where the skill landed

~/.codex/skills/bitpub/SKILL.md

Plus per-project ./AGENTS.md. Codex reads both — closest match wins for instructions, the skill provides the deep reference.

Smoke test

Save the design decisions from this session to a bitpub slice called arch-decisions so the next Codex run can reference them.

AGENTS.md is the cross-agent convention. Codex, Cursor, Windsurf, Continue, and Gemini all read it. BitPub is the only memory layer that drops a section into AGENTS.md automatically per workspace — your agent finds it on the first ls.

04 ✦ Gemini CLI Shell + AGENTS.md

Gemini CLI

Gemini CLI runs shell commands directly. Once bitpub is on $PATH, the agent can bitpub save, bitpub load, bitpub recent, and bitpub catch-up — no skill registration, no MCP. The AGENTS.md section dropped by bitpub init tells Gemini when to use it.

No MCP gold standard for Gemini today. The agent's strongest lever is its shell tool — and shell + a clear AGENTS.md instruction is faster, easier to debug, and survives Gemini version bumps. If your team uses GEMINI.md, copy the same BitPub block there too.

              gemini · sample interaction
              terminal
            
> save the architecture notes to a bitpub slice called architecture
 
  Reading AGENTS.md … found BitPub section.
  I'll save the notes via the bitpub CLI.
 
  ▶ shell: bitpub save architecture --stdin
  ✓ wrote bitpub://private:agent_h7q2x9k4m1nz/Workspaces/my-app/architecture (v1)
 
  Saved. Use `bitpub load architecture` or `bitpub recent` to recall.

Instructions live in

./AGENTS.md

For machine-wide reach, copy the section into ~/.gemini/GEMINI.md. Gemini reads both.

Smoke test

Save the architecture you've inferred from this codebase to a bitpub slice called architecture. Then run bitpub recent to confirm.

Tip: If Gemini ignores AGENTS.md in your version, prepend an explicit hint to your prompt: "You have a CLI called bitpub installed; consult ./AGENTS.md for usage." The skill content takes over from there.

05 W Windsurf Shell + AGENTS.md

Windsurf

Cascade reads AGENTS.md on session start and can run shell commands through its tool calling. After the universal install, the BitPub block is in ./AGENTS.md — Cascade discovers it and shells out to bitpub directly. Same path as Gemini CLI; same single source of truth.

Why not MCP? Windsurf has experimental MCP support, but Cascade reading AGENTS.md + shelling to bitpub is more robust today — fewer moving parts, no per-host JSON to maintain, and the same instructions that the rest of your toolchain (Codex, Cursor, Gemini) reads. One file, every agent.

              terminal · confirm Cascade can see the block
              bash
              
            
$ grep -A 10 "BitPub" AGENTS.md
  ## BitPub
 
  This workspace is wired to BitPub. Use the `bitpub` CLI to
  save findings, restore context, and hand off between sessions:
 
  - `bitpub save <name> <value>` — save a slice (encrypted, private)
  - `bitpub load <name>`        — read a slice back
  - `bitpub recent`             — list recent slices in this workspace
  - `bitpub catch-up`           — bootstrap context on a fresh session

Instructions live in

./AGENTS.md

Optional Cascade rules: .windsurf/rules/bitpub.md — mirror the same BitPub block if you want it pinned even when AGENTS.md is missing.

Smoke test

Drop your in-progress refactor plan into a bitpub slice called refactor-plan so the next Cascade session can pick it up.

Windsurf reads AGENTS.md at session start; close and reopen Cascade after a fresh bitpub init so the new instructions take. The skill itself reaches Cursor / Codex / Claude Code via bitpub skills install — Windsurf piggybacks on the cross-agent file.

06 ▶ Continue.dev Shell + rule

Continue.dev

Continue can invoke shell commands and reads project rules. Wire BitPub by adding a one-line rule that points at ./AGENTS.md (which already has the BitPub block). Continue then uses bitpub from its shell tool — no MCP process to manage.

Continue's rule system loads context-aware system prompts. The AGENTS.md section that bitpub init wrote can be referenced from a rule, or you can copy it directly into .continue/rules/. Either way, Continue knows about bitpub on every session — no MCP runtime needed.

              ./.continue/rules/bitpub.md
              markdown
              
            
---
description: Use BitPub for persistent shared memory across sessions
---
 
This workspace has BitPub installed. Use the `bitpub` CLI for
persistent memory: `bitpub save <name> <value>`, `bitpub load <name>`,
`bitpub recent`, and `bitpub catch-up`.
 
Full instructions live in ./AGENTS.md (## BitPub).

Rule lives in

./.continue/rules/bitpub.md

Or for global use: ~/.continue/rules/bitpub.md. Continue merges global + project rules at session start.

Smoke test

Save a snapshot of this chat with bitpub save, then close Continue and reopen — ask "bitpub catch-up" to restore the thread.

Continue has MCP support for tool invocation, but the rule-based path doesn't require any extra process to manage. Skip MCP unless you specifically need tool buttons in the Continue UI — see the escape hatch.

07 CW Claude Cowork MCP · gold standard here

Claude Cowork

Cowork is Claude's desktop agentic mode — its tool surface is what the host exposes, not arbitrary shell commands. That makes MCP the right path here: drop the JSON below into claude_desktop_config.json and Cowork surfaces bitpub_save, bitpub_load, etc. as native tools.

Why MCP for Cowork and not the others? Cowork is a GUI agent without a shell tool. To extend its capabilities you have to register MCP servers — that's the only mechanism. Everywhere else (CLI agents that can shell out), skill files + AGENTS.md is leaner. Here, MCP earns its place.

              claude_desktop_config.json
              JSON
              
            
{
  "mcpServers": {
    "bitpub": {
      "command": "npx",
      "args": ["-y", "@bitpub/smp", "bitpub-mcp"]
    }
  }
}

Config lives in

~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json · or Settings → Developer → Edit Config in the desktop app.

Smoke test

Use bitpub_save to drop today's research findings into a slice called research-q3 so the rest of my agents can read it.

Cowork's superpower is local-file work; BitPub's is addressable persistence. They compose: Cowork synthesizes a long doc, drops it at bitpub://private:<you>/Briefs/Q3-launch, and tomorrow's Claude Code session pulls it by address. Same brief, different surface.

08 </> Build-your-own SDK · CLI · MCP

Building your own agent? Use the SDK directly.

Custom agent runner, eval harness, or backend job? Skip skills and MCP — import the SDK or shell to bitpub directly. Same auto-bootstrap, same private namespace, same SQLite cache. All three call shapes share ~/.bitpub/config.json and ~/.bitpub/cache.db so a slice written from one is instantly visible to the others.

              JavaScript / TypeScript · /bitpub
              js
              
            
import { BitPub } from "@bitpub/smp";
 
const tb = new BitPub();   // auto-provisions on first call
 
await tb.save("setup-test", "raw SDK works");
const recent = await tb.recent({ limit: 5 });
console.log(recent);

              Python · sdk/python/bitpub.py
              python
              
            
from bitpub import save, load, recent
 
save("setup-test", "raw SDK works")
print(load("setup-test"))        # → "raw SDK works"
print(recent(limit=5))           # → list of slices

Install

npm install @bitpub/smp

Python: pip install bitpub · CLI: curl -fsSL bitpub.io/install.sh | bash

No-MCP smoke test

From the CLI: bitpub save setup-test "raw". From the SDK: same call shape, same auto-bootstrap, same ~/.bitpub/config.json. Slices written from any tier are visible to all the others.

The four call shapes (CLI, JS, Python, MCP) are interchangeable — Claude Code writing a slice via the CLI is instantly readable by a Python eval script via the SDK, and vice versa. They all share the same on-disk cache and config.

MCP escape hatch

Need MCP instead of skills?

If your host is GUI-only, can't run shell commands, or your team is standardized on MCP for tool-button UX, the MCP server ships in the same npm package. npx downloads / on first run, caches it, and starts bitpub-mcp over stdio — same auto-bootstrap, same private namespace.

                universal MCP config (works for Cursor, Claude Code, Cowork, Codex, Gemini, Windsurf, Continue, …)
                JSON
                
              
{
  "mcpServers": {
    "bitpub": {
      "command": "npx",
      "args": ["-y", "@bitpub/smp", "bitpub-mcp"]
    }
  }
}

Drop into ~/.cursor/mcp.json, ~/.claude.json, claude_desktop_config.json, ~/.codex/config.toml (TOML form: [mcp_servers.bitpub]), ~/.gemini/settings.json, ~/.codeium/windsurf/mcp_config.json, or .continue/mcpServers/bitpub.json — same JSON, every host. But: for everything except Claude Cowork, the agent-native install above is leaner.

One install. Every agent learns BitPub.

The universal install.

Install the CLI

Initialize a workspace

Distribute the skill

Claude Code

Cursor

Codex CLI

Gemini CLI

Windsurf

Continue.dev

Claude Cowork

Building your own agent? Use the SDK directly.

Need MCP instead of skills?

Three commands. Every agent.