Reference
Package index
Eleven npm packages, what each one exports, and which of them work with no LLM at all.
Handbooks is a monorepo of eleven packages. Four of them never touch an LLM and are useful entirely on their own.
| Package | Role | LLM? | Docs |
|---|---|---|---|
@handbooks/core | Data model, zod schemas, config registry, utilities | ❌ | README |
@handbooks/analyzer | Multi-language static call-graph extraction | ❌ | README |
@handbooks/llm | OpenAI-compatible client, cache, actor–critic, mock | ✅ | README |
@handbooks/pipeline | The generation pipeline, phases 1–3 | ✅ | README |
@handbooks/renderer | Markdown, HTML, agent index, llms.txt | ❌ | README |
@handbooks/skill | SKILL packaging, validation, drift hashes | ❌ | README |
@handbooks/planner | Read-only planning agent | ✅ | README |
@handbooks/patcher | Byte-exact apply, backups, rollback | ❌ | README |
@handbooks/resync | Incremental roll-forward | ✅ | README |
@handbooks/studio | Local web UI | ✅ | README |
@handbooks/cli | The handbook command | — | README |
The three most useful on their own
@handbooks/analyzer — a call graph for 18 languages
import { registerBuiltinAdapters, discoverAll, getAdapter, buildGraph } from '@handbooks/analyzer';
registerBuiltinAdapters();
const byLanguage = discoverAll('/path/to/repo');
const analyses = [];
for (const [lang, files] of Object.entries(byLanguage)) {
analyses.push(await getAdapter(lang).analyze(files, '/path/to/repo'));
}
const { graph, stats } = buildGraph(
{ functions: analyses.flatMap((a) => a.functions), edges: analyses.flatMap((a) => a.edges) },
{
sourceRoot: '/path/to/repo',
scannedFiles: Object.values(byLanguage).flat(),
language: 'multi',
defaultExt: '',
},
);No LLM, no network, no native compilation.
@handbooks/patcher — apply an edit plan safely
import { applyPlan, rollback, parsePlan } from '@handbooks/patcher';
const problems = parsePlan(planText).problems; // lint a plan without applying it
const dry = applyPlan({ sourceRoot, plan: planText, dryRun: true });
if (dry.ok) {
const result = applyPlan({ sourceRoot, plan: planText });
// rollback(result.backupDir!, { expectedSourceRoot: sourceRoot })
}The plan format is documented in Applying changes. Nothing
requires the plan to have come from @handbooks/planner — you can write one by hand.
@handbooks/renderer — render any HandbookModel
import { renderMarkdownHandbook, renderAgentSite, renderLlmsTxt } from '@handbooks/renderer';
renderMarkdownHandbook(model, 'out/');
renderAgentSite(model, 'out/agent');
renderLlmsTxt(model, 'out/');HandbookModel is the only contract. Fill one however you like and rendering, skill
packaging and planning all work.
Key exports at a glance
// @handbooks/core — the vocabulary
CodeGraph · FunctionNode · CallEdge · AdapterCapabilities
FileCard · Skeleton · Assignment · Organization · Narration · RegisterEntry
HandbookModel · StageTree · coerceRole
resolveConfig · settingsFor · envName · scopedEnvName · loadConfigFile · applyEnvFiles
writeFileAtomic · readValidatedJson · pLimit · withRetry · withDirLock · sha256Hex
// @handbooks/analyzer — the parser
registerBuiltinAdapters · registerAdapter · getAdapter · availableLanguages
discoverAll · adapterForFile · buildGraph · writeGraphArtifacts · buildNavPack
// @handbooks/llm — the model seam
ChatClient · OpenAiChatClient · CachedChatClient · MockChatClient
resolveLlmEnv · llmConfigFromValues · actorCriticLoop · ROLE_PROMPTS
// @handbooks/pipeline — generation
generateHandbook · loadHandbookModel · runPhase1 · generateCards
synthesizeSkeleton · synthesizeWithDoctor · assignFiles · organizeStages
narrate · extractRegisters · classifyMembers · WorkDir
// @handbooks/renderer — presentation
renderMarkdownHandbook · renderHtmlSite · renderSinglePageHtml
renderAgentSite · renderLlmsTxt · HandbookView · stageMapMermaid
// @handbooks/skill — packaging
buildSkill · validateSkill
// @handbooks/planner — localization
runPlanner · handbookDirFromSkill · parseDeclarations · ReadOnlyTools
// @handbooks/patcher — execution
applyPlan · rollback · listBackups · parsePlan
// @handbooks/resync — roll-forward
resyncHandbook · loadCase · diffGraphs · detectCardDetail · loadCorrections
// @handbooks/studio — the UI
startStudio · createStudioServer · StateStore · JobRunnerInstalling
pnpm add @handbooks/analyzer # or npm / yarnEvery package is ESM-only ("type": "module"), ships type declarations, requires Node
≥ 20.11, and is MIT licensed. Third-party versions are pinned once in the workspace
catalog, so two packages can never end up on two versions of the same library.