pdfnative-mcp
CLAUDE.md2 starsChanged 56 days agoMITView on GitHub
Everything in AGENTS.md applies. This file adds only what is specific to Claude Code sessions in this repository. - Run tests through npx tsx scripts/gate.ts --fast or npx vitest run <file> (the dot reporter is configured); never paste a full test run into context. - Never Read dist/, coverage/, test-output/, package-lock.json, node_modules/, .clusterfuzzlite/engine/package-lock.json, .audit/. The deny list in .claude/settings.json applies to Read and, at best effort, to Grep/Glob — ask the built server (tools/list, prompts/get) instead of reading dist/; npm…
- Commits and pushes
In this repository4 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .github/copilot-instructions.mdCopilot instructions
- llms.txtllms.txt
- release-auditSkill
The file
We split this CLAUDE.md into the rules it gives an agent
8 rules. About 0 are common, 0 are distinctive, and 8 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
8
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Very specific: line 9
Run tests through npx tsx scripts/gate.ts --fast or npx vitest run <file> (the dot reporter is configured).
- Very specific: line 10
Never Read dist/, coverage/, test-output/, package-lock.json, node_modules/, .clusterfuzzlite/engine/package-lock.json, .audit/.
- Very specific: line 14
Read README.md, ROADMAP.md, docs/KNOWLEDGE_BASE.md and docs/AGENT_CONTRACT.md by section: grep -n "^## " first, then a line range.
- Very specific: line 17
Never push, never open PRs/issues/releases, never tag (HITL policy, hook-enforced).
- Very specific: line 23
When the gate (or the whole vitest suite) exceeds the shell timeout, run it in the background and read --json / the FAIL lines only.
- Very specific: line 34
Always drive the built server (node dist/cli.js.
- Very specific: line 58
Never edit a generated file: edit the source, then regenerate (verify:docs rules claude-rules-sync / governance-embed fail on drift).
- Very specific: line 64
Follow CONTRIBUTING.md §Release and scripts/release-prepare.ts: prepare everything (lock-step version, changelog, note, manifest, PR draft, …
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
@AGENTS.md
Claude Code addendum
Everything in AGENTS.md applies. This file adds only what is specific to Claude Code sessions in this repository.
Token discipline
- Run tests through
npx tsx scripts/gate.ts --fastornpx vitest run <file>(the dot reporter is configured); never paste a full test run into context. - Never Read
dist/,coverage/,test-output/,package-lock.json,node_modules/,.clusterfuzzlite/engine/package-lock.json,.audit/. The deny list in.claude/settings.jsonapplies to Read and, at best effort, to Grep/Glob — ask the built server (tools/list,prompts/get) instead of readingdist/;npm ls <pkg>answers lockfile questions; the large fixtures (engine-surface.json,tool-shape.json) are read bygrep -n, never whole. - A tool's inputs are in
src/tools/<name>.ts; a shared fragment (layout,print,color,font-dir, …) is one Grep away insrc/*.ts.tools/listis about 350 kB: project it, never print it. - Read README.md, ROADMAP.md, docs/KNOWLEDGE_BASE.md and docs/AGENT_CONTRACT.md by section:
grep -n "^## "first, then a line range. CHANGELOG.md: only the top entry. .github/instructions/*.mdare the per-area rules: open the ONE matching the area you touch.- Sample regeneration:
npm run build && npm run test:generatethennpx tsx scripts/verify-samples.ts. Any--update(rebaseline) must be justified in the release note. - Never push, never open PRs/issues/releases, never tag (HITL policy, hook-enforced). No
Co-Authored-Bytrailers (attribution.commitis"").
Gate
npx tsx scripts/gate.ts --fastbefore proposing a commit;npm run gateis the CI profile;--publish --require-allon release branches only.--only <step>for one step,--jsonfor machine output; logs intest-output/.gate/<step>.log— open only the failing step's log, through the shell.- When the gate (or the whole vitest suite) exceeds the shell timeout, run it in the background and read
--json/ theFAILlines only. The fuzz container never runs locally:tests/fuzzing/targets.test.tsis the proof.
Where to look first
src/server.ts— theTOOLSregistry, prompts, instructions;tests/_fixtures/tool-shape.json— every pinned schema shape.- AGENTS.md §Where is what — the path → purpose → instruction-file table.
docs/assets/ecosystem.json— every count and version;npm run verify:docsenforces it.
Stdout gotcha
On stdio, stdout IS the protocol: one stray console.log in src/ corrupts every session (the gate's smoke step fails on any non-JSON-RPC line). Log to stderr.
Always drive the built server (node dist/cli.js; harness tests/_stdio-session.ts) before claiming a change works.
Windows session notes
- The session shell is PowerShell, with Git Bash as the Bash tool. PowerShell swallows
--afternpm run— callnpx tsx scripts/<name>.tsdirectly. - Multi-line
node -epayloads and heredocs break on backticks,$and backslashes: write a script to the scratchpad and run it; a scratch.mtsimportingpdfnativemust sit inside the repository (test-output/). Git Bashsedmangles\d/\sin replacements — use Edit for a line that carries a regular expression. - veraPDF: portable install in
%USERPROFILE%\verapdfwith JDK 13; the runner readsVERAPDF_HOMEandJAVACMD(the JDK'sjava.exe—JAVA_HOMEalone is not enough when spawned from Node). npm installunder npm 10.9 can fail with an arboristedgesOuterror on a fresh resolution;npx npm@11.19.1 installworks,npm ciis unaffected.- vitest sometimes reports "no tests" right after a file write: run it again.
Hooks and permissions in force
.claude/hooks/guard.mjs(PreToolUse on Bash and PowerShell) deniesnpm publish/unpublish/deprecate/dist-tag/version,gh pr|issue create|edit|close|comment|merge,gh release, writinggh api, anygit push,git tag <name>,git add --renormalize— in every command segment,$( )/backticks andsh -c/pwsh/node -e/npx -cpayloads (a quoted string holding one is refused too: write it with Edit). The maintainer submits those (.github/AGENT_RULES.md);tests/tools/guard.test.tsis the rule table.permissions.denyblocks Read on the bulk files above and the same write commands, for both shells;permissions.allowpre-approvesnpm run,npx vitest,npx tsx scripts/*,npx tsc,npx eslint,node -eand read-only git.node dist/cli.jsis asked each time: it can reach the operator's TSA.
Plan mode, rules and skills
- Plan mode for multi-file changes (plans name files, commands and the expected gate outcome);
/code-reviewthe branch diff before drafting a PR body. .claude/rules/*.mdare generated from.github/instructions/*.instructions.mdbynpm run agents:rules(scoped bypaths:= the sourceapplyTo);src/governance-embed.tsfrom.github/ai-governance.json+AGENT_RULES.mdbynpm run agents:governance. Never edit a generated file: edit the source, then regenerate (verify:docsrulesclaude-rules-sync/governance-embedfail on drift)./release-audit [release-notes/vX.Y.Z.md] [previous-tag](.claude/skills/release-audit/) is the maintainer-invoked pre-release audit: two auditors, an adversarial verifier, an agent-autonomy pass and a GO/NO-GO ledger under.audit/.
Release
Follow CONTRIBUTING.md §Release and scripts/release-prepare.ts: prepare everything (lock-step version, changelog, note, manifest, PR draft, publish gate) and stop before pushing.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

