wiki-agent

wiki-agent turns an nb notebook into an agent-maintained personal wiki. It installs the agent instructions, Markdown templates, lint hooks, shell wrapper, and tooling config needed for Pi, Claude Code, Cursor, or OpenCode to maintain notes safely.

The package deliberately does not manage model selection or API keys. Your coding-agent harness owns authentication and model settings; wiki-agent only configures the wiki workflow.

Prerequisites

• Node.js 22+
• nb — npm install -g nb (the setup wizard will offer to install it if missing)

By default, setup creates a single nb notebook rooted at ~/.nb/home:

~/.nb/
├── home/
│   ├── journal/
│   ├── finance/
│   ├── projects/
│   └── reference/
├── hooks/
│   └── lint.sh
├── node_modules/       (markdownlint-cli2, prettier)
├── .markdownlint.json
├── .prettierrc
├── package.json
└── <agent context file>

It does not create peer notebooks like ~/.nb/journal. All note-type folders live under the single home notebook so one nb sync can back up the whole wiki.

Install

npx @justestif/wiki-agent setup

Pi users can also install the package because package.json includes the pi-package keyword and a Pi manifest:

pi install npm:@justestif/wiki-agent

Setup wizard

The interactive setup asks for:

1. Coding agent: Pi, Claude Code, Cursor, or OpenCode
2. Notebook backend: nb
3. Wiki location, defaulting to ~/.nb
4. Starter note folders: journal, finance, projects, reference, plus custom folders

After setup, wiki-agent:

• creates the single home notebook folder structure
• writes the correct context file for the selected agent
• installs the agent lint hook adapter
• copies starter Markdown templates
• writes markdownlint and Prettier config
• writes a package.json with lint dependencies and runs npm install
• installs a wiki shell helper

Dry run

Preview generated files without writing to disk:

npx @justestif/wiki-agent dry-run

Shell wrapper behavior

The generated wiki helper behaves as follows:

• wiki with no arguments opens the selected agent in the wiki directory.
• wiki <native-nb-command> ... passes through directly to nb.
• Any other arguments are sent as a single-shot agent prompt from the wiki directory.

For Bash and Zsh, setup writes the wrapper under ~/.local/lib/wiki-agent/ and sources it from the shell rc file. For Fish, setup writes the function file under ~/.config/fish/functions/.

Metadata and linting

wiki-agent relies on nb-native features: tags, links, selectors, bookmarks, todos, search, move/rename, sync, and git-backed history. It does not generate a separate index or log by default.

The shared hook core is hooks/lint.sh. Agent-specific hook adapters call it with edited Markdown files. Linting uses npx to resolve markdownlint-cli2 and prettier from the local node_modules installed during setup. It runs:

markdownlint-cli2 <files>
prettier --check <files>

Violations produce a non-zero exit code so blocking hook systems can ask the agent to fix the files before finishing.

Agent backends

| Backend | Context file | Hook adapter | | ----------- | -------------- | ------------------------------------------------ | | Pi | AGENTS.md | .pi/extensions/wiki-lint.ts | | Claude Code | CLAUDE.md | .claude/settings.json + hooks/claude-hook.sh | | Cursor | .cursorrules | .cursor/hooks.json + hooks/cursor-hook.sh | | OpenCode | AGENTS.md | .opencode/plugins/wiki-lint.ts |

Model selection and authentication stay with the selected coding agent (/model, /login, auth, or /connect flows depending on the harness). wiki-agent does not ask for API keys, check model availability, or write model settings.

The hook adapters are intentionally small wrappers around the shared lint script. Before publishing a release, verify each harness API against current upstream docs because hook and extension APIs can change quickly.

Development

npm run check

This runs formatting, ESLint, strict TypeScript checking, secret checks, and the build.