![\"Burtson](\"https://cdn.burtson.ai/logos/burtson-labs-logo.png\"){kind=logo}
\n \n ![](\"https://icons.burtson.ai/svg-accent/download.svg\"){kind=icon}
Install\n\n```bash\npnpm add @burtson-labs/host-kit\n```\n\n## ![](\"https://icons.burtson.ai/svg-accent/blocks.svg\"){kind=icon}
What's in the box\n\n- **Memory loader** — discovers and merges `BANDIT.md` / `CLAUDE.md` / `AGENTS.md` files across workspace + global locations; deduplicates overlapping content at load time; `consolidateMemory()` unifies multiple entry files into a single canonical `BANDIT.md` (symlink on macOS/Linux, copy-with-drift-warning on Windows)\n- **Topic memory** — lazy-load index at `.bandit/memory/MEMORY.md` (preferred) with back-compat reads from legacy root `MEMORY.md`; writes always go to `.bandit/memory/`; `migrateMemoryToBanditDir()` moves an existing root `memory/` layout into `.bandit/memory/` idempotently\n- **`@-mention` expansion** — detects `@path/to/file` in user input and inlines file contents (with secret redaction) or attaches images as base64\n- **Hook runner** — executes PreToolUse / PostToolUse / Stop / UserPromptSubmit hooks; `loadHookSettings` merges the **global** `~/.bandit/settings.json` under the workspace `.bandit/settings.json` so hooks + permissions + the guard apply across every repo\n- **Pre-tool security guard** — `evaluateSecurityGuard(call, settings, ctx)`: an opt-in, in-process safety net (no shell spawn) that blocks catastrophic tool calls (`rm -rf /`, `curl … | sh`, disk wipes, credential exfil, writes to system/credential paths) before they run. Wired into `beforeToolExecute` in both hosts\n- **MCP loader** — reads `mcp-servers.json` (global + workspace, workspace wins), auto-injects `BANDIT_API_KEY`, registers servers with the pool\n- **Turn trace reader** — parses workspace and global `.bandit/turns/*.jsonl` into summaries and markdown timelines for CLI `/trace`, IDE `/trace`, tests, and future bug-bundle export\n- **Insights** — usage analytics aggregator (CLI sessions → human report)\n- **Extra tool builders** — `todo_write`, `web_fetch`, `web_search`, `task` (subagent), `remember`, `test_run`, `pdf_read`\n\n## ![](\"https://icons.burtson.ai/svg-accent/wrench.svg\"){kind=icon}
What you can do\n\n**Load and merge project memory** — `BANDIT.md` / `CLAUDE.md` / `AGENTS.md`, deduped:\n\n```ts\nimport { loadMemory, consolidateMemory } from '@burtson-labs/host-kit';\n\nconst { content } = await loadMemory(cwd); // merged, overlapping content removed\nawait consolidateMemory(cwd); // unify duplicates into one canonical BANDIT.md\n```\n\n**Lazy topic memory** — keep a tiny index in context, load topics on demand:\n\n```ts\nimport { loadMemoryIndex, writeMemoryTopic } from '@burtson-labs/host-kit';\n\nconst index = await loadMemoryIndex(cwd); // .bandit/memory/MEMORY.md\nawait writeMemoryTopic(cwd, 'auth-flow', '# Auth flow\\n…');\n```\n\n**Inline `@-mentions`** — file contents (secret-redacted) and images, expanded into the prompt:\n\n```ts\nimport { expandMentions } from '@burtson-labs/host-kit';\n\nconst { prompt, images } = await expandMentions('explain @src/auth.ts and @diagram.png', cwd);\n```\n\n**Block dangerous tool calls before they run** — opt-in, in-process, no shell spawn:\n\n```ts\nimport { evaluateSecurityGuard } from '@burtson-labs/host-kit';\n\nconst verdict = evaluateSecurityGuard(call, settings.security?.guard, ctx);\nif (!verdict.allow) abort(verdict.reason); // rm -rf /, curl | sh, disk wipes, credential exfil, …\n```\n\n**Run lifecycle hooks** — `PreToolUse` blocks; `PostToolUse` / `Stop` fire-and-forget:\n\n```ts\nimport { loadHookSettings, runHooks } from '@burtson-labs/host-kit';\n\nconst settings = await loadHookSettings(cwd); // global ~/.bandit + workspace, merged\nawait runHooks('PostToolUse', settings, { name, primary, duration });\n```\n\n**Register MCP servers** from `mcp-servers.json` (global + workspace, `BANDIT_API_KEY` injected):\n\n```ts\nimport { registerMcpServersFromDisk, addMcpServerToConfig } from '@burtson-labs/host-kit';\n\nawait registerMcpServersFromDisk(cwd, mcpPool);\n```\n\n**Drop-in agent tools** — register them straight into your tool registry:\n\n```ts\nimport { buildWebSearchTool, buildTaskTool, buildTestRunTool } from '@burtson-labs/host-kit';\n\nregistry.register(buildWebSearchTool({ apiKey })); // web search\nregistry.register(buildTaskTool({ /* … */ })); // spawn subagents\nregistry.register(buildTestRunTool()); // detect framework + run tests\n```\n\n**Read turn traces** — for a `/trace` view, audits, or bug bundles:\n\n```ts\nimport { listTurnTraces, readTurnTrace, formatTurnTraceMarkdown } from '@burtson-labs/host-kit';\n\nconst traces = await listTurnTraces(cwd);\nconsole.log(formatTurnTraceMarkdown(await readTurnTrace(cwd, traces[0].id)));\n```\n\n## ![](\"https://icons.burtson.ai/svg-accent/badge-check.svg\"){kind=icon}
Status\n\nStable. Imported by both [`apps/bandit-cli/`](../../apps/bandit-cli/) and [`apps/bandit-stealth/`](../../apps/bandit-stealth/) — breaking changes here require coordinated PRs to both hosts.\n\n## ![](\"https://icons.burtson.ai/svg-accent/zap.svg\"){kind=icon}
Quick example\n\n```ts\nimport { loadMemory, expandMentions, registerMcpServersFromDisk } from '@burtson-labs/host-kit';\n\nconst memory = await loadMemory(workspaceCwd);\nconst { prompt, images } = await expandMentions(rawUserInput, workspaceCwd);\nconst count = await registerMcpServersFromDisk(workspaceCwd, mcpPool);\n```\n\n## ![](\"https://icons.burtson.ai/svg-accent/beaker.svg\"){kind=icon}
Tests\n\n```bash\npnpm --filter @burtson-labs/host-kit test\n```\n\n## License\n\n[Apache License 2.0](../../LICENSE) — Copyright 2026 Burtson Labs.\n","readmeFilename":"README.md"}