jotbook

Easily build a knowledge base every time you ask Claude to explain what it built.

If you're a vibe coder, your agent is almost certainly shipping code you don't fully understand. If you're a responsible vibe coder, you ask it to explain what it just built so you actually learn something. Jotbook is for the responsible vibe coder.

The problem: The best explanations arrive while you're working on something, when stopping to save them would derail you, so they evaporate. Jotbook catches them without breaking your flow: jot down a cheap pointer in the moment, review the backlog later for what's still worth keeping, ink the survivors into finished long-form entries.

The trick: Claude stages these jots itself the moment it finishes explaining something. You work, the record writes itself.

How it works

Want to get a quick sense of how it works? run `/jotbook-pencil how-jotbook-works`

  ┌──────────┐     ┌──────────┐     ┌──────────┐
  │   jot    │ ──▶ │  review  │ ──▶ │   ink    │
  └──────────┘     └──────────┘     └──────────┘
   lightweight      consolidate /     inked entry
   pointer file     drop / tweak      in the jotbook

• Jot is cheap: a one-line pointer file with today's date and (optionally) the files the explainer referenced. Use it freely — most won't survive.
• Review is curation: list the backlog, propose merges, drop the dead weight, tweak framings, mark the survivors.
• Ink is the actual writeup: read the referenced files, reconstruct the explanation, produce a finished entry. Markdown by default; Obsidian or HTML on request.

You can drive each stage by hand with /jot, or just run /jotbook-ink for a guided session that walks review → ink in one pass.

Inking isn't just append-only. Every ink rebuilds a navigable index (index.md, or index.html in HTML mode) and gives each entry a link back to it, so the jotbook reads as a connected whole instead of a folder of files. Promoting a new entry also cross-links it into related existing entries, and /jotbook-link sweeps the whole collection on demand to connect older entries to ones inked after them. Format it as linked Markdown (default), an Obsidian vault, or templated HTML.

Install

Jotbook isn't yet published to a public Claude Code marketplace. This section will be updated when it is.

In the meantime, you can install jotbook by hosting it through your own local plugin marketplace — a directory on your machine with a .claude-plugin/marketplace.json file that points at your cloned jotbook directory. Once registered with /plugin marketplace add <path>, jotbook installs into any project via /plugin install jotbook@<your-marketplace-name>. See Anthropic's plugin marketplaces docs for the full setup walkthrough.

Quickstart

In any project, run either:

/jotbook-ink
# or, equivalently when nothing is set up yet:
/jot init

The first run detects that the plugin hasn't been initialized in this project yet and writes a starter .claude/jotbook.local.md settings file (offering to add it to your .gitignore along the way). Edit the defaults if you want; otherwise everything works out of the box. Once initialized, /jotbook-ink becomes the guided curation flow.

Then, during normal use:

Commands

Most operations have two equivalent invocation forms: the direct skill alias (/jotbook-<skill>) or via the /jot toolkit (/jot <subcommand>). Both route to the same skills; pick whichever your fingers prefer. See the namespace note below the table for why the rest of the skills use the jotbook- prefix.

Reserved words after /jot (review, ink, pencil, init, stage, template, link) are interpreted as subcommands. If you want to jot a subject that starts with one of those words, use /jot stage <subject>.

Note on Claude Code's plugin namespace: Claude Code skills surface as bare slash commands using their literal name: field — a skill named foo becomes /foo, not /jotbook:foo. That collides with built-in skills like /init and /review and with skills from other plugins. To dodge collisions, every jotbook skill except jot is manually prefixed: jotbook-init, jotbook-ink, jotbook-pencil, etc. jot itself is unique enough that we leave it bare so the toolkit dispatcher (/jot <subcommand>) reads naturally. Typing /jotbook triggers autocomplete listing every jotbook-* skill; /jot is its own thing alongside.

Pencil drafts

Sometimes you can't tell if a jot is worth inking until you read the long-form version. Pencil is an optional intermediate step: produce the full elaboration first, then evaluate it like you would a jot.

Pencils live in their own backlog (pencils_dir, default docs/jotbook/_pencils/). The source jot stays in place until the pencil resolves one way or the other.

Creating a pencil

/jot pencil <slug>            # from a jot in your backlog
/jot pencil <subject>         # from a fresh subject — stages the jot first, then drafts
/jot pencil <slug-a>,<slug-b> # consolidate multiple jots into one pencil
/jot pencil <slug> --html     # opt into the HTML template (requires template_path)

The argument doesn't have to be an existing jot. Hand it a fresh subject — something you just discussed, or a topic you want drafted now — and pencil stages the lightweight jot for you first, then drafts from it, so the pencil still has a real source jot behind it. (If the subject looks like a typo of an existing jot, it'll ask rather than create a duplicate; if there's nothing to draft from, it'll ask for material rather than invent it.)

You can also create a pencil from inside the /jotbook-ink flow: pencil <slug> is a valid decision alongside ink, drop, merge, tweak, and keep.

Reviewing pencils

/jot review pencils

Five decisions per pencil:

• Ink — promote to a finished entry. Cross-links into existing entries fire here. Pencil + source jot(s) are deleted on success.
• Drop — delete the pencil. Asks once whether to also delete the source jot(s); defaults to keeping them so you can redraft later.
• Revise — regenerate with your feedback notes. Bumps the revised: date.
• Edit — surfaces the file path; you'll hand-edit and re-run review later.
• Keep — no-op for now.

Format

Pencils render as Markdown by default regardless of output_format, since most iteration is text. Pass --html when you want to see an SVG diagram or interactive sketch before deciding whether the entry is worth keeping.

Format conversion at ink time is asymmetric — going up in fidelity is automatic, going down is opt-in:

• Markdown pencil → any `output_format` — converts to match. A Markdown pencil promoted into an HTML jotbook is rendered through your template; the inked entry is the finalized form of the draft.
• HTML pencil → Markdown/Obsidian `output_format` — kept as .html by default. Choosing HTML at draft time was deliberate (you wanted the SVG, the interactive sketch, the richer layout), so the inked entry stays HTML even though your global format is Markdown. The promotion prompt offers an explicit downcast if you actually do want it flattened to Markdown — it's lossy (diagrams become alt text, complex layouts flatten), so it stays opt-in.
• HTML pencil → HTML `output_format` — promotes directly. Any ink-time template finalization (e.g., masthead "draft" → "published") applies.

Navigation

A jotbook should be readable as a whole, not a folder you open one file at a time. Inking keeps it navigable:

• An index / landing page. Every ink rebuilds index.md (or index.html in HTML mode) in entries_dir from the entries on disk — a reverse-chronological table of contents linking every entry. It's regenerated from scratch each time, so it never drifts from what's actually there. In HTML mode it's the styled landing page (served as the directory default); in Obsidian it's a MOC of [[wikilinks]]; in plain Markdown it's an index.md you open or link to as the jotbook's front door.
• Back-to-index on every entry. Each entry opens with a small link back to the index, so you can move between an entry and the collection from anywhere.
• A within-entry Contents list. Entries long enough to warrant it (three or more sections) get a Contents block linking their own sections. Short entries stay clean — no boilerplate.
• Cross-links, two ways. Inking a new entry links it into obviously-related existing entries automatically. To reconnect the whole collection later — including linking older entries to ones inked after them — run /jotbook-link (or /jot link): it surfaces related-but-unlinked pairs and adds the links on your confirmation. It only ever adds links; it never rewrites your prose, and it always asks before editing an existing entry.

Settings

Settings live at .claude/jotbook.local.md in each project. YAML frontmatter for config, an optional markdown body for house-style guidance.

The body of the settings file (after the closing ---) is treated by jotbook-ink and jotbook-pencil as house-style guidance — voice, tone, terminology, formatting conventions. Use it for things that should shape the writeup but don't fit in a single config field.

Example:

---
jots_dir: docs/jotbook/_jots/
entries_dir: docs/jotbook/
pencils_dir: docs/jotbook/_pencils/
output_format: obsidian
backlog_threshold: 12
pencils_threshold: 3
---

# House style

Field-manual voice — restrained, precise, deadpan. No exclamation points.
Cross-link liberally; prefer wikilinks over relative paths.
Code excerpts capped at ~20 lines; longer extracts go in a sibling code block.

Output modes

markdown (default)

Plain GitHub-flavored Markdown. Sections, callouts (> [!NOTE]), tables, code blocks, relative .md links for cross-references. A trailing *Sources:* line lists the jot's referenced files.

obsidian

Markdown tuned for an Obsidian vault. Same body structure as markdown, but with:

• YAML frontmatter: tags, aliases, created, sources.
• [[wikilinks]] for cross-links between entries instead of relative paths.
• Optional inline #topic/subtopic tags where they read naturally.

Point entries_dir at a folder inside your vault and entries appear there directly.

html

Template-driven HTML for users who want a styled long-form output (zines, field manuals, internal wikis, etc.). Requires template_path to point at a real HTML file containing {{PLACEHOLDER}} tokens for the title, standfirst, sections, etc. jotbook-ink will refuse to invent a template — building one is a separate, deliberate design task.

If you'd like to build an HTML template for this mode, run /jotbook-template (or /jot template) — a guided design workflow that produces the stylesheet, a tokenized template, a preview, and house-style token docs, then wires template_path for you on sign-off.

Notion

Notion doesn't support file-based writes, so there's no notion output mode. The default markdown output is Notion-import-friendly, though — drag a finished entry into a Notion page and the structure comes through cleanly. A real Notion integration would need API access, likely as a separate plugin.

Auto-staging

Staging is driven by the jotbook-stage skill's description, which tells Claude to invoke the skill at the end of any turn where the last response was a substantive multi-paragraph explainer worth revisiting. Claude makes the judgment call in-band: after a real explainer it'll briefly narrate ("Jotted as cache-eviction-policy") and you'll see the file land under jots_dir. After a short answer, status update, or jotbook-skill output, it won't trigger.

If Claude misses something you wanted staged, run /jot [subject] explicitly. If Claude stages something you didn't want, /jot review (or /jotbook-review) lets you drop it in seconds.

For lower friction: consider adding Write(docs/jotbook/_jots/**) to your project's .claude/settings.json permissions.allow list, so the staging skill's file write doesn't prompt you each time. The plugin doesn't ship this allow rule (permissions are a per-user decision), but it's a one-line addition.

Backlog reminder

A SessionStart hook counts files in jots_dir and pencils_dir and surfaces a one-line nudge when either reaches its threshold (backlog_threshold for jots, pencils_threshold for pencils). The nudge points you at /jotbook-ink for jots and /jot review pencils for pencils. The hook is a no-op when neither threshold is met.

Restart caveat

The SessionStart hook is loaded when Claude Code starts. Editing backlog_threshold or pencils_threshold in the settings file won't take effect until you exit and restart Claude Code. The skills and commands themselves pick up settings changes immediately.

Configuration cheatsheet

License

MIT — see LICENSE.