This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Context Nest is a structured second brain for AI agents — a governed, versioned knowledge base that agents can query. It provides typed graph structure, ~100x cheaper queries (~500 tokens vs 50k), and hash-chained audit trails.
Requires Node >= 20 and pnpm >= 9. CI runs the full matrix on ubuntu/windows/macOS × Node 20/22, so cross-platform correctness matters — normalize CRLF, avoid POSIX-only path assumptions, and don't shell out to tools Windows lacks (jq, etc.).
pnpm install
pnpm build # tsup, all packages
pnpm lint # tsc --noEmit, all packages
pnpm test # vitest — unit + structural (regression suites EXCLUDED)
pnpm test:regression # builds CLI + MCP server first, then runs *.regression.test.ts
pnpm clean
# Single file / pattern / package
pnpm test packages/engine/src/__tests__/engine.test.ts
pnpm test -t "hash chain"
pnpm --filter @promptowl/contextnest-engine test
# Plugin vendoring (see "Plugins" below) — run after editing plugins/shared/
pnpm plugins:sync
pnpm plugins:check # CI guard; fails on drift
pnpm test and pnpm test:regression are separate on purpose: regression suites spawn the built dist/index.js of the CLI and MCP server against throwaway vaults, so they need a build first and are slow. Editing engine/CLI source and running only pnpm test will not exercise them.
pnpm monorepo, two workspaces of interest:
packages/ # published npm packages (engine ← cli, mcp-server)
plugins/ # coding-agent plugins that drive the ctx CLI (not published to npm)
packages/governance/ is untracked local build residue — ignore it.
@promptowl/contextnest-engine)Standalone core implementing CONTEXT_NEST_SPEC.md. Notable modules beyond the obvious CRUD:
| Module | Purpose |
|--------|---------|
| parser.ts / schemas.ts | Markdown + YAML frontmatter; Zod validation rules 1–17 (spec §13) |
| storage.ts | Vault file operations, document CRUD |
| versioning.ts / checkpoint.ts | Keyframe+diff history; nest-level atomic snapshots |
| integrity.ts / chain-log.ts | SHA-256 hash chains and their audit log |
| selector/ | lexer → parser → evaluator (+ index-evaluator for the fast path over context.yaml) |
| graph-traverser.ts / graph-query-engine.ts / wiki-graph.ts | Relationship traversal and [[wikilink]] graph |
| registry.ts | Central vault registry at ~/.contextnest/config.yaml — see resolution order below |
| source-graph.ts | Live source nodes (MCP/REST/CLI/function transports) |
| packs.ts | Saved selector bundles (pack:name) |
| suggestions.ts / approval.ts / rbac.ts / stewards.ts | Drift suggestions, approval workflow, role scoping |
| hygienist.ts / index-generator.ts / index-md-generator.ts | Vault health checks; context.yaml and INDEX.md regeneration |
| structure.ts / structure-store.ts | Structure rules (spec §11.1.1): folder patterns, allowed types, token/regex name formats (regex is a whitelist grammar matched by a linear-time position-set matcher — never hand an owner regex or token pattern to RegExp, and don't add quantified groups), templates, required sections/files. structure.ts is the pure checker; structure-store.ts holds the IO every write surface shares (enforcedStructure — only enforce: true changes a write — missingFolders/scaffoldFolders, assertStructureUpdate/assertStructureDelete; assertStructurePublish/scaffoldFirstPublish, which publishDocument(s) call so every publish is judged alike). Never re-implement these in a caller. OperationContext.structure: "skip" is for trusted hosts restoring a vault only. setStructure is the one writer — never writeConfig. Every document write — and commitNewVersion (rollback, czar edit, suggestion approval) — also calls assertWritableDocumentId (storage.ts): no .context/.versions/_suggestions segments, no root packs/, no \. Deletes and forgets (imported ones too) call only assertErasableDocumentId (so legacy ids stay erasable); writeDocument/deleteDocument back it with assertNotMachineryPath and assertResolvesOutsideMachinery (a ~digit name is judged where it resolves, never by its spelling). Grandfathering trusts only a verified head (sealedHead: rebuilt, content hashes matching); import verdicts live in api/import-verdicts.ts (importRefusals: per-file refusals, then what goes with each refused file, then structure verdicts — the executor only stages); imported .versions/ files are judged by the head the vault will hold after the import, under the imported history.yaml and the one on disk (historySetVerdict); PDF binaries are judged on the bytes on disk (none there: nothing to replace). One import's reads, hashing and replays share a budget (importReplayBudget, limits.importReplayChars) — its verdicts and its bulk publish (publishDocuments replayBudget) alike; sealedHead reads through sealedReaders one artifact at a time, each sized to the room left in the history's cap and the budget (regular files only), then hashes and replays one history at a time and yields; a document that passes the full check is never replayed (structurePublishViolations and the import verdicts check in full first, and historySetVerdict rebuilds the disk's head only when a verdict needs it); a bulk publish judges its documents in order. structureReport(storage, rules) is the compliance report for any rules — context_structure and hosts judging a draft use it. Apply a staged edit (held edit, suggestion) only through applyStagedEdit (suggestions.ts), which also checks the body it proposed, and any other patch only through applyPatchBounded (reconstruct.ts): it applies a hunk only where its header says, in order and inside the text — raw applyPatch searches every position for a hunk that does not fit, and copies up to whatever start a header claims. Judge a sealed head through sealedHeadView. Headings, sections and links use one line model (splitLines in markdown-mask.ts: CR, LF, CRLF) — never split a body on \n alone when judging it. Build what the rules judge with structureView (it carries status: a forget stub owes no sections and grants nothing as a baseline). Writers keyed by a document id call assertWritableDocumentPath before their first write. Fold a path to refuse it, compare exactly to judge or exempt it (comparableSegment, structure.ts). No regex with an unanchored x+$ on owner or caller input — trim with a loop. Every attack QA has found is a test in structure-adversarial.test.ts (engine) / structure-adversarial.regression.test.ts (MCP); an open one is it.fails with its repro — add new attacks there |
| agent-configs.ts | Generates CLAUDE.md / agent config blocks into a target project |
| semantic/ | Retrieval modes: config.ts (search: block, validated where used), providers.ts (pluggable embedder/reranker registry; OpenAI-compatible via fetch), bedrock.ts (Cohere Embed v4 / Titan v2 / Cohere Rerank 3.5 — Bedrock API key via fetch, else LAZY optional @aws-sdk/client-bedrock-runtime), embedding-store.ts (published-only index at .context/embeddings/, keyed id+version+content hash), hybrid.ts (RRF k0=60, exact title/#tag seeds pinned, rerank). Never add a mandatory provider dependency. The search: block is untrusted vault input: region must look like an AWS region, api_key_env must end in _API_KEY, and a base_url host other than api.openai.com or loopback is called only if the user lists it in CONTEXTNEST_TRUSTED_ENDPOINTS. Search uses INTERACTIVE_CALL (short retry budget); encrypted vaults refuse embed, rerank and semantic/hybrid. |
| encryption/ | Opt-in encrypted vaults (docs/encrypted-vaults.md). NestStorage is the only caller: every sensitive read/write goes through its readText/sealText helpers. Never read or write a vault content file with raw fs outside storage, or you will get ciphertext, or write plaintext into an encrypted vault |
Vault resolution (resolveVaultPath(), highest precedence first) — a frequent source of "wrong vault" bugs:--vault <alias> → CONTEXTNEST_VAULT (alias) → CONTEXTNEST_VAULT_PATH (abs path) → positional arg → local .context/config.yaml found by walking up cwd → registry default: → cwd.
@promptowl/contextnest-cli)Binaries ctx and contextnest, both from a single ~2k-line src/index.ts (commander). Command groups: document CRUD (add/update/delete/read/publish), query (query/search/resolve/list), integrity (verify/history/reconstruct/checkpoint), governance (drift stage|list|approve|reject), and multi-vault (vault add|list|remove|default|which). init scaffolds from src/starters/ — the starter prompt bodies are the agent-facing onboarding text and have their own tests.
@promptowl/contextnest-mcp-server)43 tools over stdio, in three groups:
listOperations("core") — name, description and schema all come from the engine's operation catalog, so this surface cannot drift, and a new core op appears here automatically): context_init, context_nests, context_get, context_list, context_folders, context_search, context_embed, context_query, context_resolve, context_versions, context_reconstruct, context_packs, context_verify, context_create, context_update, context_publish, context_delete, context_import, context_import_pdf, context_skill, context_skill_install, context_forget, context_forget_log, context_structure. Add new tools here, not by hand.document_format, read_index, read_pack, list_checkpoints, stage_drift_suggestion, list_suggestions, approve_suggestion, reject_suggestion, context_review (review gate — hand-written on purpose so hosted catalog bindings cannot toggle it).vault_info, resolve, read_document, list_documents, search, verify_integrity, read_version, create_document, update_document, delete_document, publish_document. Additive parity fixes are allowed here — list_documents takes path (the folder filter of context_list), create_document/update_document take description and accept content as an alias for body — but nothing already accepted may change meaning.Every tool is registered through the local tool() helper, NOT server.tool(). server.tool() takes a raw shape and wraps it in a non-strict z.object(), which STRIPS unknown keys while the JSON Schema it publishes claims additionalProperties: false: a client that misnames a parameter gets a success response for a write that silently dropped its text. tool() goes through registerTool with a .strict() ZodObject so the advertised contract is the enforced one. EngineApi.run() refuses unknown keys for the same reason, one layer down.
plugins/)Makes coding agents vault-aware (auto-retrieve) and self-maintaining (deliberate capture + consistent corrections) by shelling out to ctx. Only the Claude Code plugin is built; Codex/Gemini are README-only.
plugins/shared/ is the single source of truth. Never edit plugins/claude-code/core/ — it is a vendored byte-identical copy. Installed Claude plugins can't read files outside their own directory, so pnpm plugins:sync copies shared/core/ into each agent plugin and fills the <!-- BEGIN SHARED -->…<!-- END SHARED --> regions of agent/skill markdown from shared/prompts/.md. pnpm plugins:check fails CI on drift.
Each core/*.js module exports a pure run({ input, env, exec }) returning the hook-output object (or null to do nothing), plus a thin IO shell guarded by isMain(import.meta.url). Tests call run() with a fake exec — no subprocess. Zero runtime deps, plain Node ESM.
Config comes from env, CLAUDE_PLUGIN_OPTION_ with CONTEXTNEST_ fallbacks (so non-Claude agents can feed the same values): RETRIEVAL_MODE (off/search/query/agent, default search), CAPTURE_MODE (off/explicit/propose/auto, default explicit — only user asks, corrections and update sweeps gate; propose adds the ambient review), UNCLEAR_NEST (ask/default, default ask — what capture does when no nest clearly fits a new note), VAULT (pinned alias; may be <server>/<nest>), CTX_COMMAND (default ctx). AUTO_CAPTURE is deprecated but still read (true→propose, false→off); an explicit CAPTURE_MODE wins at any layer.
Writes are gated in code, not in prose. capture-gate.js decides whether to engage the vault (explicit intent → correction → substantive-and-out-of-cooldown, tracked per session in ~/.contextnest/plugin-state/); the prompts decide what. When changing capture behaviour, change the gate — a prompt cannot be unit-tested and the old "under-capture is the failure mode" framing is exactly what made the plugin noisy.
Hooks: SessionStart → vault overview injection (plus a compact blueprint of the pinned/working-directory vault's structure rules via ctx structure --json), UserPromptSubmit → retrieval and dispatch of any parked job, Stop → capture gate, PostToolUse (Bash) → sweep-check: after a ctx update, diff against the prior version and report every node in every registered nest still carrying the removed value (two channels: exact entity-tag lookup via ctx list --tag — agents tag nodes with the concrete values they assert and retag on edit — plus confirmed full-text search for untagged prose). The sweep-check keys on the write, not the phrasing — correctionIntent() misses declarative updates entirely, which is why it exists. Concurrent same-vault writes are serialized by a per-vault mkdir lock in the engine's mutating executors (packages/engine/src/vault-lock.ts); without it, parallel writers silently corrupt the checkpoint chain.
The Stop hook never blocks. It used to return decision: "block", which held the turn open while a subagent ran. It now parks {kind, reason, turn} in the session ledger and returns only a systemMessage; the next UserPromptSubmit drains the queue and hands the directive over as additionalContext (the field the model acts on — Stop's own additionalContext is transcript metadata it does not act on). contextnest-capture and contextnest-curator are background: true so the dispatched work overlaps the user's next request. Note saveLedger writes an explicit key projection: a new ledger field must be added to the EMPTY sentinel, the loadLedger projection and the saveLedger stringify, or it is dropped silently.
Node types: document, snippet, glossary, persona, prompt, source, tool, reference, skill, agent, artifact, table, pdf, task, view
PDF nodes (spec §1.11): body = extracted text (<!-- page N --> markers), the PDF is a binary sidecar <id>.pdf beside the .md, bound by pdf.sha256 in frontmatter (so it rides the version chain). Created only by context_import_pdf / ctx import pdf (importers/pdf.ts, unpdf); body edits are refused; prior binaries are archived as .versions/<doc>/<sha256-hex>.pdf; verifyPdfSidecars reports sidecar_drift/sidecar_missing; delete removes the sidecar.
Statuses: draft, pending_review, approved, published, rejected, forgotten (set only by ctx forget; spec §6.3 — erased content, hashes kept, anti-resurrection via .versions/chain_events.yaml; ctx delete only appends an audit-only record). Parse-time aliasing normalizes legacy/foreign values (case-insensitive; unknown → draft); disk always stores canonical values, re-canonicalized on round-trip through serializeDocument or ctx index.
Selector grammar: #tag, type:document, status:published, pack:onboarding.basics, nodes/<id> / sources/<id> (a bare node id — shorthand for contextnest://nodes/<id>), with a space or + (AND), | (OR), - (NOT), and ( ) to group. The one canonical line is SELECTOR_GRAMMAR in packages/engine/src/selector/grammar.ts; every surface that teaches the grammar renders it verbatim, so change it there and nowhere else.
URI scheme: contextnest://path, @N (pinned to checkpoint N), #section.
Version model: keyframe + diff (keyframe every 10 versions by default), SHA-256 hash-chained for both document versions and nest checkpoints.
Every PR — human- or AI-authored — must have both of these, or the Claude review marks it 🔴 blocking (full rules in REVIEW.md):
Task: https://nest.promptowl.ai/nest/<nest-id>?doc=nodes/projects/<stage>/<task-slug>; tasks live in the po-engineering-ops nest), or a ClickUp ticket in the title, body or branch name (CU-<id>, [CU-<id>], #<id>, or an app.clickup.com/t/<id> link). If you don't know the task, ask — don't open the PR without it.N/A — no user-facing change plus a reason only for docs/CI/chore PRs.Changesets. pnpm version-packages (changeset version + lockfile refresh), then pnpm release. All three packages are AGPL-3.0 and versioned together. CONTEXT_NEST_SPEC.md is the one exception in the repo: Apache-2.0, per LICENSE-SPEC.
CONTEXT_NEST_SPEC.md is normative — §1 document format, §2 selectors, §3 packs, §4 URI scheme, §5 context.yaml, §6–8 versions/checkpoints/integrity, §9 injection & tracing, §10 INDEX.md, §13 validation rules.
Weekly roundup of top Claude Code skills, MCP servers, and AI coding tips.