nb-agent

nb-native, agent-assisted personal wiki.

One command: npx @justestif/nb-agent setup. Seeds WIKI.md, installs wiki.nb-plugin, wires agent prompt command into nb ask.

E2E tested with: Pi (pi -p) · Claude Code (claude -p) · OpenCode (opencode run)

Prerequisites

• Node.js 22+
• nb — npm install -g nb (setup installs it if missing)

Install

npx @justestif/nb-agent setup

Pi package discovery:

pi install npm:@justestif/nb-agent

Commands

| Command | What it does | | ---------------------------------------- | --------------------------------------------------- | | nb journal "Met Sam about budget" | Timestamped note, auto-filed by type | | nb ask "What did I decide about sync?" | Prompt agent with WIKI.md context | | nb distill home --days 60 | Extract key facts from old notes, archive originals |

wiki shell helper = NB_DIR-scoped nb shortcut:

wiki journal "quick note"
wiki ask "what changed?"
wiki distill home --days 60

Wiki structure

~/.nb/
├── home/                    (nb notebook — one git repo, nb sync)
│   ├── journal/
│   ├── finance/
│   ├── projects/
│   └── reference/
├── archive/                 (distilled notes)
│   └── home/2026-04/
├── WIKI.md                  (working memory for nb ask)
├── wiki.json                (note types, agent prompt command, distill config)
├── node_modules/            (markdownlint-cli2, prettier)
├── .markdownlint.json
├── .prettierrc
└── package.json

Supported agents

| Agent | chatCmd | promptCmd | | ----------- | ---------- | -------------- | | Pi | pi | pi -p | | Claude Code | claude | claude -p | | OpenCode | opencode | opencode run | | Cursor | cursor . | cursor . |

Wizard writes chosen promptCmd to wiki.json. Plugin reads it at runtime.

Working memory (WIKI.md)

nb ask includes WIKI.md in agent prompt for persistent context.

Sections: Identity · Structure · Active context · Known facts · Preferences · Changelog

Setup wizard

1. Agent — Pi, Claude Code, OpenCode, or Cursor
2. Wiki location — default ~/.nb
3. Note folders — journal, finance, projects, reference, plus custom
4. Distillation — enable/disable, age threshold (default 30 days)

Distillation

nb distill                   # current notebook, default threshold
nb distill home --days 60    # notes older than 60 days
nb distill home --batch 20   # 20 notes per batch

Flow: list old notes → batch read → prompt agent → append to _digest.md → move originals to archive/ → nb sync.

Linting

nb journal runs background Markdown maintenance:

nb run npx markdownlint-cli2 --fix <note>
nb run npx prettier --write <note>
nb sync

Dry run

Preview generated files without writing:

npx @justestif/nb-agent dry-run

Development

npm run check   # format + lint + typecheck + secrets + build