
get-md v1.7.0 is out. Where 1.6.0 taught the library to read PDF, DOCX, and Markdown, this release is about not throwing away the one thing a Markdown converter usually destroys: **Mermaid diagrams**. v1.7.0 preserves Mermaid fences it finds, recovers the source from diagrams a browser has already rendered to `<svg>`, optionally reconstructs diagrams drawn into a PDF using a vision model, and optionally checks that whatever comes out actually parses. It also fixes a handful of real bugs surfaced along the way, including a validation path that was almost always wrong.

Built by the [Nano Collective](https://nanocollective.org), a community collective building AI tooling not for profit, but for the community.

## What changed

Four diagram behaviours, on by default where they can be, opt-in where they need optional dependencies:

1. **Preserved.** A ` ```mermaid ` fence in your HTML or Markdown comes out the other side unchanged, fence and language tag intact. Same treatment for `dot`, `graphviz`, and `plantuml`, all newly registered as recognised language identifiers.
2. **Recovered.** When a docs site has already rendered a diagram to `<svg>` (the GitHub, MkDocs, and Docusaurus case), get-md pulls the original source back out of the DOM before Readability and the HTML cleaner can strip it.
3. **Reconstructed.** Diagrams drawn into a PDF can be rebuilt by a remote vision model. Opt-in, capped at the first 10 pages, and remote providers only.
4. **Validated.** `validateMermaid: true` parses every Mermaid block in the finished Markdown and annotates the ones that fail, keeping the original so you can repair it rather than losing it.

These cover the same problem from four angles, and each one is independently switchable. The default install footprint is unchanged. New capabilities that need rendering or parsing install their own optional peer dependencies.

## Preserved: Mermaid fences survive conversion

`mermaid` is now a recognised language identifier, alongside `dot`, `graphviz`, and `plantuml`. Previously a Mermaid block survived only by accident, through a loose lowercase-word fallback with no test coverage behind it.

A ` ```mermaid ` block in HTML (`<pre><code class="language-mermaid">`) or in a Markdown file comes out the other side unchanged, fence and language tag intact. The behaviour applies from both the library and the CLI, across HTML, URL, and `.md` input.

The release also fixes a general case that affects every syntax-highlighted page, not just Mermaid: the Mermaid recovery work sets `keepClasses: true`, so `<pre><code class="language-x">` keeps its class through extraction. Fenced output is now tagged, ` ```python `, ` ```go `, ` ```rust `, where it previously came out bare. This is the most visible change in the release for anyone converting documentation sites. Two consequences worth knowing: unrecognised class names can now surface as tags via the lowercase-word fallback, and because element classes survive into the cleanup pass, class-based noise rules match more often (a `cookie-notice` block is correctly dropped, but so is genuine prose carrying an `advertisement` or `popup` class).

## Recovered: Mermaid source from rendered SVG

GitHub, MkDocs, and Docusaurus run mermaid.js client-side, so the HTML you fetch holds the rendered `<svg>`, not the diagram. The source is usually still in the DOM somewhere, and get-md now goes looking for it before Readability and the HTML cleaner can strip it.

The recovery looks for these container shapes:

- `.mermaid`, `pre.mermaid`, `[data-processed="true"]`, `svg[id^="mermaid-"]`, and `svg.mermaid`.

For each container it tries the first source it can find, in this order:

1. A `<script type="text/mermaid">` inside or next to the container.
2. A `data-code`, `data-mermaid`, `data-src`, `data-original`, or `data-source` attribute.
3. The container's own text when it is a `<pre>` holding no `<svg>`.
4. A hidden `pre[hidden]`, `<template>`, or `textarea[hidden]`.
5. The SVG's `<desc>`, `<title>`, or `aria-label`.

That last fallback is deliberately strict. mermaid.js writes accessibility strings such as `Created with Mermaid` into those nodes, and emitting one as a diagram would be worse than dropping it. Text qualifies only if it is multi-line, contains `;`, or opens with a diagram keyword and carries an arrow, a colon, or real length.

Recovered diagrams are re-emitted as ` ```mermaid ` fences. Where no source is recoverable, behaviour is unchanged: the SVG's text labels fall through as loose text.

## Reconstructed: diagrams in PDFs by a vision model (opt-in)

A diagram in a PDF is vector drawing or raster image. There is no text to recover, so this is a vision problem. With `useLLM` and a remote vision-capable model, get-md renders PDF pages to images and asks the model to emit Mermaid inline where the diagram appeared.

A few constraints worth stating up front:

- **Remote providers only.** The local ReaderLM-v2 path is text-only, and so is `useLLM` with no `llm` config, since that defaults to local-llama. Neither renders pages nor calls a vision model.
- **New optional peer dependencies.** `pdfjs-dist` (^5) and `@napi-rs/canvas` (^0.1), installed only if you want this. Standard fonts resolve dynamically from the installed `pdfjs-dist`.
- **Capped at the first 10 pages**, to keep long PDFs from overflowing the model's context. Longer documents log a warning naming the cap; text extraction still covers the whole file.
- **Fails soft in both directions.** Missing render dependencies or a render error warns and continues text-only, and a failed vision request retries the same conversion without images.
- **Accuracy varies with the model and the diagram.** This is a best-effort assist, not guaranteed fidelity.

One limitation carried over from 1.6.0 and now worth stating explicitly: a PDF with no extractable text, a pure scan or a page that is nothing but a diagram, still returns an empty result before page rendering is attempted, so vision reconstruction never runs on exactly the PDFs that would benefit most.

## Validated: parse every Mermaid block (opt-in)

`validateMermaid: true` runs every ` ```mermaid ` fence in the finished Markdown through mermaid's own parser and annotates the ones that fail, so a model that emits plausible-but-broken Mermaid does not do so silently.

- Invalid blocks are **kept**, with a GitHub-style `> [!WARNING]` callout inserted above them. You repair the diagram rather than losing it.
- Applies to all Mermaid in the output: preserved, recovered, and model-generated alike, and runs last, after conversion and image localization.
- Available as the `validateMermaid` library option, the `--validate-mermaid` CLI flag, and a `validateMermaid` config-file key, across every conversion path: HTML, URL, Markdown, PDF, DOCX, batch, and sitemap.
- Requires the **optional** `mermaid` peer dependency (^11). Without it, get-md logs a warning and returns the Markdown untouched, so enabling the option can never break a conversion.
- Only non-indented triple-backtick fences are matched; indented fences may pass through unvalidated.

```typescript
import { convertToMarkdown } from "@nanocollective/get-md";

const result = await convertToMarkdown(source, {
  inputType: "markdown",
  validateMermaid: true,
});
```

## Bug fixes from the launch review

Three real bugs were caught while building this release, and a behavioural change worth its own callout.

- **Mermaid validation no longer rejects valid diagrams.** `mermaid.parse` sanitizes label text through DOMPurify, which needs a DOM. Under plain Node there wasn't one, so any diagram carrying node labels, things like `A[Start]`, `B{Choice}`, `-->|yes|`, and every class, state, ER, gantt, and mindmap diagram, threw `DOMPurify.addHook is not a function`, and the validator treated any throw as a syntax error. In practice almost every real diagram was annotated as invalid, including correct output from the PDF vision path this option exists to check. Validation now installs a headless DOM before importing mermaid (the point DOMPurify binds to the global scope) and restores the global scope afterwards, including `process`, which constructing a happy-dom `Window` replaces. Only a genuine parse complaint now annotates the document; anything environmental logs one diagnostic and leaves the diagram alone. Two diagram types (`pie`, `gitGraph`) still take that path, failing inside a lazily loaded mermaid parser chunk, and are skipped by the validator.
- **`--config <path>` is no longer ignored.** The flag was accepted, and `--show-config` even printed the path, but every conversion still loaded configuration through cwd/home auto-discovery. An explicitly named config file had no effect on output and its validation errors never surfaced, so a typo'd config failed silently. All five conversion paths and `--show-config` now resolve config through one helper that honors the flag.
- **Duplicate validation warnings prevented.** Re-running validation over already-annotated Markdown no longer stacks a second warning onto the same block. The fence-matching regex was also tightened for stability.
- **PDF rendering is loaded dynamically**, so the optional `pdfjs-dist` and `@napi-rs/canvas` dependencies are never touched unless vision reconstruction is actually in play.

## Behaviour change: code-block language tags survive

Already covered above, but worth its own callout because it affects every docs conversion, not just Mermaid. The recovery work sets `keepClasses: true`, so `<pre><code class="language-x">` keeps its class through Readability extraction. Fenced output is now tagged where it previously came out bare. The two tradeoffs above (unrecognised class names surfacing as tags, class-based noise rules matching more often) are real, and worth noting if your pages lean heavily on either.

## Installation

```bash
npm install -g @nanocollective/get-md

# Install this specific version
npm install -g @nanocollective/get-md@1.7.0
```

For the optional paths:

```bash
# PDF diagram reconstruction (vision)
npm install pdfjs-dist @napi-rs/canvas

# Mermaid validation
npm install mermaid
```

## Usage

```bash
getmd
```

Or from a script:

```typescript
import { convertToMarkdown } from "@nanocollective/get-md";

// From HTML string
const result = await convertToMarkdown("<h1>Hello</h1><p>World</p>");
console.log(result.markdown);

// From a Markdown file with validation
const validated = await convertToMarkdown(markdownSource, {
  inputType: "markdown",
  validateMermaid: true,
});
```

## Documentation

The new [Diagrams & Mermaid guide](https://docs.nanocollective.org/get-md/docs/guides/mermaid) covers the support matrix of what is preserved, recovered, reconstructed, and validated per input type, the recovery precedence order, setup and limits for the opt-in PDF path, and a troubleshooting table. The README gains a Mermaid section, and the runnable [`examples/mermaid-diagrams.ts`](https://github.com/Nano-Collective/get-md/blob/main/examples/mermaid-diagrams.ts) covers preservation, recovery, and validation entirely offline, with the PDF vision path as a commented snippet.

## Tests

634 passing (up from 592 at 1.6.0). New coverage for Mermaid fence preservation from HTML and Markdown, and the other diagram languages; source recovery across every container shape and source strategy, including the accessibility-text guard; PDF page rendering and the 10-page cap; vision prompting, multimodal message assembly, and text-only fallback; validation across nine diagram shapes that were previously false-positived, plus global-scope and `process` restoration; and the `--validate-mermaid` flag and `--config` resolution end-to-end through the CLI.

## Upgrading

```bash
npm install @nanocollective/get-md@1.7.0
```

Or:

```bash
pnpm add @nanocollective/get-md@1.7.0
```

Node.js 22 or later is required. No peer dependencies are required for the standard HTML/PDF/DOCX/Markdown paths. The new Mermaid and PDF-vision paths install their own optional dependencies when you opt in.

If you hit any issues or want to dig into the diagram recovery work, open an issue or find us on [Discord](https://discord.gg/ktPDV6rekE).

Repo: https://github.com/Nano-Collective/get-md


get-md v1.7.0: Mermaid diagrams survive the conversion, end to end


get-md v1.7.0 is out. The headline is that Mermaid diagrams now survive HTML, URL, and Markdown conversions, end to end.

Where 1.6.0 taught get-md to read PDF, DOCX, and Markdown alongside HTML, this release is about not throwing away the one thing a Markdown converter usually destroys: diagrams. v1.7.0 handles Mermaid four ways:

- Preserved. A ` ```mermaid ` fence in your HTML or Markdown comes out unchanged, fence and language tag intact. On by default.
- Recovered. When a docs site has already rendered a diagram to `<svg>` (the GitHub, MkDocs, and Docusaurus case), get-md pulls the original source back out of the DOM. On by default.
- Reconstructed. Diagrams drawn into a PDF can be rebuilt by a remote vision model. Opt-in, capped at the first 10 pages, remote providers only.
- Validated. `validateMermaid: true` parses every Mermaid block in the finished Markdown and annotates the ones that fail, keeping the original so you can repair it rather than losing it. Opt-in.

Two related fixes shipped with the release. Code-block language tags now survive Readability extraction, so ` ```python `, ` ```go `, ` ```rust ` fenced output is tagged where it previously came out bare. And Mermaid validation no longer false-positives on every real diagram: a headless DOM is installed before mermaid loads, so DOMPurify-bound label sanitizing stops throwing.

The default install footprint is unchanged. The new PDF vision path needs optional `pdfjs-dist` and `@napi-rs/canvas`; the Mermaid validator needs optional `mermaid`. Standard HTML/PDF/DOCX/Markdown conversions work with no peer dependencies.

634 tests passing, up from 592 at 1.6.0.

Install: `npm install @nanocollective/get-md@1.7.0`

Full notes, examples, and the support matrix are in the GitHub Discussion.

Repo: https://github.com/Nano-Collective/get-md



We've just shipped get-md v1.7.0, and we wanted to explain why this one matters even if you don't use Mermaid.

The short version: 1.6.0 taught get-md to read PDF, DOCX, and Markdown alongside HTML. That worked, but it surfaced a problem we hadn't really focused on before: Mermaid diagrams. They're the thing a Markdown converter usually destroys, because the converter sees either a fence it doesn't recognise or a rendered `<svg>` it doesn't know what to do with. v1.7.0 is about fixing that, end to end.

**What we shipped**

Four diagram behaviours, each independently switchable:

1. **Preserved.** A ` ```mermaid ` fence in your HTML or Markdown comes out the other side unchanged. Same for `dot`, `graphviz`, and `plantuml`, all newly registered as proper language identifiers. Previously these survived only by accident, through a loose lowercase-word fallback with no test coverage behind it.

2. **Recovered.** GitHub, MkDocs, and Docusaurus render Mermaid client-side, so the HTML you fetch holds the rendered `<svg>`, not the diagram. The source is usually still in the DOM somewhere, and we now go looking for it before Readability and the HTML cleaner can strip it. We try `<script type="text/mermaid">` tags, `data-code`/`data-mermaid`/`data-src` attributes, hidden `<template>` and `textarea[hidden]` blocks, and finally the SVG's `<desc>`/`<title>`/`aria-label`. The last fallback is deliberately strict, because mermaid.js writes accessibility strings like `Created with Mermaid` into those nodes, and emitting one as a diagram would be worse than dropping it.

3. **Reconstructed (opt-in).** A diagram in a PDF is vector drawing or raster image. There is no text to recover, so this is a vision problem. With `useLLM` and a remote vision-capable model, we render PDF pages to images and ask the model to emit Mermaid inline where the diagram appeared. Cap is 10 pages, to keep long PDFs from overflowing context. Remote providers only, because the local ReaderLM-v2 path is text-only. Best-effort, not guaranteed fidelity.

4. **Validated (opt-in).** `validateMermaid: true` runs every Mermaid block in the finished Markdown through mermaid's own parser. Invalid blocks are **kept**, with a GitHub-style `> [!WARNING]` callout above them. You repair the diagram rather than losing it. Applies to all Mermaid: preserved, recovered, and model-generated alike.

**Two things that surprised us while building this**

First, Mermaid validation was almost always wrong. `mermaid.parse` sanitizes label text through DOMPurify, which needs a DOM. Under plain Node there wasn't one, so any diagram carrying node labels (`A[Start]`, `B{Choice}`, `-->|yes|`, and every class/state/ER/gantt/mindmap diagram) threw `DOMPurify.addHook is not a function`, and the validator treated every throw as a syntax error. In practice almost every real diagram was annotated as invalid, including correct output from the PDF vision path this option exists to check. We install a headless DOM before importing mermaid now and restore the global scope afterwards, including `process`, which constructing a happy-dom `Window` replaces. Only genuine parse complaints annotate the document now. Two diagram types (`pie`, `gitGraph`) still take the old path, because they fail inside a lazily loaded parser chunk, and they're skipped rather than misreported.

Second, code-block language tags now survive Readability extraction. The Mermaid recovery work sets `keepClasses: true`, so `<pre><code class="language-x">` keeps its class through extraction. This is the most visible change in the release for anyone converting documentation sites: ` ```python `, ` ```go `, ` ```rust ` fenced output is tagged where it previously came out bare. There are two tradeoffs: unrecognised class names can surface as tags via the lowercase-word fallback, and class-based noise rules now match more often (a `cookie-notice` block is correctly dropped, but so is genuine prose carrying an `advertisement` or `popup` class). Worth knowing if your pages lean on either.

**Other fixes**

- `--config <path>` was being silently ignored. The flag was accepted, `--show-config` even printed the path, but every conversion still loaded through cwd/home auto-discovery, so a typo'd config failed silently. All five conversion paths now resolve config through one helper that honors the flag.
- Re-running validation over already-annotated Markdown no longer stacks a second warning onto the same block.
- PDF rendering is loaded dynamically, so the optional `pdfjs-dist` and `@napi-rs/canvas` dependencies are never touched unless vision reconstruction is actually in play.

**Install footprint**

The default install is unchanged. The PDF vision path needs optional `pdfjs-dist` and `@napi-rs/canvas`; the Mermaid validator needs optional `mermaid`. Standard HTML/PDF/DOCX/Markdown conversions work with no peer dependencies.

```bash
npm install @nanocollective/get-md@1.7.0
```

634 tests passing, up from 592 at 1.6.0. New coverage spans every container shape and source strategy for recovery (including the accessibility-text guard), PDF page rendering and the 10-page cap, vision prompting and multimodal message assembly, validation across nine previously false-positived shapes, and the `--validate-mermaid` and `--config` flags end-to-end through the CLI.

The full release post (with the support matrix and recovery precedence order spelled out) is in the GitHub Discussion linked from the repo. Issues and Discord both open if you hit anything or want to dig into the diagram recovery work.

Repo: https://github.com/Nano-Collective/get-md



get-md v1.7.0: Mermaid diagrams now survive HTML/PDF/Markdown conversions, end to end. Preserved, recovered from rendered SVG, optionally reconstructed by a vision model for PDFs, optionally validated. 634 tests passing.

https://github.com/Nano-Collective/get-md



The Nano Collective doesn't hide a gate behind a 'just ask' form. Stage 0 is a Discord message or a docs issue with your idea, and the answer is usually 'yes, write the whitepaper'. It is a sanity check, not a filter.


1.12GB on your disk. Zero API calls. get-md's local LLM path runs ReaderLM-v2 via node-llama-cpp, so better Markdown conversion costs you storage, not metered tokens.


Your oldest JSON file has no version field, and that file is the one that breaks first. json-up treats missing version as v0 by default, so every unversioned file in production runs through the same migration chain as a fresh one. No special-case branch for legacy data.


Three places a skill can live - project, global, built-in - and only one wins. Project shadows global, global shadows built-in. /skills promote copies a project skill to every repo, /skills demote vendors a built-in into one. /skills show tells you which layer won.



An open-ended eval you can't re-run isn't an eval. In Nanotune the LLM judge is a config: provider, model, criteria, threshold in `.nanotune/judge.json`, plugged into a benchmark with `"match": "llm-judge"`. Open-ended now reproduces like string-match.


Nanocoder v1.29.0 is out. The headline is a native VS Code GUI powered by the Agent Client Protocol: the extension now spawns and drives `nanocoder --acp` itself, so there is nothing to run in a terminal. Alongside that: you can press `Ctrl+S` to attach to a running subagent session and watch what it is doing in real time, a new `PrivacyContext` scrubs sensitive content out of prompts before they leave your machine, and each development mode can now have its own provider and model.

Built by the [Nano Collective](https://nanocollective.org), a community collective building AI tooling not for profit, but for the community.

Full changelog and docs at [https://github.com/Nano-Collective/nanocoder](https://github.com/Nano-Collective/nanocoder).

## Native VS Code GUI

The biggest change in this release is that the VS Code extension now ships a full sidebar chat, not a companion window. The extension spawns and manages `nanocoder --acp` itself, so the only thing in the terminal is whatever you were already doing. Responses stream into a sidebar webview with collapsible thinking sections, tool activity renders as live cards, and file edits open in VS Code's diff viewer.

Behind the scenes this is the Agent Client Protocol (ACP) plumbing added in v1.28.0, now with a real editor on top. Concretely:

- **Sessions persist to disk.** New Chat, a session history view with resume and delete, and full thread replay (including thinking and completed tool cards) on resume. A resumed thread looks like the conversation you left, not an empty screen.
- **Provider, model, and mode switching** from dropdowns in the chat header. The model list refreshes when you switch provider.
- **Slash commands work in the GUI.** `/help`, `/clear`, and any custom commands from `.nanocoder/commands`. CLI-only commands explain themselves rather than failing silently. Messages that start with file paths are not mistaken for commands.
- **Interactive tools render properly.** `ask_user` questions render with one button per answer. Tool approvals show Approve/Deny inline instead of a terminal prompt.
- **Live progress.** Subagent runs stream token and tool counts onto their card. The task tool (`write_tasks`) renders as a live checklist via ACP `plan` updates, which also lights up in other ACP clients like Zed.
- **Cancellation works end to end.** Stop ends the whole turn: the current tool aborts, queued tools are skipped, and no follow-up model request is issued.
- **Robust CLI spawning.** The extension resolves the login shell's PATH (nvm-friendly when VS Code launches from the Dock), runs the CLI in the workspace folder, validates `nanocoder.cliPath`, and surfaces the last stderr line in the crash dialog. A silent `--acp` startup crash when the working directory was unwritable is fixed.

Legacy WebSocket companion mode is now opt-in (`nanocoder.autoConnect` defaults to off), and the extension docs have been rewritten around the GUI.

Thanks to @akramcodez and @Dhirenderchoudhary for the build.

## Attach to a running subagent

Subagents have been useful but opaque: they run in their own context and you only saw the result when they finished. v1.29.0 lets you attach to a running subagent from the terminal UI and inspect exactly what it is doing, including streaming text and reasoning, in real time.

- Press `Ctrl+S` while a subagent is running to attach to it.
- If multiple subagents are running in parallel, `Ctrl+S` cycles through them.
- Press `Esc` to detach and return to the parent.

Under the hood this needed two fixes that were easy to miss. The attached-session transcript renders through Ink's append-only `<Static>`, so switching agents never printed the new agent's messages; the view is now remounted per agent with a terminal wipe (the same treatment `/clear` uses), and rapid `Ctrl+S` presses cycle reliably. Thanks to @llupRisinglll.

## Privacy-aware prompt scrubbing

A new `PrivacyContext` scrubs sensitive content from prompts before they leave your machine. Tool arguments are rehydrated locally after the response comes back, so the model still sees the values it needs while the cloud provider only ever sees placeholders. There is also:

- **Privacy session support.** Scrubbed placeholders stay stable within a session so re-prompts and follow-ups keep working.
- **A `/privacy` command** to inspect what is being scrubbed in the current session, with the active rule pack and a sample of recent scrub events.
- **Automated scrubbing telemetry notifications** so you see when something is being scrubbed rather than it happening silently.

Thanks to @akramcodez.

## Mode-specific provider and model configuration

You can now bind a different provider and model to each development mode (normal, auto-accept, yolo, plan), so the cheap local model you use for chat is not the one you accidentally burn through with `--mode yolo` on a long refactor. The configuration lives in `agents.config.json` under a per-mode block and re-resolves live when you switch modes.

Closes #277. Thanks to @akramcodez.

## Interactive questions in plan mode

Plan mode used to plan around ambiguity by guessing. v1.29.0 lets the agent ask structured questions via `ask_user` while it is planning, with one button per answer, so it can resolve open questions instead of inventing answers. The questions render inline in the GUI and as a normal `ask_user` prompt in the terminal UI. Closes #96. Thanks to @akramcodez.

## TUI refinements

A grab bag of quality-of-life fixes to the terminal UI:

- **Dual screen modes.** `--alt-screen` (fullscreen with in-app scrolling) and the inline default both render correctly. `/clear` is more reliable and exits cleanly. Thanks to @llupRisinglll.
- **Multiline cursor navigation and word-jump** in the input box, with sane behavior on narrow terminals. Thanks to @llupRisinglll.
- **Fuzzy search in the `/model` picker**, with a capped, centered scrolling window so large model catalogs no longer overflow the terminal. The current model is preselected. Closes #683. Thanks to @rakshith1928.
- **Tabbed `/settings` dialog** with searchable categories, so settings are easier to scan and filter from the TUI. Closes #471. Thanks to @llupRisinglll.
- **Fixed static vs. live content misalignment in `--alt-screen` mode.** The chat transcript and the input/tools footer now share the same left column, so assistant messages, tool results, and the input line up cleanly. The fix moves the footer out to the transcript's padded column rather than pushing the transcript into the scroll viewport's clip window (which was clipping the first character of each line).
- **`ask_user` cleanup.** Emoji badges removed from the question type, and the tool result now always renders the full Question/Answer block even in compact tool display mode, instead of folding into the tool tally and hiding what was answered.
- **Command suggestions on `/`.** The completion menu now appears as soon as you type `/`, and Tab selects the highlighted suggestion. Previously the menu was Tab-triggered and often failed to render, especially in alternate-screen mode. Recalling a `/command` from history with the arrow keys no longer opens the menu, so up/down keep navigating history freely; the menu returns as soon as you type.
- **Image attachments leave an `[Image #N]` placeholder** in the message. Dragged or typed image paths are no longer silently stripped; each becomes a numbered `[Image #N]` placeholder (mirroring the `[Paste #N]` convention), numbered after any images already attached via Ctrl+V, and highlighted in the chat history like `[@file]` mentions.

## Session resume, CLI flags

`--continue` (`-c`) resumes the most recent session for the current directory. `--resume [id]` (`-r`) resumes a session by id, list index, or `last`, with a bare `--resume` opening the session picker at startup. Thanks to @llupRisinglll.

## New commands and flags

- **`/doctor`** checks your setup and reports common configuration problems (missing binaries, broken config files, stale model caches). Closes #609. Thanks to @Dhirenderchoudhary.
- **`/retry`** re-runs the last user turn without retyping the prompt. Closes #608. Thanks to @Dhirenderchoudhary.
- **`--json` output flag** for the non-interactive plain run path, for piping Nanocoder into other tools. Thanks to @OMEE-Y.
- **`diff_edit` tool** for nano-profile models, so very small local models that struggle with `string_replace` have a more forgiving edit primitive. Closes #604. Thanks to @Dhirenderchoudhary.

## Under the hood

- **Stateless API with history-boundary rehydration.** The client now treats the model as a stateless endpoint and rehydrates conversation history at history boundaries, which improves reliability across reconnects and provider restarts. Thanks to @akramcodez.
- **Foundation for semantic memory** (storage layer and initial wiring), groundwork for upcoming memory features. Thanks to @Dhirenderchoudhary.
- **File tools resolve relative paths against the shell's current working directory**, and `cd` in bash persists across commands, so relative reads and edits work after moving into a subdirectory or worktree. File tools also accept absolute paths that point inside the project, and can still reach the project root or a sibling worktree after `cd`-ing into a subdirectory.
- **Automatic diagnostics after file edits** surface errors introduced by an edit right away, in the same render pass. Closes #538. Thanks to @2409324124.
- **Message queueing while the agent is busy** so you can type ahead. Queued messages can be recalled before streaming, are truncated properly on narrow terminals, and no longer double-dispatch. Closes #597, #598. Thanks to @Dhirenderchoudhary.
- **Estimated dollar cost tracking in `/usage`**, with a per-provider cost breakdown and a cumulative per-call cost history. Closes #602. Thanks to @rakshith1928.
- **PDF and DOCX support in `read_file`** via get-md, so those documents can be read directly into the conversation. Thanks to @akramcodez.

## Providers

- **Together AI** joins the provider template list with first-class docs. Thanks to @octo-patch.
- **MiniMax Coding now defaults to MiniMax-M3**. Thanks to @octo-patch.
- **Atomic Chat** has new local provider configuration docs. Thanks to @yanalialiuk.
- **Thesean AI** is added as a provider template. The `/setup-providers` wizard includes Thesean's Ship endpoint with Anthropic-compatible Claude models (`ship-like/claude-opus-4-8`, `ship-like/claude-sonnet-5`, `ship-like/claude-haiku-4-5`), plus a new docs page covering configuration and available models.

## Fixes

- **`nanocoder.tune` loading and configuration precedence** from `agents.config.json` now resolve correctly. Closes #648. Thanks to @rakshith1928.
- **Malformed SSE termination strings from providers** are now patched, preventing stream parsing errors. Closes #614. Thanks to @akramcodez.
- **Slash command completions are bounded** so the menu no longer overflows. Closes #624. Thanks to @2409324124.
- **Console log verbosity is decoupled from `NODE_ENV`**, and noisy LSP discovery logs are quieted. Closes #606. Thanks to @A-S-Manoj.
- **Removed the `strip-ansi` runtime dependency.** Closes #643. Thanks to @2409324124.
- **Provider configuration loading** preserves existing providers and falls back to a working provider on startup instead of freezing. Thanks to @llupRisinglll.

## Documentation

- Simplified Chinese README and Traditional Chinese translations, with fixes to the Simplified Chinese copy, plus a star-history chart. Thanks to @2409324124, @jason1015-coder, and @zerone0x.
- A typing SVG in the README showing "Meet Nanocoder" and "your private, local first AI coding assistant". Thanks to @jason1015-coder.
- VS Code extension docs rewritten around the GUI.

## Dependency updates

`@ai-sdk/google`, `@ai-sdk/openai-compatible`, `undici`, `diff`, and `knip`.

The VS Code extension saw major work this cycle (ACP process manager and handshake, a chat sidebar webview with tool-permission and diff UI, session persistence, and Tailwind styling). It is versioned separately from the CLI. Thanks to @akramcodez and @Dhirenderchoudhary.

If anything is broken or surprising, please open an issue or drop a note in Discord. Thank you for using Nanocoder.

Nanocoder v1.29.0: native VS Code GUI, subagent attach, prompt scrubbing


Nanocoder v1.29.0 is out, and the headline is a native VS Code GUI: the extension now spawns and drives `nanocoder --acp` itself, so there is nothing to run in a terminal. Responses stream into a sidebar webview with collapsible thinking, tool activity renders as live cards, and file edits open in VS Code's diff viewer. Sessions persist, and a resumed thread looks like the conversation you left, not an empty screen.

Three other additions sit alongside it. You can press `Ctrl+S` to attach to a running subagent session and watch what it is doing in real time, with `Esc` to detach. A new `PrivacyContext` scrubs sensitive content out of prompts before they leave your machine, with a `/privacy` command to inspect what is being scrubbed. Each development mode (normal, auto-accept, yolo, plan) can now have its own provider and model, so the cheap local model you chat with is not the one you accidentally burn through on a long refactor.

The TUI also got a lot of attention this cycle. Dual screen modes render correctly, multiline cursor navigation and word-jump work in the input box, the `/model` picker has fuzzy search and a bounded scrolling window, the `/settings` dialog is tabbed and searchable, and command suggestions appear as soon as you type `/`. `Ctrl+S` cycles through parallel subagents reliably. Image attachments now leave an `[Image #N]` placeholder in the message instead of being silently stripped.

A few smaller things worth knowing: `--resume` and `--continue` CLI flags for session resumption, a `/doctor` command to surface common configuration problems, a `/retry` command to re-run the last turn, a `--json` output flag for the non-interactive run path, and PDF/DOCX support in `read_file`. The client is now stateless with history-boundary rehydration, semantic memory has its storage layer in place, and Together AI plus Thesean AI are added as first-class provider templates.

Full release notes and changelog at https://github.com/Nano-Collective/nanocoder.

Built by the Nano Collective, a community collective building AI tooling not for profit, but for the community.


We just shipped Nanocoder v1.29.0, and this one felt worth writing up. The headline is a native VS Code GUI: the extension now spawns and drives `nanocoder --acp` itself, so there is nothing to run in a terminal. Sessions persist, slash commands work, interactive tools render as buttons, and a resumed thread looks like the conversation you left. Legacy WebSocket companion mode is now opt-in.

Underneath that there are a few things we have wanted to ship for a while. You can now press `Ctrl+S` to attach to a running subagent and watch what it is doing in real time, including streaming text and reasoning, and `Ctrl+S` cycles through multiple parallel subagents reliably. Press `Esc` to detach.

A new `PrivacyContext` scrubs sensitive content out of prompts before they leave your machine, with tool-argument rehydration, privacy session support, a `/privacy` command to inspect what is being scrubbed, and automated scrubbing telemetry notifications. Each development mode (normal, auto-accept, yolo, plan) can now have its own provider and model, so the cheap local model you chat with is not the one you accidentally burn through on a long refactor. Plan mode can now ask you structured questions via `ask_user` while it is planning, with one button per answer, instead of guessing around ambiguity.

## TUI work

A lot of quality-of-life fixes to the terminal UI this cycle:

- Dual screen modes (`--alt-screen` and inline) both render correctly, and `/clear` is more reliable.
- Multiline cursor navigation and word-jump in the input box.
- Fuzzy search in the `/model` picker, with a capped, centered scrolling window so large catalogs no longer overflow the terminal.
- Tabbed `/settings` dialog with searchable categories.
- Fixed static vs. live content misalignment in `--alt-screen` mode so the transcript and the input/tools footer line up cleanly.
- `ask_user` cleanup: emoji badges removed from the question type, and the tool result now always renders the full Question/Answer block even in compact display mode.
- Command suggestions appear as soon as you type `/`, and Tab selects the highlighted suggestion. Recalling a `/command` from history with the arrow keys no longer opens the menu.
- Image attachments now leave an `[Image #N]` placeholder in the message instead of being silently stripped.
- `Ctrl+S` cycles between parallel subagent sessions reliably, with the attached transcript remounted per agent.

## Smaller but useful

- `--continue` (`-c`) resumes the most recent session for the current directory. `--resume [id]` (`-r`) resumes a session by id, list index, or `last`, with a bare `--resume` opening the session picker at startup.
- A `/doctor` command checks your setup and reports common configuration problems.
- A `/retry` command re-runs the last user turn.
- A `--json` output flag for the non-interactive plain run path.
- A `diff_edit` tool for nano-profile models that struggle with `string_replace`.
- PDF and DOCX support in `read_file` via get-md.
- Estimated dollar cost tracking in `/usage`, with a per-provider breakdown.
- Message queueing while the agent is busy, so you can type ahead. Queued messages can be recalled before streaming, are truncated properly on narrow terminals, and no longer double-dispatch.

## Under the hood

- The client now treats the model as a stateless endpoint and rehydrates conversation history at history boundaries, which improves reliability across reconnects and provider restarts.
- Foundation for semantic memory (storage layer and initial wiring).
- File tools resolve relative paths against the shell's current working directory, and `cd` in bash persists across commands, so relative reads and edits work after moving into a subdirectory or worktree.
- Automatic diagnostics after file edits surface errors introduced by an edit right away.

## Providers

- Together AI joins the provider template list with first-class docs.
- MiniMax Coding now defaults to MiniMax-M3.
- Atomic Chat has new local provider configuration docs.
- Thesean AI is added as a provider template, with Anthropic-compatible Claude models (`ship-like/claude-opus-4-8`, `ship-like/claude-sonnet-5`, `ship-like/claude-haiku-4-5`) and a new docs page.

## Fixes worth calling out

- `nanocoder.tune` loading and configuration precedence from `agents.config.json` now resolve correctly.
- Malformed SSE termination strings from providers are now patched, preventing stream parsing errors.
- Slash command completions are bounded so the menu no longer overflows.
- Console log verbosity is decoupled from `NODE_ENV`, and noisy LSP discovery logs are quieted.
- The `strip-ansi` runtime dependency is gone.
- Provider configuration loading preserves existing providers and falls back to a working provider on startup instead of freezing.

## Documentation

- Simplified Chinese README and Traditional Chinese translations, with fixes to the Simplified Chinese copy, plus a star-history chart.
- A typing SVG in the README.
- VS Code extension docs rewritten around the GUI.

## Who this is for

If you have been waiting for an editor-native experience, the new VS Code GUI is the headline. If you have been frustrated that subagents are opaque while they run, `Ctrl+S` to attach fixes that. If you have wanted to keep more of your prompt out of a cloud provider, `PrivacyContext` is the answer. If you have wanted a different model for `yolo` than for `plan`, mode-specific provider and model configuration is finally here.

Repo, changelog, and docs are at https://github.com/Nano-Collective/nanocoder. We would love to hear what breaks or what is missing.


Nanocoder v1.29.0: native VS Code GUI, Ctrl+S to attach to running subagents, privacy-aware prompt scrubbing, mode-specific provider config, new doctor/retry commands. https://github.com/Nano-Collective/nanocoder


Your agent's `ls`, `git log`, `cat`, and `grep` outputs go to the next LLM turn in the clear. The cloud sees your repo layout and your hosts file.

prompt-scrub scrubs every message in the array under one session id. The same email maps to the same `Email_1` across the loop.



$250/mo puts your logo on Nano Collective surfaces. What it does not buy is also on the page: no roadmap influence, no contributor pay decisions, no exclusivity. The offer and the constraint sit side by side, on purpose.



Most CLIs guess wrong on stdin. get-md sniffs the first bytes: `%PDF` routes to the PDF extractor, anything else gets parsed as HTML. DOCX and Markdown still need a file path, so the autodetect surface is wider than the docs suggest.


Your data already has rows with a version field, and renaming it is a migration of the migration. json-up's migrate() takes a key parameter, so pass `key: 'version'` (or whatever you used) and nothing breaks. One parameter, no migration of the migration.



A risky refactor under an agent ties up conversation history, edited files, and your model config in one knot. `/checkpoint create before-refactor` saves all three, so the destructive try costs nothing if it fails.


Throwing more data at a tiny model is not fine-tuning. It's over-training in disguise. Nanotune ships 100–500 examples as the honest default for 0.5B–1.5B models because quality beats volume when the model is small enough to memorise every row.



# Introducing Sentinel: a Nanocoder-driven audit workflow for your GitHub org

We are publishing the first public build of Sentinel. **Built by the [Nano Collective](https://nanocollective.org): a community collective building AI tooling not for profit, but for the community.**

Sentinel is an installable, Nanocoder-driven workflow that runs continuous, configurable security and code audits across the repositories in a GitHub organisation, and files what it finds as issues for a human to act on. You install it into your org, point it at the repos you care about, write the rule packs that describe what to look for, and a scheduled GitHub Actions workflow does the audit pass. Findings are filed as issues on the target repo, with stable identities so the same finding does not get refiled on every run. Local models are a first-class path, so the audited code does not have to leave hardware you own.

The version you can install today is v0.1.0-alpha.2. It is an alpha. The audit loop is real and has been run end to end against a live repository, but the contract is not stable and the rule packs are not yet ready for production. We are publishing it now so that real-world feedback can shape what lands in v1.

## What Sentinel does

The high-level shape is the same regardless of how you tune it:

1. **You install Sentinel into a GitHub organisation.** `npx @nanocollective/sentinel init` scaffolds the config and a GitHub Actions workflow.
2. **You write rule packs.** A pack is a set of rules that describe what to look for in a given repo or set of repos. Sentinel ships no rule packs of its own; the value comes from the packs the installing organisation writes for the code it actually ships. Security scanning, code-style audits, compliance checks, internal-best-practice review: anything that can be expressed as "look at this file and tell me whether X holds" is a fit.
3. **The workflow runs on a schedule.** A scheduled GitHub Actions workflow invokes the audit, which uses Nanocoder (or a local model of your choice) to produce a structured list of findings.
4. **The filer turns findings into issues.** Each finding is filed against the target repo as a labelled issue. If the same finding is seen again, it is not refiled; the existing issue is updated. If a finding has not been seen in N runs, the issue is auto-closed.
5. **A human acts on the issues.** Sentinel does not rewrite code or open PRs. It is a triage layer, not a fixer.

Everything below walks through the parts of that loop in more detail.

## The audit loop

The audit step is a Nanocoder run against the target repo. You give it a rule pack, the repo, and the model you want to use. It returns a JSON array of findings. Each finding has a rule, a file, a category, a human-readable description, and a line range. The line range is recorded for the human reader but is not part of the finding's identity; see the section on dedup below for why.

A run can produce a long array. The parser knows how to handle a truncated model response: the leading complete findings are recovered, the truncated tail is dropped, and the run summary flags the truncation so it is not silent. A validation failure in the audit itself is surfaced in the preview of any subsequent dry run, so a broken pack is visible before you point a live run at it.

## Dedup: why `rule + file + category` is the identity

Every scheduled run produces a fresh batch of findings. The thing standing between a clean run and a torrent of duplicate issues is a stable identity per finding. If that identity is unstable, the filer cannot tell a new finding from one it already filed, and the issue tracker fills up.

The identity we use is `rule + file + category`. That is the part of a finding that is stable across runs: the rule that raised it, the file it lives in, and the category it belongs to. Line ranges sounded precise, and they are, but they are also exactly the kind of thing models report inconsistently between runs. The same finding, run twice, would come back with `42-47` one time and `43-48` the next. Each variant would get a different hash, the dedup store would treat them as two different findings, and the filer would refile the issue. Using `rule + file + category` keeps the identity stable.

If you have tuned `sentinel.yaml` to suppress specific content hashes from an earlier build, you will need to re-derive them from the new identity the next time a finding is filed. The run summary logs the new identity per finding so it is straightforward to capture.

## Filing on a fresh repo

The filer needs a small set of labels to apply to the issues it opens: `sentinel` plus the suppression labels. On a fresh repo, none of those labels exist yet. The filer creates the ones it needs before the first issue is filed, and tolerates the case where they already exist. A first run on a new repo lands cleanly without manual label setup.

Individual `gh issue create` / `gh issue edit` / `gh issue close` calls can still fail for reasons that have nothing to do with the finding itself: transient API errors, a label race, a permission hiccup. Each create/update/close is tolerated individually, the failure is logged, and the run continues. The run summary at the end lists which findings failed to file and why. The operational cost of one transient failure is no longer "open the workflow logs and re-run the entire batch".

## Auto-resolution

Some findings stop being true. A vulnerability is fixed, a style violation is cleaned up, a compliance rule is no longer relevant. The filer can close the corresponding issue automatically if the finding has not been seen in N scheduled runs. The default is conservative: a finding has to be missing for several runs in a row before the issue is closed, on the assumption that a single missed run is more likely a flaky check than a resolved finding. Some teams want a tighter loop, some want a looser one, and some want it off. `--resolve-after-misses <N>` on `sentinel run` is the knob. The default is unchanged for existing installs.

## Dry-run

Before pointing a live run at a repo, you can preview what would be filed. The dry-run mode prints a grouped preview: would-file-as-new, would-match-dedup, would-skip-below-threshold. If a pack fails validation, the failure surfaces in the preview itself, with the reason and the run that produced it. You see that a pack is broken before you commit to a live run.

## What Sentinel does not do

Sentinel is a triage layer. It does not rewrite code, open PRs, or push fixes. It does not ship rule packs. It does not, on its own, decide what counts as a bug worth filing; that is what the rule packs are for, and writing them is the work the installing organisation does. The audit loop is a model in a workflow, and the model is what the model is: a model. The findings are a starting point for a human review, not a verdict.

This is intentional. The judgement about what to fix, in what order, and how, stays with the people who own the code.

## Install

```bash
npx @nanocollective/sentinel@0.1.0-alpha.2 init
```

`init` scaffolds the config, the workflow, and a starter `sentinel.yaml`. It is idempotent for existing files and will refresh the workflow to pick up the latest filer if you re-run it.

## What is coming

V1.0 is the goal. The contract for the audit loop, the rule pack format, the filer, and the auto-resolution knobs should not change between now and v1 unless a real install breaks. The rough edges we have found so far, including the rare case where two rules in the same pack produce identical `rule + file + category` identities, will be addressed in the next alpha. The most useful thing you can do to shape v1 is run Sentinel against your own repos and tell us what breaks. We are testing on our own repos and a handful of external projects at this stage.

Expect breaking changes between alphas. If you want your project audited as part of that loop, get in touch on Discord.

## Links

Repo: https://github.com/Nano-Collective/sentinel

Docs: https://docs.nanocollective.org/sentinel/docs

Built by the [Nano Collective](https://nanocollective.org): a community collective building AI tooling not for profit, but for the community.


Introducing Sentinel: a Nanocoder-driven audit workflow for your GitHub org


We are publishing the first public build of Sentinel, the Nano Collective's Nanocoder-driven workflow for running continuous, configurable security and code audits across the repositories in a GitHub organisation and filing the findings as issues for a human to act on. The version you can install today is v0.1.0-alpha.2.

Sentinel is a triage layer. You install it into your org, point it at the repos you care about, and write the rule packs that describe what to look for. A scheduled GitHub Actions workflow does the audit pass, and each finding is filed against the target repo as a labelled issue. The same finding is not refiled on every run; the existing issue is updated. If a finding has not been seen in N runs, the issue is auto-closed. Local models are a first-class path, so the audited code does not have to leave hardware you own.

A few of the things that have shaped this first public build:

- **Stable dedup.** The finding identity is `rule + file + category`. Line ranges are recorded for the human reader but are not part of the identity, because models tend to drift on line ranges between runs.
- **Works on a fresh repo.** The filer creates the labels it needs (`sentinel` and the suppression labels) before the first issue is filed, and tolerates the case where they already exist.
- **One bad issue call does not abort the run.** Each `gh issue create` / `edit` / `close` is tolerated individually, logged, and the run continues. The run summary lists which findings failed to file and why.
- **Dry-run is honest.** If a pack fails validation, the failure surfaces in the preview, with the reason and the run that produced it.
- **Truncated model output is salvaged.** A long audit run that comes back with the JSON array cut off mid-finding is recovered: the leading complete findings are filed, the truncated tail is dropped, and the run summary flags the truncation.
- **Tunable auto-resolution.** `--resolve-after-misses <N>` on `sentinel run` controls how many runs a finding has to be missing before its issue is auto-closed. The default is conservative.

Sentinel is an alpha. It ships no rule packs of its own; the value comes from the packs the installing organisation writes for the code it actually ships. We are testing on our own repos and a handful of external projects at this stage. Expect breaking changes between alphas. If you want your project audited as part of that loop, get in touch on Discord.

Install:

`npx @nanocollective/sentinel@0.1.0-alpha.2 init`

Repo and full notes: https://github.com/Nano-Collective/sentinel

Built by the Nano Collective: a community collective building AI tooling not for profit, but for the community.



Introducing Sentinel alpha v0.1.0-alpha.2: a Nanocoder-driven workflow for running scheduled security and code audits across a GitHub org and filing findings as issues. Stable dedup, fresh-repo labels, tunable auto-resolution. https://github.com/Nano-Collective/sentinel



Most privacy tools bundle the network layer. prompt-scrub won't. It scrubs text and gets out of the way, so your VPN, Tor, or relay stays yours. scrub, send, rehydrate. The boundary is the design.


A custom tool should be one file, not a plugin. nanocoder's tools are .md with a Zod-style input schema, shell-quoting, and an approval policy. Drop it in .nanocoder/tools/, restart, the model calls it.



90 minutes into training and the loss curve went sideways. It wasn't the model. It was the data: duplicate rows, broken turn alternation, missing context messages, all silent. nanotune data validate catches them in seconds, before the hour-long run is wasted.



Generic identifiers like count or id would flood your session map with junk matches. prompt-scrub's CodeTellDetector is dormant by default for that reason. Pass --code-tell-terms with the names you treat as sensitive and it scrubs only those. One flag, your detector.


Most open-source orgs won't tell you what's in the fund before you commit a weekend. The Nano Collective charter does: community fund is a mechanism, not a balance, bounty capacity today is effectively zero. You know the shape before you invest.



Glue code isn't a step in the pipeline, it's a tax. `getmd --sitemap <sitemap-url>` walks it, recurses nested indices, filters by globs, and writes one .md per page. Docs site to LLM-ready corpus, one command.


A migration throws and the stack trace tells you nothing about which field broke. json-up's ValidationError carries a Zod issues array, so error.issues.forEach(i => console.error(i.path.join('.'), i.message)) prints the exact path and message - the catch tells you what to fix.



A 4B model forgetting the question by the second tool call isn't a model problem. It's a prompt problem. Nanocoder's `/tune` `nano` profile shrinks the system prompt from ~700 to ~150 tokens and drops MCP tool sprawl, which is why a small model can actually finish the loop.



87% pass rate told me almost nothing. Nanotune's Markdown report groups failures by category. One bucket had every miss, and that was the next training row to write.



A URL with a token in it isn't a URL. prompt-scrub's collision chain picks SecretDetector over UrlDetector when spans overlap, so the bearer gets scrubbed as a secret, not a link. Missing a credential is treated as strictly worse than misclassifying a path.



We updated the headline description of Nanocoder. This post explains why (the thinking behind the change, what the old framing was getting wrong, and what the new one gets right).

## The short version

**Before:** "A local-first CLI coding agent..."

**After:** "A coding agent in your terminal, running on any model you choose (local models via Ollama, or any OpenAI-compatible API such as OpenRouter, Anthropic, and Google)."

The principles didn't change. The emphasis did, so the description matches both how the tool is actually used and why it exists at all.

## What was wrong with the old framing

"Local-first" was the first thing you read about Nanocoder. It was the noun that defined the product. That created two problems.

**Problem one: it reads as local-only.** In practice, the Nanocoder harness is used heavily against cloud models (OpenRouter, Anthropic, Google, and more). "Local-first" as the headline undersold a significant part of what the tool actually is. Users who primarily used cloud providers felt like second-class citizens. Users who hadn't tried it assumed it didn't support their use case. Neither was true.

**Problem two: it buried the real differentiator.** The strongest thing about Nanocoder isn't that it's local. It's that it's built by a community collective, not a company. No paid tiers. No telemetry. No vendor lock-in. No investor-driven roadmap. The people building it are the people using it, and the direction is shaped by contributors rather than executives.

"Multi-provider on principle" is a *consequence* of being community-built. A collective has no commercial incentive to lock you to one vendor's model, so it doesn't. That story was getting crowded out by the local-first headline.

## What "local-first" means in the collective's framing

This is not a retreat from local models. We support them. We prioritise them. We are actively investing in making them better (including through Nanotune, a separate project working to make small local models genuinely good at coding tasks).

The Nano Collective defines local-first as a spectrum: *on-device by default, with privacy-preserving bridges to external capability when a task genuinely requires it.* Supporting cloud providers doesn't violate local-first. The old copy implied a purity the tool never claimed.

The three collective principles are held together, in fixed order: **privacy-respecting, local-first, open for all.** The old copy elevated one of the three and dropped the other two. The new copy keeps all three, in order, as a description of the collective, and lets the product copy describe what the product does.

## The honest position on local models today

Local coding models aren't yet at parity with the best cloud models for every task. We're working to close that gap. We don't oversell where it stands today.

Local-first is a direction we are committed to and investing in, not a limitation we impose on users today. Cloud support is how we stay useful while the local ecosystem catches up, and helping it catch up is part of the mission.

## The differentiator that can't be copied

Features can be copied. The ownership model cannot.

Most AI tooling is built by companies whose incentives diverge from their users'. Nanocoder is built by the people who rely on it, in the open, under permissive licenses, with the direction shaped by contributors rather than investors.

That single fact (who builds it and why) is what shapes every other decision. No paid tiers, no telemetry, no vendor lock-in, no roadmap steered by what monetises best. Everything else flows from it.

This is why we lead with "built by a community collective" rather than "local-first". The community collective approach is the point.

---

*Built by the [Nano Collective](https://nanocollective.org). A community collective building AI tooling not for profit, but for the community.*

Why we updated how we describe Nanocoder


We changed the headline description of Nanocoder. Not because the tool changed (the principles are the same), but because the old framing was doing the product a disservice.

Previously: "A local-first CLI coding agent."

That reads as local-only, even though the tool has always supported cloud models via OpenRouter, Anthropic, Google, and any OpenAI-compatible API. We were underselling half of what it actually is.

The new framing: "A coding agent in your terminal, running on any model you choose (local models via Ollama, or any OpenAI-compatible API)."

Local-first is still a core commitment. We're actively investing in it, including through separate work on Nanotune, which is pushing small local models to be genuinely good at coding tasks. But local-first is one of three principles the collective holds (privacy-respecting, local-first, open for all), not the only one. The old copy elevated one principle and dropped the other two.

The deeper reason for the shift: the real differentiator for Nanocoder isn't that it's local. It's that it's built by a community collective, not a company.

No paid tiers. No telemetry shipping your prompts elsewhere. No investor-driven roadmap steering what gets built toward what monetises best. No lock-in to one vendor's model. The people building it are the people using it, and the direction is shaped by contributors, not executives.

That ownership model is why Nanocoder can genuinely support any model, because a community collective has no commercial incentive to lock you to a specific vendor. Multi-provider support isn't a feature; it's a consequence of the structure.

Local-first is a direction we're committed to and investing in. Cloud support is how we stay useful while the local ecosystem catches up, and helping it catch up is part of the mission.

Built by the Nano Collective. A community collective building AI tooling not for profit, but for the community.

→ https://nanocollective.org


Different isn't a feature. It's who builds it. Built by a community collective, not a company: no paid tiers, no telemetry, no lock-in. That's why it runs on any model. The ownership model is the moat. → https://nanocollective.org

Choosing your Nanocoder extension point


Nanocoder v1.27.0 gives you three distinct surfaces for adding custom behaviour. Custom commands, Custom Tools, and MCP servers each solve a different problem and map to different trade-offs. Picking the right one from the start saves you retrofitting work later.

This post maps all three, with concrete guidance on which to reach for and when.

## The three extension surfaces

### Custom Commands: prompt injection

A custom command is a markdown file in `.nanocoder/commands/` that defines a reusable prompt. When you invoke it with `/my-command`, the file body gets injected into the system prompt as context. Nanocoder then responds as it normally would, without running any external code.

**What you get:**
- Named slash command (`/my-command`)
- Parameter substitution via named placeholders
- Auto-injection via `triggers` or `tags` keywords
- Namespacing via subdirectories (`refactor/dry.md` becomes `/refactor:dry`)

**What you do not get:**
- Execution. The prompt is context only. If your command says "run this script and return the output", the model will describe what it would do rather than actually running it.
- Tool access by default. The model has its normal tool set, but the command itself does not grant a new tool.

**Use custom commands when:** you want to encode a pattern or convention that the model should follow consistently, or to parameterise a frequently-typed prompt. Examples from the docs: a test-convention command that reminds the model about AVA framework rules, or a dry-refactor command that encodes your team's extraction approach.

**Do not use custom commands when:** you need something to actually run. For that, you need Custom Tools or MCP.

### Custom Tools: shell-quoted markdown

A Custom Tool is a markdown file in `.nanocoder/tools/` (project) or `~/.config/nanocoder/tools/` (personal). It declares an input schema in YAML frontmatter and writes a shell command body. The model can call it like any built-in tool. Parameters are validated against the schema, the body is rendered with substitutions, and stdout is returned to the model.

**What you get:**
- A first-class tool callable by the model, confirmed by you
- JSON Schema-style parameter validation (types, required, pattern, minLength, etc.)
- Shell-quoted substitution (named placeholders and conditional sections) - all values are POSIX-shell-escaped, blocking injection through parameter values
- `approval` and `read_only` flags that participate in mode policy
- Registration into the same `ToolManager` registry as built-ins and MCP tools - visible via `/tools`

**What you do not get:**
- A persistent external process. Each invocation spawns a shell, runs the command, returns.
- The full MCP protocol (capabilities, notifications, structured schemas from the server).

**Security model:** the tool runs with your full shell privileges. The trust boundary is "you wrote this file or you trust the repo it came from." Parameter values are shell-escaped, but the body is whatever you wrote. Treat project-level Custom Tools the same way you treat `.nanocoder/commands/`, `.envrc`, or `package.json` scripts.

**Use Custom Tools when:** you have a CLI that produces useful output (kubectl, gh, jq, curl, a custom shell wrapper) and you want the model to call it with parameterised input. The sweet spot is project-local helpers that do not need their own process or state between calls.

**Do not use Custom Tools when:** the tool needs to maintain state between calls, spans multiple rounds of interaction without Nanocoder, or is something you want to share across multiple Nanocoder installations. For those cases, reach for MCP.

### MCP servers: external process + full protocol

An MCP server is a process you configure in `.mcp.json` (project) or `~/.config/nanocoder/.mcp.json` (personal). Nanocoder communicates with it via the Model Context Protocol over stdio, HTTP, or WebSocket. The server advertises its available tools; Nanocoder registers them alongside built-ins.

**What you get:**
- A persistent external process with its own state
- Structured tool schemas defined by the server
- Full MCP protocol (capabilities, server-side tool resolution)
- HTTP and WebSocket transports for remote servers
- `alwaysAllow` per-server tool-level configuration

**What you do not get:** automatically. The same is true of any external tool. You are responsible for the server's availability, its auth setup, and its resource usage.

**Use MCP when:** the capability you need is maintained outside Nanocoder (a database, a remote API with session state, a code indexer that maintains an on-disk cache), when you want to share the integration across multiple AI tools, or when the server ships a well-defined tool schema that changes without you having to edit a markdown file.

**Do not use MCP when:** a simple shell wrapper would do the job. If the integration is project-local, stateless, and callable as a one-liner, a Custom Tool is lighter and has no separate process to manage.

## The decision matrix

Here is the short version for common cases.

**You want the model to follow a convention or pattern consistently.**
Custom command. Put it in `.nanocoder/commands/` and invoke via slash command or trigger.

**You want the model to call a CLI tool and get structured output back.**
Custom Tool. Drop a `.md` file in `.nanocoder/tools/`, write the shell body, confirm execution.

**You want a tool that maintains state between calls or needs its own process.**
MCP server. Configure it in `.mcp.json`. Use stdio for local, HTTP or WebSocket for remote.

**You want to package a command, a subagent, and a tool together as one shippable unit.**
Skills bundle. Put them in `.nanocoder/skills/<name>/` with a `skill.yaml` manifest. The subagent automatically sees its sibling tools, scoped tools stay hidden from the global list, and commands auto-namespace.

## One concrete example

Suppose you have a `kubectl`-based workflow: list pods, tail logs, describe a resource. With a Custom Tool:

```markdown
---
name: k8s_pods
description: List pods in a Kubernetes namespace
parameters:
  namespace:
    type: string
    required: true
    pattern: '^[a-z0-9-]+$'
    maxLength: 63
approval: never
read_only: true
---
kubectl get pods -n my-namespace
```

The model can call `k8s_pods({ namespace: "default" })` directly. Parameters are validated, the shell-quoted substitution prevents injection, and stdout comes back as a tool result. No separate process, no MCP config, no server to maintain.

The same workflow over MCP requires a running server process, a `.mcp.json` entry, and the server's own tool schema. That is the right trade-off when the server maintains state you need (a cache, a session, an index) or when you are sharing it across tools. It is the wrong trade-off for a stateless shell wrapper that only needs to exist while Nanocoder is running.

## Modes and tool availability

Custom Tools have explicit mode behaviour. Plan mode only allows `approval: never && read_only: true` tools. Scheduler (cron) mode also requires `approval: never`. MCP tools have their own `alwaysAllow` configuration in `.mcp.json`, independent of the Custom Tool approval flags.

Custom commands are always available. They are prompt injection, not tool calls, so mode restrictions do not apply to them.

## Project vs personal

Custom commands, Custom Tools, and single-file skill members live in both project-level (`.nanocoder/`) and user-level (`~/.config/nanocoder/`) directories. Project-level files take precedence by name. MCP servers follow the same precedence: project `.mcp.json` overrides the global one.

For Custom Tools specifically, project tools shadow personal tools by name. This lets a team ship a standard set of tools with the repo while allowing individuals to override or extend with their own.

## Getting started

- `/commands create <name>` - scaffold a custom command with AI help
- `/tools create <name>` - scaffold a Custom Tool with AI help
- `/setup-mcp` - interactive MCP server configuration
- `/skills` - list everything loaded (commands, agents, tools, subscriptions)

Docs at https://github.com/Nano-Collective/nanocoder - or dive straight into the docs:
- Custom Commands: https://docs.nanocollective.org/nanocoder/docs/v1.27.0/features/custom-commands.md
- Custom Tools: https://docs.nanocollective.org/nanocoder/docs/v1.27.0/features/custom-tools.md
- MCP: https://docs.nanocollective.org/nanocoder/docs/v1.27.0/configuration/mcp-configuration.md
- Skills: https://docs.nanocollective.org/nanocoder/docs/v1.27.0/features/skills.md

Built by the [Nano Collective](https://nanocollective.org) - a community collective building AI tooling not for profit, but for the community.


Nanocoder v1.27.0 ships three distinct surfaces for adding custom behaviour. Most users reach for one and then discover they picked the wrong one partway through. Here is the short map.

**Custom commands** - prompt injection, no execution. Put a markdown file in `.nanocoder/commands/`, invoke via `/my-command`, and the body gets injected into the system prompt. Good for encoding conventions and patterns. Not for running anything.

**Custom Tools** - model-callable shell scripts. A markdown file in `.nanocoder/tools/` with YAML parameter schema and a shell body. The model calls it like a built-in tool. Parameters are validated and shell-quoted. Good for wrapping CLIs (kubectl, gh, jq) with parameterised input.

**MCP servers** - external process with full protocol. Configure a persistent process in `.mcp.json`. Nanocoder communicates over stdio, HTTP, or WebSocket. The right choice when the integration needs to maintain state between calls or when you are sharing it across tools.

Most confusion comes from Custom Tools vs MCP. If it is a stateless shell one-liner, use a Custom Tool. If it needs its own process or maintains state, use MCP.

All three surfaces are skill members. A skills bundle also lets you package a command, a subagent, and a tool together as one shippable unit.

Full decision guide and docs links at the repo: https://github.com/Nano-Collective/nanocoder

Built by the [Nano Collective](https://nanocollective.org) - a community collective building AI tooling not for profit, but for the community.


A decision that comes up a lot in Nanocoder's GitHub discussions: when do you reach for a custom command, a Custom Tool, or an MCP server? v1.27.0 ships all three, and they are easy to mix up.

Here is the short version:

A **custom command** is a prompt you inject into context. It lives in `.nanocoder/commands/`, becomes a slash command, and is just text as far as Nanocoder is concerned. No execution happens. Good for encoding conventions - things you want the model to remember and follow consistently. Bad if you need something to actually run.

A **Custom Tool** is a shell script with a YAML parameter schema. Drop it in `.nanocoder/tools/`, the model calls it like any built-in, and stdout comes back as a tool result. Parameters get validated against the schema and shell-quoted to prevent injection. This is the right level for wrapping CLI tools - kubectl, gh, jq, your own wrapper scripts. No separate process to manage.

An **MCP server** is a persistent external process configured in `.mcp.json`. Nanocoder talks to it over stdio, HTTP, or WebSocket. You get the full MCP protocol, persistent state, and structured schemas from the server. This is the right choice when the tool needs to maintain state between calls, or when you want to share the integration across multiple AI clients.

The most common mistake is reaching for MCP when a Custom Tool would do. If your integration is a stateless one-liner - run kubectl, get output, done - a Custom Tool is lighter and simpler. MCP is worth the extra config when you need the server's process and state.

All three are skill members. If you want to ship a command, a subagent, and a tool together as one bundle, the skills bundle form puts them in `.nanocoder/skills/<name>/` with a `skill.yaml` manifest.

Docs for all of it: https://github.com/Nano-Collective/nanocoder

Built by the [Nano Collective](https://nanocollective.org) - a community collective building AI tooling not for profit, but for the community.


Nanocoder v1.27.0: three extension surfaces. Custom commands (prompt), Custom Tools (shell), MCP servers (process). Stateless CLI = Custom Tool. Needs process/state = MCP. Guide: https://github.com/Nano-Collective/nanocoder


You start a bounty Monday. Wednesday the charter revises. Are your terms still your terms?

The Nano Collective commits to 30 days notice on changes and applies them to new work only. Started under yesterday's terms, those terms hold.


Most get-md installs skip node-llama-cpp. Since v1.4.0 it's an optional peer, not a direct dep - so the ~95% who only need convertToMarkdown skip hundreds of MB of native binaries. Use the LLM path? A clear error points at the install command.


Version 0 is a real state, not a missing field. In json-up, JSON without a version key reads as v0 - so legacy data runs every migration on first load. No special branch for the unversioned case, the upgrade path just starts at zero.



A skill that knows its own parts.

Nanocoder bundle skills ship a subagent, its tools, and a command under one skill.yaml. The agent auto-sees its sibling tools, and tools default to scoped - only that agent sees them.

One artifact. No cross-references to maintain.


Fine-tuning is the easy part. Getting llama.cpp to compile so you can actually run the model is the part that ends the project. nanotune export downloads pre-built binaries, fuses the LoRA, writes a GGUF. One command.


A privacy tool you route traffic through protects your IP. prompt-scrub isn't that. It rewrites the text of your prompts locally - emails, paths, secrets become `Email_1` - and never sees your headers, IP, or timing. Bring your own network layer if you need it.



A default rule pack would have to be wrong about most codebases. Sentinel ships the format, authoring guide, and worked examples instead. Your pack knows your repo. Ours couldn't.


A Nano Collective whitepaper merges. Easy to read that as 'we're building this.'

Merge only means the thinking is good enough to publish. Build is a separate Stage 3 gate, rationale on the page even for a yes. Deliberate departure from the old pattern.


You paste a docs page through a converter and the Mermaid blocks vanish. get-md keeps the fences and recovers rendered SVGs back to source - on by default, no flag to remember.


The discipline of writing both, even when only the schema changes, is what stops a 'just bump the version' edit from quietly corrupting old data. json-up makes the up function mandatory. The schema alone was never the migration.



Editor integrations shouldn't be bespoke. Nanocoder's ACP server speaks the same JSON-RPC protocol Gemini does, so any editor that implements it can host a session. Run nanocoder --acp, point your client at it, and your tools, modes, and history come with you when you switch.



Validation loss climbing while training loss drops isn't progress. It's overfitting. Nanotune's training display shows both side by side, so you see the gap. The fix: cut iterations (150 to 100 to 75) or learning rate (5e-5 to 2e-5), and the next benchmark run reflects it.



A leaked token in your prompt is a 3am incident. A missed email is a bug. So prompt-scrub puts SecretDetector above Email, Url, and Path. If a URL carries a credential shape, the token wins and the URL is rewritten around it.


Four tiers, not three. Sentinel rates findings low, medium, high, critical, with confidence on a separate axis. A high-confidence "low" and a low-confidence "critical" both exist, and the gap between them is exactly where bad alerts live.


The community fund holds $0. The $30 payout minimum is bigger than the pool. The Nano Collective publishes the empty ledger in its charter so a maintainer is straightforward about what is and isn't fundable today.


Most sitemap crawlers trust whatever the index returns. Run one against a big ecommerce sitemap and you find out where the brakes are not. get-md ships with depth caps, URL caps, and glob filters built in. A runaway crawl is exactly the surprise it refuses to ship.


"migration failed" in your logs tells you nothing. json-up throws ValidationError, MigrationError, VersionError - ValidationError carries the version and Zod issue path, so the log reads `settings.theme: invalid_enum_value`. The difference between fixing it and guessing.


# Nanotune v1.6.0: Nanotune works without a terminal

Built by the [Nano Collective](https://nanocollective.org), a community collective building AI tooling not for profit, but for the community.

This release is the smallest in a while and the one most people will feel. Up to 1.5.x, every Nanotune command crashed when `stdin` was not a TTY. That included commands that never needed a keypress, like `status`. A 40-line React reconciler stack trace, exit code 1, no output. v1.6.0 fixes the underlying assumption and makes every command usable from CI, pipes, Docker (without `-t`), and shell scripts.

## Pipe, redirect, and CI without a terminal

Ink enables raw mode as soon as a component calls `useInput`. Nanotune was calling `useInput` for keyboard hints across the whole TUI, which meant raw mode was turned on for every command, including ones that did not need it. Piping `nanotune status` into `tee run.log`, or running it inside a CI step, has always produced something like:

```
ERROR Raw mode is not supported on the target process.
```

The fix is in `src/lib/tty.ts`. Every command now detects whether a keyboard is available and behaves accordingly.

### Render-and-exit commands

`status`, `data validate`, `train`, `export`, `benchmark`, and `judge test` render their output and exit on their own when there is no TTY, instead of parking on a "press any key" frame forever.

Two important consequences:

- **Non-zero exit codes on failure.** A failed run now sets exit code 1, so `nanotune train && nanotune export` chains correctly and CI can gate on `nanotune data validate`.
- **Keyboard hints are suppressed.** Captured output is clean.

A pipeline like this now works end to end:

```bash
nanotune data validate && nanotune train && nanotune export
```

### Interactive-only commands

`init`, `data add`, `data list`, `chat`, and `judge configure` genuinely need a keyboard. They now print a single clear sentence and exit 1, instead of crashing:

```
`nanotune chat` needs an interactive terminal.
stdin is not a TTY, so it cannot read keypresses. Run it directly in a
terminal rather than through a pipe, a CI job, or with stdin redirected.
```

Pairing the diagnostic with a non-zero exit code means CI jobs catch the misuse rather than carrying on.

## `nanotune data import --yes`

New `-y, --yes` flag skips the confirmation prompt, making `data import` usable from scripts and CI:

```bash
nanotune data import examples.jsonl --yes
```

Without a TTY and without `--yes`, the command explains that the flag is required rather than failing obscurely.

## Fixes

- **Platform check now fires up front.** The Apple Silicon assertion only ran inside `installLlamaCpp`, so users on Linux or Intel Macs hit a confusing `pip install mlx-lm` resolver error during `train` instead of the clear message that already existed. `train` and `export` now assert supported hardware before doing any work. Extracted to `src/lib/platform.ts`.
- **`judge.json` is written with `0600` permissions.** The file can hold a literal API key for users who do not use the `${ENV_VAR}` form. Existing configs written by earlier versions are tightened on next save.

## Documentation

- **`nanotune chat` is documented.** The 1.5.0 headline feature shipped with no docs page. Added `docs/commands/chat.md` covering slash commands, all flags, per-turn stats, and chat-template handling, and listed it in the commands index.
- **Quick start covers `chat`** as step 5, between export and benchmark.
- **`data import --yes` documented** in the data command reference.
- **Fixed the benchmark preset table**, where the max-tokens column read 50/100/150/200 instead of the actual 128/256/512/1024.

## Internals

- **Coverage now reports an honest number.** The `c8` `exclude` pointed at `source/app/App.tsx`, a path that has never existed, and spec files were counted as covered source, trivially 100%. Excluding them moves the reported figure from 88.62% to 78.97% with no change in actual test coverage. The point of the bump is honesty, not aesthetics.
- New `src/lib/tty.ts` (raw-mode detection) and `src/lib/platform.ts` (hardware assertion), both pure and unit-tested.
- New `useKeyInput`, `useAutoExit`, and `ExitHint` in `src/components/`. `useKeyInput` is now the only sanctioned way to read keys. Calling Ink's `useInput` directly reintroduces the crash.
- **239 tests total (+16)** covering raw-mode detection, platform assertions, and judge config file permissions.

## Toolchain

- Dependency updates via Dependabot: `ai` 7.0.15, `@ai-sdk/anthropic` 4.0.8, `@ai-sdk/google` 4.0.8, `ink` 7.1.0, `ava` 8.0.1, `c8` 11.0.0, `knip` 6.24.0, `tsx` 4.23.0, `typescript` 6.0.3, `@types/node` 26.x, `@biomejs/biome` 2.5.1.
- Repaired a broken `pnpm-lock.yaml` and several latent toolchain breaks in CI.
- Resolved Biome config deprecations and Semgrep findings.

## Install

```bash
npm install -g @nanocollective/nanotune
```

Full source, issues, and the changelog are on the project repo at [github.com/Nano-Collective/nanotune](https://github.com/Nano-Collective/nanotune). If something breaks, open an issue with the command, the output, and your OS, and we will sort it out.


Nanotune v1.6.0: Nanotune works without a terminal


A retrain that just adds more data usually adds the same blind spots.

Nanotune's benchmark report lists every missed test by id, so the next round writes examples for those exact cases. Each loop closes a named gap instead of guessing what the model still needs.



Most open source projects chain a maintainer to a repo until they burn out, then let them slip away in silence. The Nano Collective does the opposite: stepping back, going quiet, or rotating off is built in. The chair is borrowed, not owned.



A PDF through a converter usually means a flag, or a per-format branch in your script. `cat doc.pdf | getmd` skips the negotiation. It sniffs the `%PDF` magic bytes and routes to the right extractor. One CLI for HTML, PDF, DOCX, Markdown. Less branching in the script.


A 1B model burns a quarter of its context window on the system prompt.

The nano tune profile shrinks nanocoder's prompt from ~500-700 tokens to 150-250, and drops find_files, list_directory, subagent delegation. Context freed for the code.


A custom identifier in your code is the one thing a regex won't catch. Generic terms on a code payload return noise, so prompt-scrub keeps CodeTellDetector off by default and a no-op. Pass codeTellTerms and it scans only your list, the way a private detector should behave.


The migration runs, the next schema rejects the output, and the stored JSON is silently trust-me-broken. json-up runs Zod against every up() and throws ValidationError with issues pointing at the exact path, so the failing field is the message - not a generic migration failed.


How Nanocoder's daemon replaces the scheduler

Nanocoder v1.27.0 removes the old scheduler module entirely. What replaced it is a per-project background daemon that handles two event kinds (`file.changed` and `schedule.cron`) for skill subscriptions. This post walks through the daemon's architecture, the design decisions behind it, and what changed from the old model.

## Why a daemon, and why now

The scheduler that shipped in earlier Nanocoder versions ran as part of the interactive TUI process. That meant file watching and cron ticked only when you had the TUI open, and each triggered run shared the TUI's development mode (typically `ask` or `plan`). There was no way to run a subscription autonomously, and the scheduling state lived in a separate `.nanocoder/schedules.json` file that nothing else read.

v1.27.0 replaces this with a long-lived background process that owns the event loop for subscriptions. It runs independently of the TUI, installs as a user-level service on macOS and Linux, and executes triggered runs in `headless` mode by default (autonomous, no foreground prompts).

## Lockfile: ensuring a single instance

The daemon writes a JSON lockfile at `.nanocoder/daemon.json` on boot. The lock record contains the PID, the Unix socket path, and the start time:

```json
{
  "pid": 12345,
  "socketPath": ".nanocoder/daemon.sock",
  "startedAt": 1748300297000,
  "projectRoot": "/path/to/project"
}
```

Before starting, the daemon reads any existing lockfile. If the PID inside is still alive, the start is rejected with a message pointing at the running instance. Dead PIDs are reaped automatically (using `process.kill(pid, 0)` as a probe), so a crashed daemon does not block a fresh start.

Write atomicity is handled by writing to a sibling `.tmp` file and renaming in place, so a partially-written lockfile is never observable.

On Windows the lockfile path stays the same but the socket becomes a named pipe at `\\.\pipe\nanocoder-daemon-<hash>`, where the hash is a 10-character prefix of the project root's SHA-256. This keeps each project in its own pipe namespace.

## Unix socket IPC

The daemon's IPC surface is a single `AF_UNIX` socket at `.nanocoder/daemon.sock` (macOS and Linux). The protocol is minimal: newline-delimited JSON requests with matching responses.

```typescript
// Request
{"id": 1, "method": "listSubscriptions"}
// Response
{"id": 1, "result": [...]}
```

Supported methods: `ping`, `listSubscriptions`, `shutdown`. The `shutdown` method triggers a graceful event-loop drain (watcher stop, cron stop, IPC server close, lockfile removal) and is the clean path on Windows where `SIGTERM` would otherwise be force-kill.

The socket is removed before each `listen()` call so a stale socket from a previous crashed run does not block startup. The daemon unlinks the socket file on stop as well.

## Event sources: file watching and cron

Two event sources feed the daemon's router. Both start when the daemon boots, not when the TUI opens.

**File watching** uses `chokidar` under the hood. It watches the project root with sensible defaults: `node_modules`, `.git`, and `.nanocoder/` itself are excluded. The last exclusion is deliberate. Triggered runs write checkpoints under `.nanocoder/checkpoints/`, which would otherwise fire `file.changed` events and create a feedback loop. The `.nanocoder/` tree is loaded once at boot and is not hot-reloaded.

Emitted events carry the file path (relative to the project root) and the event kind (`add`, `change`, `unlink`). Subscription-level filtering against `paths` and `eventKinds` happens inside the event router, not in the source, so one watcher serves all `file.changed` subscriptions.

**Cron scheduling** registers with a `node-cron`-compatible timer. Each `schedule.cron` subscription registers its cron expression when the daemon boots. The cron source fires with the scheduled time as the event payload.

## Per-subscription concurrency cap and debouncing

The `BackpressureDispatcher` wraps the skill dispatcher and applies two protections by default, neither of which is configurable in v1.

**Concurrency cap of 1.** If an event arrives for a subscription that already has a run in flight, the new event is dropped. A `git pull` that produces 1,000 `file.changed` events in 200 ms will dispatch one run and drop the other 999, rather than spawning 1,000 parallel subagent processes.

**Trailing-edge debounce, 500 ms.** Applied only to `file.changed` events. Each event resets the timer; on expiry, the most recent event for that subscription is dispatched once. This prevents a linter run that touches 50 files from firing 50 separate triggered runs.

Cron events are not debounced. A cron schedule fires at its configured interval and dispatches immediately without the debounce layer.

## Headless mode vs the removed scheduler

The old scheduler ran inside the TUI process using the same mode the TUI was using. A triggered run would fire in `ask` mode or `plan` mode depending on the TUI's state, with no way to opt into autonomous execution.

The daemon's triggered runs execute in **`headless` mode** by default: no `ask_user`, no `agent` calls, no foreground confirmations. The subagent runs to completion autonomously. A triggered run that needs human review can set `confirm: true` on its subscription, which switches the execution to `plan` mode instead (the subagent proposes but does not apply).

```yaml
# autonomous (headless)
subscribe:
  - kind: file.changed
    paths: ["docs/**"]

# supervised (plan mode)
subscribe:
  - kind: file.changed
    paths: ["docs/**"]
    confirm: true
```

The `modeForSubscription` function in `source/skills/dispatcher.ts` encodes this distinction. It returns `'headless'` unless `confirm: true` is set, in which case it returns `'plan'`.

Checkpoint creation is tied to this choice. The dispatcher skips the checkpoint step for `confirm: true` runs because plan-mode runs make no file mutations that need reverting.

## Lifecycle and operational commands

```
nanocoder daemon start      # fork and detach
nanocoder daemon stop       # graceful drain via IPC, then SIGTERM fallback
nanocoder daemon status     # read lockfile, probe PID, report uptime
nanocoder daemon logs       # tail last 64KB of .nanocoder/daemon.log
nanocoder daemon install    # install launchd/systemd auto-start
nanocoder daemon uninstall # remove the auto-start unit
```

`daemon start` blocks until the lockfile is written. `daemon status` reads the lockfile and probes the PID to distinguish running from stale. Stale lockfiles are reaped silently on any read that finds a dead PID.

The log file is append-only. The default `onActivity` listener writes one line per triggered run: target, mode, event kind, subscription ID, duration, and an optional checkpoint ID or error.

## Migrating from schedules.json

The legacy `useSchedulerMode` hook, the scheduler view, and `.nanocoder/schedules.json` are gone. If the file is present when Nanocoder boots, a loud deprecation warning points at the migration guide.

The migration is a frontmatter edit. Move each cron entry into the targeted command's `subscribe:` block:

```markdown

---
description: Monday morning summary.
subscribe:
  - kind: schedule.cron
    cron: "0 9 * * MON"
---

Summarize last week's commits...
```

After migrating, run `nanocoder daemon start` (or `nanocoder daemon install` for auto-start across reboots) to activate the subscriptions.

The source lives at https://github.com/Nano-Collective/nanocoder. For the full subscription syntax and daemon lifecycle, see the Skills docs.

Built by the [Nano Collective](https://nanocollective.org) - a community collective building AI tooling not for profit, but for the community.


File watchers that only run while your terminal is open aren't file watchers. nanocoder's daemon exists because subscriptions need to outlive the TUI: file.changed and schedule.cron tick on their own clock, install as a user service, run triggered work headless.


Security scanners either ship rules for someone else's stack or hand you an empty editor and leave. Sentinel ships zero rule packs. You write them for the code you actually ship, so the audit is shaped by your team, not a vendor's idea of what matters.


Every hour contributors spend arguing whether a new project is in scope is stolen from something already shipping. Stage 0 at the Nano Collective is a short fit conversation before any whitepaper. The friction that deters serial proposers is what protects the volunteers.



A rendered Mermaid diagram is gone unless the source lives in the DOM. get-md reads it back from the SVG with a strict heuristic, refusing strings like "Created with Mermaid" that mermaid.js writes into a11y nodes. Loose labels are worse than no diagram.


Every migration library we've shipped wanted a one-time import script for pre-migration data. json-up skips the script: input without _version is treated as 0, and the first migrate() runs every step in order. The codebase picks up where it left off, by default.


A fine-tune used to mean renting a box, compiling llama.cpp, and a weekend of YAML. Nanotune targets 0.5B to 1.5B models on a few hundred examples, runs LoRA on Apple Silicon via MLX, and writes GGUF without touching llama.cpp. The laptop you have open is enough.


20+ model providers and you still switch tools every time the API key changes. nanocoder treats them all as one CLI - Anthropic, OpenAI, Mistral, Ollama, vLLM, whatever you have - so you swap vendors without swapping muscle memory.



A path leaks the moment you run `ls`. prompt-scrub takes the whole messages array, so every tool result and outgoing turn is scrubbed, not just the prompt you typed. One hook in the message handler, no rewiring around the LLM call.


An LLM auditor will be wrong. Build for the misses. Sentinel dedups by content hash, takes false-positive labels, and reads a per-repo sentinel.yaml, so dismissing noise is cheaper than living with it.



Two streams, one ledger. Every payment in and every payment out of the Nano Collective lands on a public ledger the moment it is processed. Not-for-profit, no investors. The floor, not a feature. Open the ledger before you donate.


Under 100ms per page, no API key, no rate limit. get-md runs Turndown plus Mozilla Readability locally, so convertToMarkdown() on a URL is a single sync-feeling call. Wire it into a small loop for a long URL list, not a script that round-trips an LLM for every page.



A chain of sync migrations doesn't need Promise overhead. Mark up() async only when it actually awaits - a fetch, a key call. The createMigrations / createAsyncMigrations split keeps a 100-example benchmark from silently doubling its runtime on an unused async keyword.


The Nano Collective crossed 100,000 total downloads across its open-source AI tooling: Nanocoder, Nanotune, get-md, and json-up. The number felt big enough to mark, and small enough to be honest about what it represents.

## What this number is, and what it isn't

A download is a low-friction signal. It does not tell us anything about who installed, what they did with the tool, or whether they kept it. Across four packages, 100,000 of them is still useful information: it tells us that the work is being found, that the install path is working, and that people are willing to put the collective's tooling on their machines.

What it does not tell us is that the model is finished, or that the audience is locked in. It tells us the direction is landing. That is worth pausing on.

## What the collective builds

For anyone encountering the Nano Collective for the first time: it is a community-led group of developers, designers, and maintainers building open-source AI tools for the people who use them. We build not for profit, but for the community.

The packages in scope for this milestone:

- **Nanocoder**, a coding agent in your terminal that runs on any model you choose. The flagship project, and the one that has driven the largest share of installs.
- **Nanotune**, tooling focused on fine-tuning and improving small, local models for practical use.
- **get-md**, a fast, lightweight HTML, PDF, DOCX, and Markdown to Markdown converter optimised for LLM consumption.
- **json-up**, a type-safe JSON migration tool with Zod schema validation.

Everything the collective ships is open. You can audit the code, fork it, contribute to it, or simply run it without an account or a third-party dependency. The [Economics Charter](https://docs.nanocollective.org/collective/organisation/economics-charter) locks in how the collective operates: no investors, no profit-taking, no extraction. Funds cover infrastructure costs and contributor bounties only, and the [Open Collective ledger](https://opencollective.com/nano-collective) publishes every incoming and outgoing payment in real time.

## Why this is a different shape of milestone

The tooling landscape for AI-assisted development has grown rapidly, and a large share of it routes data and prompts through proprietary platforms. That model is a choice, not an inevitability. Local-first, open-source tooling exists as an alternative: one where your code and your queries stay on your hardware, where the behaviour is auditable, and where the community shapes the direction rather than a product team at a company with an IPO to plan.

100,000 downloads across four packages is a sign that this model resonates beyond the early-adopter circle. It is developers and teams making a practical choice: they want tools that work this way. That is the part of the milestone that matters to us, more than the number itself.

## What this milestone does not claim

It does not mean the collective is large. The core team is small, the contributor pool is modest, and there is a long backlog of work that is under-resourced. It does not mean the tools are finished. Each project has open issues that have been waiting for someone to pick them up. It does not mean the operating model is solved. Governance, contributor compensation, and project stewardship all have open questions that the collective is working through in public.

What it does mean is that the work has reached a community large enough to be self-sustaining in spirit: there are enough people using the tools, and enough people willing to push back on direction, that the collective can keep going without an outside funder deciding its priorities. That is the milestone.

## What's next

The work continues, and the priorities for each project live in their own public roadmaps:

- **Nanocoder**, broader model support, deeper terminal integration, expanded skill system.
- **Nanotune**, better defaults for small-model fine-tuning, broader evaluation tooling.
- **get-md**, additional input formats, improved handling of edge cases in real-world documents.
- **json-up**, schema-diff ergonomics, expanded migration primitive coverage.

If you want to contribute, whether through code, docs, design, feedback, or sponsorship, every project has a `CONTRIBUTING.md` and open issues tagged for contribution. The collective's governance and contributor resources are documented at [docs.nanocollective.org](https://docs.nanocollective.org).

If the work is useful to you and you'd like to support it financially, see [Support the Collective](https://docs.nanocollective.org/collective/organisation/support).

## Thanks

Thanks to everyone who has downloaded a package, opened an issue, reviewed a PR, written a doc, shared a project with a colleague, or simply given one of these tools a try. The number belongs to the community that produced it. We are grateful, and we are not going to waste it.

[Nano Collective](https://nanocollective.org)


100,000 downloads, a milestone worth marking honestly


The Nano Collective just crossed 100,000 total downloads across its open-source projects: Nanocoder, Nanotune, get-md, and json-up.

This milestone is not a vanity number. It is a real signal that a model built on local-first, privacy-respecting, open tooling can find a working audience without investors, without an extraction layer, and without a cloud dependency bolted to every keystroke. Each install is someone choosing that model for their own work.

The Nano Collective is community-led and not-for-profit. Everything it ships is open, transparent, and shaped by the people who actually use it. The Economics Charter locks in how the funds flow. The Open Collective ledger shows every payment in real time. None of that is incidental; it is the operating system the work runs on.

100,000 downloads belongs to everyone who installed a package, opened an issue, reviewed a PR, wrote a doc, or pointed a colleague at one of these tools when they needed it. Thank you.

Explore the work: https://nanocollective.org



The Nano Collective just passed 100,000 total downloads across its open-source projects: Nanocoder, Nanotune, get-md, and json-up. Sharing here because this community tends to care about tools that stay open, run locally, and don't route your work through a third-party platform.

**What the Nano Collective is**

For anyone unfamiliar: the Nano Collective is a community-led group building AI tooling that is open-source, privacy-respecting, and local-first. No investors. No profit motive. The [Economics Charter](https://docs.nanocollective.org/collective/organisation/economics-charter) lays out exactly how it operates, and funds go to infrastructure and contributor bounties, nothing else. Everything is visible on the [Open Collective ledger](https://opencollective.com/nano-collective) in real time.

**What the tools are**

- **Nanocoder**, a coding agent in your terminal that runs on any model you choose.
- **Nanotune**, tooling focused on fine-tuning and improving small, local models for practical use.
- **get-md**, a fast, lightweight HTML, PDF, DOCX, and Markdown to Markdown converter optimised for LLM consumption.
- **json-up**, a type-safe JSON migration tool with Zod schema validation.

All open-source, all under the `Nano-Collective` GitHub org.

**Why this milestone is worth noting**

100,000 downloads across four packages is a signal that local-first, open-source AI tooling has a real user base beyond the early-adopter crowd. Developers and teams are making a practical choice: they want tools that stay on their hardware, that they can audit, and that the community shapes rather than a company with an exit to plan.

It is also worth being honest about what the number does and does not mean. It does not mean the tools are finished. It does not mean the collective is large. It means the direction is landing: people are choosing this model for their work, and choosing it at enough volume to keep the project self-sustaining in spirit.

**What we are grateful for**

Every install is the community choosing this model. That belongs to the people who actually use the tools, not to the people who maintain them. We are grateful to every person who has installed a package, opened an issue, reviewed a PR, written a doc, or pointed a colleague at one of these tools when they needed it.

If you want to dig in: https://nanocollective.org



The Nano Collective just crossed 100,000 total downloads across Nanocoder, Nanotune, get-md, and json-up. Open-source AI tooling, built by the community, for the community. Local-first. Privacy-respecting. Thank you to everyone who installed a package. https://nanocollective.org


Sponsorship gets placement, not say. Most projects can't promise that, because investors and paid tiers come with asks. MIT licence, no paid tier, no investor return are written into the Nano Collective's brand and economics charter, not a pricing call.


Default 5 parallel converters sounds fast until your LLM provider starts throttling. `get-md` lets you pull it down with --concurrency 3 and keeps the same JSONL stream and manifest either way.



Your catch knows the migration broke, not which step. json-up tags ValidationError, MigrationError, VersionError with a version, so the log points at the step. MigrationError adds a typed cause, ValidationError the Zod issues array.


Most CLI agents phone home the moment you run them. Nanocoder's default is the opposite: zero install ping, zero usage metrics, zero outbound calls you didn't ask for. Run it against a local model and your network audit shows nothing.


Adding data on instinct burns evenings. nanotune benchmark writes a markdown report with a failed-tests table - read it, then data add examples aimed at those exact failures. Retrain lands on a smaller surface, not the one you guessed at.


0 tokens shipped for an unscrubbed prompt that mentions an `Email_1` placeholder. prompt-scrub runs at the content layer on your machine - local CPU, no API call, no quota - and the session map is just a JSON file on disk. Detection cost is yours, not the network's.



An audit that calls a cloud model is not a private audit. Sentinel's first-class local path (Ollama, LM Studio, llama.cpp, MLX) keeps every byte of audited code on hardware you own. Same workflow, same findings, different threat model.



Most coding agents ship a separate extension per editor. Nanocoder exposes one ACP socket, so any editor that speaks the protocol drives it directly. Zed today, more later. Nothing on the Nanocoder side to keep up.


Most failed training runs are not hyperparameter bugs. They are data bugs caught in seconds. Run nanotune data validate before you queue a training run: bad JSON, missing fields, duplicate examples, broken role alternation, minimum count flag. Cheap to run, expensive to skip.


Most privacy tools want to own your whole stack. prompt-scrub only scrubs text. Pair it with the VPN, Tor, or proxy you already trust, and call rehydrate() at the boundary you control. One primitive, composed on purpose.


An LLM might flag the same issue at lines 4–6 today and 5–5 tomorrow. Sentinel's dedup hash is rule + file + category, not range. The span still shows in the body, but it isn't the finding's identity, so re-audits update, not refile.



A cheap local model that cannot reliably call tools is a dead end. Turn fails, retry, fail again.

Nanocoder tries three paths (native, XML, JSON) and repairs broken output instead of failing the turn.

MCP, subagents, scheduling, Skills still work. No cloud API in the middle.


A model performance question should never be answered on a feeling. Nanotune's loop is train, benchmark, read the markdown report (pass rate, per-test table, failed tests, timing), then data add aimed at the failures the report names, then train again.


Most sponsorship buys influence. The Nano Collective's doesn't. The sponsor page and contributor resources page publish the rule upfront: funding cannot direct what gets built or who gets paid. Logo on the page, nothing at the table. The constraint is the point.



Pipe a file with no useful extension into get-md and it reads the bytes, not the name. `%PDF` on stdin lands it on the PDF branch, anything else falls through to HTML, so a chained shell command becomes Markdown without renaming anything. The filename is the fallback.


Most migration chains make you pick sync or async on day one and rewrite if you change your mind. json-up's async builder accepts both: one step awaits a key, the next copies a field in plain JS. No split builders.



Collision resolution is policy, not a tie-breaker. prompt-scrub states the hierarchy upfront: secrets first, PII second, identifiers third. Asymmetric on purpose. A missed token is a 3am incident. A missed email is a bug.


Paying a cloud model to read 40 files is a bad deal.

Nanocoder subagents can pin their own provider and model. Point one at Ollama, hand it a 3B, and codebase reads run in parallel on your machine. Only the answer comes back to your main conversation.



Open-ended tests usually hand you a number and trust you on the why. Nanotune's llm-judge tests put per-criterion scores and the judge's reasoning in the same markdown report a string-match test shows up in. Auditable in one place, no separate log to chase.


Dismiss a finding once and Sentinel never refiles it. The audit reads the false-positive label and drops it from future runs, so the noise you triaged on Tuesday doesn't reopen itself next Monday.


A rule pack for prompt-scrub is just an npm package. Install it, list it under prompt-scrub.rulePacks, and your detector shows up in `prompt-scrub rules list` next to the built-ins, in priority order. No plugin runtime, no separate loader.


Two systems for one job was the bug.

/schedule wrote schedules.json. Skills already had a place for triggers, so cron moves onto a command's frontmatter or bundle manifest. The JSON file is dropped; the daemon fires it.

confirm: true opts a triggered run into plan mode.


A model with 99% accuracy can still break a coding agent.

Nanotune's benchmark report shows Total Latency, Time to First Token, Generation Time, tokens, and tokens/sec per test. The one that kills workflows is the model that stalls on first byte.



The first live Sentinel run files everything at once. Pick dry-run from workflow_dispatch first. You get the would-file, dedup-would-match, and below-threshold preview in the step summary, and your calibration happens before any issues hit a teammate's repo.



"Is this helpful" is not a feature you build. It is a model you point at criteria. Nanotune writes a judge config once; pass/fail on open-ended responses comes from criteria and passThreshold the model reads. No new code, just a config that names the judge.

Authoring a prompt-scrub rule pack from scratch


# Authoring a prompt-scrub rule pack from scratch

Built by the [Nano Collective](https://nanocollective.org), a community collective building AI tooling not for profit, but for the community.

The release announcement walked through the headline shape of `prompt-scrub`: what `scrub()` and `rehydrate()` do, why determinism matters for prompt cache prefixes, and where the threat model draws the line. A sibling post went deep on the secret detector and how its three layers stack. This post is for the other side of the same coin: how to add a detector that does not live inside the main package. Rule packs are the extension point, and the contract is small enough that you can write, test, and publish one in a sitting.

What follows is a walkthrough aimed at a developer publishing their first custom detector pack: the `Detector` interface as it actually appears in `src/types/index.ts`, the three export shapes the loader accepts, why detectors deliberately do not return a replacement string, and the four integration points you have to wire up (the package, the config, the `rules list` output, and the collision resolver that runs underneath).

## The contract in one screen

The whole rule-pack contract fits on one screen. Two interfaces, both in `src/types/index.ts`:

```ts
export interface Finding {
  category: string;
  span: [number, number]; // [startIndex, endIndex]
  value: string;
  placeholderPrefix: string;
}

export interface Detector {
  name: string;
  detect(text: string): Finding[];
}
```

That is it. A rule pack is an npm package that exports one or more objects implementing `Detector`. Each `detect()` call walks the text, finds zero or more matches, and returns them as an array of `Finding`. There is no constructor signature the loader requires, no base class you have to extend, no registry to register with. The interface is structural: if your object has a `name` and a `detect`, it slots in.

A worked example, trimmed from the existing `EmailDetector` so the shape is concrete:

```ts
import type { Detector, Finding } from '@nanocollective/prompt-scrub';

const EMAIL_REGEX = /(?<![.\w])([a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})(?![.\w])/g;

export class EmailDetector implements Detector {
  readonly name = 'EmailDetector';

  detect(text: string): Finding[] {
    const findings: Finding[] = [];
    EMAIL_REGEX.lastIndex = 0;
    let match: RegExpExecArray | null;
    while ((match = EMAIL_REGEX.exec(text)) !== null) {
      const value = match[1] ?? match[0];
      findings.push({
        category: 'Email',
        span: [match.index, match.index + value.length],
        value,
        placeholderPrefix: 'Email',
      });
    }
    return findings;
  }
}
```

Note what the detector returns and what it does not. It returns `value` (the matched substring) and `placeholderPrefix` (the category namespace, here `'Email'`). It does not return a placeholder like `Email_2`, and the reason is structural, not stylistic.

## Why detectors never return a `replacement`

This is the part of the contract that surprises first-time authors, because every tutorial they have ever read on "how to write a redaction detector" hands them a `Finding` shape with a `replacement` field. The whitepaper for `prompt-scrub` did the same thing. The runtime contract deliberately omits it.

The reason is that the final placeholder has to be deterministic across the whole text, and the number suffix (the `2` in `Email_2`) depends on the session, not on the detector. If a detector returned `replacement: 'Email_1'` for its first match, and then a second detector also returned a match whose placeholder should be `Email_2`, the engine would have a choice between re-numbering detector A's output (which breaks the deterministic-prefix guarantee for prompt caches) or letting collisions sit across detectors. Both options are bad.

The runtime shape splits the responsibility. Detectors say two things: this is the match (`value` plus `span`), and this is what category namespace it belongs to (`placeholderPrefix`, e.g. `'Email'`). The core engine takes that, walks the resolved findings, assigns the numeric suffix per category in span order, and writes `Email_1`, `Email_2`, etc. into the session map. Rehydration gets the mapping back and swaps the placeholders for the originals.

For a rule-pack author this means two practical things:

- Do not invent your own placeholder strings inside `detect()`. The engine will overwrite them or, worse, leave them in place and confuse rehydration.
- Pick a `placeholderPrefix` that uniquely identifies your category in the user-visible output. `Codename` works for a project codename detector; `'ApiKey'` works for a third-party API detector; `'Ssn'` works for a US Social Security number detector. Two detectors that pick the same prefix will produce interleaved numbering, which is what you want.

## The three export shapes

`src/core/rule-packs.ts` accepts a rule pack if its top-level module looks like any of these:

```ts
// Shape 1: a default export that is itself an array of Detectors
export default [new MyDetector()];

// Shape 2: a named export called 'detectors' that is an array
export const detectors = [new MyDetector()];

// Shape 3: a default export that is an object with a 'detectors' property
export default { detectors: [new MyDetector()] };
```

The loader walks them in order: it prefers the named `detectors` export, falls back to a `default` array, falls back to a `default.detectors` array. Anything else is treated as "this package did not export any detectors" and a warning is printed to stderr:

```
[prompt-scrub] Warning: Rule pack "my-pack" did not export any valid detectors.
```

The same warning fires if your object is missing `name` or `detect`. Validation per-item is the check `typeof detector.detect === 'function' && typeof detector.name === 'string'`. There is no required inheritance, no decorator, no factory function. A detector is anything with the right shape.

Practical implications:

- If you are publishing one detector, the named-export shape is the simplest and reads well in tree-shaking audit output.
- If you are publishing several, exporting a `default` array keeps the import line tidy: `import myPack from 'my-pack'`.
- If your package has a meaningful namespace and you want `default` to be the package object itself, the third shape lets you add more fields later without breaking importers.

All three shapes are stable. We have not seen a strong reason to deprecate any of them, and the loader explicitly tries them all before giving up.

## What the loader actually does

`loadConfiguredRulePacks()` in `src/core/rule-packs.ts` is short. Walking it line by line is a fast way to see what guarantees you get as a rule-pack author:

1. The loader reads `loadConfig()` first. If `config.rulePacks` is empty or undefined, it returns `{ detectors: [], metadata: [] }` with no side effects.
2. For each pack name, it does a dynamic `await import(packName)`. This is bare Node dynamic import, so the package name has to resolve via the normal Node resolution rules: either an installed npm dependency, a path-style fallback used in tests, or a workspace package.
3. The export-shape detection runs and selects an array, or skips the pack with a warning.
4. Each detector is validated against the interface, and those that pass are appended to a flat list. Their `name` is paired with a metadata record `{ name, source: 'rule-pack: <packName>', defaultState: 'on' }`.
5. Failures during import are caught and warned, not thrown. A missing package or a malformed package will not crash your application. It will print a warning to stderr and continue with the rest of the rule packs.

Two consequences worth knowing:

- Dynamic import means your detector module is loaded lazily, on the first call to a `scrub()` or `rules list` path. If your module has top-level side effects, those side effects will run on first use, not on import of `prompt-scrub` itself.
- The default state for every rule-pack detector is `'on'`. There is no built-in switch to mark one off by default. If you want to ship a noisy detector behind opt-in, you have to either name it in a way that flags it as opt-in and let consumers turn it off via `ScrubOptions.disabledDetectors`, or document it loudly in your README.

## Wiring it up: the four integration points

A rule pack is nothing without the four integration points that actually make it run. Each is small; together they form the boundary between your package and the rest of the world.

### 1. The npm package

Your detector has to be reachable by Node's resolver. Publish to the registry, install in your project (`npm install my-pack`), or for local development use `npm install /path/to/my-pack`. The test suite uses the same path. Whatever you do, make sure a plain `require('my-pack')` from inside `node_modules/@nanocollective/prompt-scrub` would resolve.

### 2. Global config

In your project's config directory, `~/.config/prompt-scrub/config.json` on Linux (`~/Library/Application Support/prompt-scrub/config.json` on macOS, `%APPDATA%\prompt-scrub\config.json` on Windows), the `rulePacks` array is where you list the packages you want loaded:

```json
{
  "rulePacks": ["my-pack", "another-pack"]
}
```

The loader reads this file via `loadConfig()` and unions its `rulePacks` with the `prompt-scrub.rulePacks` field from your project `package.json`.

### 3. Project package.json

For per-project configuration, the same key lives under a `prompt-scrub` namespace in your `package.json`:

```json
{
  "prompt-scrub": {
    "rulePacks": ["my-pack"]
  }
}
```

`src/core/config.ts` reads `package.json` from `process.cwd()`, so it picks up whatever project you happen to be running from. The loader de-duplicates between the two sources via a `Set`, so a package listed in both ends up loaded exactly once.

### 4. The `rules list` CLI command

Once configured, your detectors show up alongside the built-ins when a user runs `prompt-scrub rules list`:

```
$ npx prompt-scrub rules list
Detector                 Source                          Default State
----------------         ------------------------------  -------------
SecretDetector           built-in                        on
EmailDetector            built-in                        on
UrlDetector              built-in                        on
PathDetector             built-in                        on
PhoneDetector            built-in                        on
AddressDetector          built-in                        on
NameDetector             built-in                        off
CodeTellDetector         built-in                        off
MyDetector               rule-pack: my-pack              on
```

This command is what people use to check that a pack is actually loaded. If your detector does not show up in this output, the loader silently skipped it and the most likely cause is a bad export shape. Check for the warning printed at startup first.

## Collision behaviour: where your detector slots in

The reason the contract is small is that the heavy lifting lives in `resolveCollisions()` in `src/core/collision-resolver.ts`. Your detector's findings are pooled with the built-ins, then a single pass resolves overlaps. The rules:

1. Findings are sorted by `span[0]` ascending and walked left to right.
2. Each new finding is checked against the accepted list for overlap. Non-overlapping candidates are accepted directly.
3. On overlap, the detector with the lower priority number wins. Priority is hard-coded in `DETECTOR_PRIORITY`: `SecretDetector` is 1, `EmailDetector` is 2, `UrlDetector` is 3, and so on through `CodeTellDetector` at 8.
4. Anything else has priority `99`, including rule-pack detectors. If your finding overlaps with `SecretDetector`, the secret wins, every time. This is the "missing a credential is worse than missing a name" policy, applied mechanically.
5. Equal priority overlaps resolve in favour of the longer span.

The implication for rule-pack authors is that your detector's findings will survive only when they do not conflict with a higher-priority built-in. Two patterns show up in practice:

- **Pick a category the built-ins do not touch.** Custom codenames, internal ticket numbers, third-party vendor tokens the secret detector does not know about. They will not collide with built-ins, so they survive.
- **Be specific enough that the span is the right one.** A detector that flags "open the App" as code-tell-shaped text will lose to the path detector if "App" is part of a path. Tighten the regex.

`docs/features/authoring-rule-packs.md` calls out the priority table verbatim, including the note that there is no public mechanism for a custom detector to override `SecretDetector` and there will not be one. That policy is what keeps the secret detector useful for the cases it is tuned for, and it is not negotiable through the rule-pack API.

## A minimal end-to-end pack

To make the moving parts concrete, this is a pack that detects internal project codenames for two strings, `Apollo` and `Zeus`. It uses the named-export shape and TypeScript:

```ts
// src/index.ts
import type { Detector, Finding } from '@nanocollective/prompt-scrub';

const PROJECT_X_REGEX = /\b(Apollo|Zeus)\b/g;

export class ProjectXDetector implements Detector {
  readonly name = 'ProjectXDetector';

  detect(text: string): Finding[] {
    const findings: Finding[] = [];
    PROJECT_X_REGEX.lastIndex = 0;
    let match: RegExpExecArray | null;
    while ((match = PROJECT_X_REGEX.exec(text)) !== null) {
      findings.push({
        category: 'ProjectX',
        span: [match.index, match.index + match[0].length],
        value: match[0],
        placeholderPrefix: 'Codename',
      });
    }
    return findings;
  }
}

export const detectors = [new ProjectXDetector()];
```

Build and publish the package (`prompt-scrub-projectx` here), then list it in the user's `package.json`:

```json
{
  "prompt-scrub": {
    "rulePacks": ["prompt-scrub-projectx"]
  }
}
```

Run `prompt-scrub rules list`. The new detector shows up with `Source: rule-pack: prompt-scrub-projectx` and `Default State: on`. From that point on, any text scrubbed via the library or CLI gets every occurrence of `Apollo` and `Zeus` replaced with `Codename_1`, `Codename_2`, etc., in source order, in the same pass that catches emails and paths.

The packing itself is unremarkable. What is worth taking away is how few places in the system know about your detector: the loader, the metadata entry for `rules list`, and the collision resolver. Everything else (the placeholder numbering, the session map, the rehydration pass) does not need to know that your detector exists. That is the shape of a contract designed to be small on purpose.

## What is stable and what is not

`prompt-scrub` is at 1.0.0 and the rule-pack contract shipped in this release. The two interfaces reproduced above (`Detector` and `Finding`) are documented as the runtime contract for everything outside the package. The general approach is conservative: any change to a public interface is a breaking change for rule packs and would land in a major version bump.

What is reasonable to expect to grow (additive, non-breaking):

- The metadata entry. `defaultState` is the only knob exposed today. If a rule-pack author needs to mark a detector as off by default, that would land as a new optional field rather than as a replacement.
- The export shapes. All three are exercised in the tests. A fourth (an async loader, say) would be additive if it kept the existing ones working.

What we do not plan to change:

- The collision table. Built-in priority is documented in `docs/features/detectors.md`. There are no plans to expose priority to rule-pack authors, because the secret-priority behaviour is a deliberate trade the whole product depends on.

Until something in `src/types/index.ts` moves, the contract you see there is the contract your pack will run against.

## Where to look in the repo

- `src/types/index.ts` for the canonical `Detector` and `Finding` shapes.
- `src/core/rule-packs.ts` for the loader (about 70 lines including comments).
- `src/core/config.ts` for how global config and `package.json` are read and merged.
- `src/core/collision-resolver.ts` for the priority table and the overlap pass.
- `docs/features/authoring-rule-packs.md` for the user-facing version of the same contract.

Issues, PRs, and rule-pack proposals are welcome at the repo. If you write one, please include a minimal test that exercises each of the three export shapes, plus a `rules list` line so others can see what they get when they install it.

Source, tests, and the full rule-pack contract: https://github.com/Nano-Collective/prompt-scrubber



If you have ever wanted to add a custom detector to `prompt-scrub` without forking the package, the rule-pack contract is what you are looking for. It is small enough to read in one sitting and consistent enough that a published pack can rely on it.

The whole contract is two TypeScript interfaces in `src/types/index.ts`:

- `Detector`: an object with a `name` and a `detect(text)` method.
- `Finding`: `{ category, span, value, placeholderPrefix }`.

That is the whole shape. A rule pack is an npm package whose top-level module exports one or more `Detector` objects in any of three accepted forms:

1. A `default` export that is itself an array of detectors.
2. A named export called `detectors` that is the array.
3. A `default` export object with a `detectors` property.

The loader in `src/core/rule-packs.ts` tries them in order and falls back gracefully. Missing or malformed detectors are skipped with a stderr warning rather than crashing the application, so a broken pack does not take down a working setup.

The one part of the contract that surprises first-time authors is that detectors deliberately do not return a `replacement` field. The runtime shape hands back `value` (the matched substring) and `placeholderPrefix` (the category namespace), and the core engine assigns the numeric suffix in source order. The reason is structural: a final placeholder depends on the session, not on the detector, and pushing that responsibility into individual detectors would break the byte-stable cache-prefix guarantee. Keep the prefix meaningful and unique to your category so the user-visible placeholder reads well.

Wiring it up has four integration points:

- Publish an npm package that exports detectors in one of the three shapes above.
- List the package in your global config (`~/.config/prompt-scrub/config.json` on Linux, the equivalent on macOS and Windows) under `rulePacks`, or under the `prompt-scrub.rulePacks` key in your project `package.json`. The loader unions the two sources and de-duplicates.
- Run `prompt-scrub rules list` to verify the package was loaded. If your detector does not appear, the loader skipped it and you have a bad export shape.
- Understand the collision behaviour. The built-ins have a hard-coded priority table (`SecretDetector` is highest), so a custom detector whose finding overlaps with a credential always loses. Pick categories that do not collide.

This is a deep dive for a developer publishing their first custom detector pack. The full walkthrough, including the minimal end-to-end example (a `ProjectXDetector` that catches two internal codenames), is in the post linked from this article.

Source, tests, and the rule-pack contract: https://github.com/Nano-Collective/prompt-scrubber



We just shipped the rule-pack contract for `prompt-scrub` and we want to walk through it, because the contract is small enough that you can read it on a coffee break and substantive enough that you can publish a real pack in an afternoon.

The pitch is simple: `prompt-scrub` ships eight built-in detectors (email, phone, postal address, path, secret, url, name as opt-in, code-tell as opt-in), but the cases that matter for one team are never quite the cases that matter for the next. Rule packs let you publish an npm package that contributes additional detectors without forking the core. They are the primary extension point, and the loader has been wired up to make them feel like a normal import.

The contract is two TypeScript interfaces in `src/types/index.ts`. Here is the whole thing:

```ts
export interface Finding {
  category: string;
  span: [number, number]; // [startIndex, endIndex]
  value: string;
  placeholderPrefix: string;
}

export interface Detector {
  name: string;
  detect(text: string): Finding[];
}
```

A detector is anything with a `name` and a `detect` method. The interface is structural (no base class to extend), so the implementation can be a class, a plain object, or anything in between. `detect()` walks the text and returns an array of `Finding`s. That is the whole shape.

There are three export shapes the loader accepts (`src/core/rule-packs.ts`). A rule pack module can be:

1. A `default` export that is an array of detectors: `export default [new MyDetector()]`.
2. A named export called `detectors` that is the array: `export const detectors = [new MyDetector()]`.
3. A `default` export object with a `detectors` property: `export default { detectors: [new MyDetector()] }`.

The loader tries them in order and silently skips anything else with a stderr warning. We have seen all three shapes in the wild; the named-export form is the cleanest for a single detector, the `default` array reads well for packs with several detectors, and the third shape gives you a namespaced package object if you want to grow into it later. None of the three is on a deprecation path.

The thing that surprises first-time authors is that `Finding` does not have a `replacement` field. Every "build a redaction detector" tutorial out there hands you `{ category, span, replacement }`, and the whitepaper for prompt-scrub originally did the same. The runtime contract deliberately omits it.

The reason is structural. The final placeholder is something like `Email_2`, where the `2` is a per-session counter. That counter is a session-wide value, not a detector-local value. If a detector returned `replacement: 'Email_1'` for its first match, the engine would have a choice between re-numbering detector A's output (which breaks the byte-stable cache-prefix guarantee prompt caching depends on) or letting collisions sit across detectors. Both options are bad, so the runtime shape splits the responsibility: detectors say "this is the match" (`value` + `span`) and "this is the category namespace" (`placeholderPrefix` like `Email` or `Codename`). The core engine takes that, numbers the placeholders in source order across all detectors, and writes the session map.

For rule-pack authors this means: do not invent your own placeholder strings inside `detect()`. Pick a meaningful, unique `placeholderPrefix` for your category, and let the engine do the numbering. `Codename`, `ApiKey`, `Ssn`, `Ticket` all work. Two detectors that pick the same prefix will produce interleaved numbering across detections, which is fine and often what you want.

Wiring a pack up to the loader has four integration points:

- The package. Publish it (or `npm install /path/to/local-pack` for development). The loader uses Node's dynamic `import()`, so anything the resolver can find works.
- Global config. `~/.config/prompt-scrub/config.json` on Linux, `~/Library/Application Support/prompt-scrub/config.json` on macOS, the roaming AppData dir on Windows. The `rulePacks` array is where you list packages. Overridable via `PROMPT_SCRUB_CONFIG_DIR` for tests.
- Project package.json. For per-project configuration, the same list lives under a `prompt-scrub` namespace in your `package.json`. The loader unions the two sources and de-duplicates, so a package listed in both still loads once.
- The `prompt-scrub rules list` CLI command. This is the diagnostic. If your detector does not appear in the output, the loader skipped it and you have a bad export shape. Check the stderr warning first.

The collision behaviour is the last thing worth understanding. Findings from your detector are pooled with the built-ins and run through `resolveCollisions()` in `src/core/collision-resolver.ts`. Built-in detectors have a hard-coded priority table: `SecretDetector` is 1 (highest), then `EmailDetector`, `UrlDetector`, `PathDetector`, `PhoneDetector`, `AddressDetector`, `NameDetector`, `CodeTellDetector`. Anything else, including rule-pack detectors, is priority 99.

The implication: if your finding overlaps a credential, the secret wins. This is the "missing a credential is worse than missing a name" policy, applied mechanically. The docs are explicit that there is no public mechanism for a custom detector to override `SecretDetector` and there will not be one. In practice this means you should pick categories that do not collide with the built-ins (custom codenames, internal ticket numbers, third-party vendor tokens the secret detector does not know), and make sure your spans are tighter than whatever category might also be in the running. A loose regex that flags "open the App" as code-tell-shaped text will lose to the path detector if "App" is part of a path.

The full long-form post walks through a minimal end-to-end pack called `ProjectXDetector` that catches two internal codenames (`Apollo` and `Zeus`), builds it, lists it in `package.json`, and shows the `rules list` output. The repo link at the bottom has the test suite (including the three export shapes) and the loader source, both of which are short enough to read in a sitting.

If you ship a real-world rule pack that exposes a problem with the contract, we want to hear about it before we have to make the contract bigger. Issues and PRs at the repo.

Source, tests, and the rule-pack contract: https://github.com/Nano-Collective/prompt-scrubber



The prompt-scrub rule-pack contract in one screen: the Detector interface, why value/placeholderPrefix but never replacement, three export shapes, config and package.json wiring.

https://github.com/Nano-Collective/prompt-scrubber


PrivacyContext - scrubbing prompts without breaking the conversation


Nanocoder v1.29.0 ships a feature we have wanted for a while: when you point Nanocoder at a cloud model on a private codebase, the model only ever sees placeholders for the identifying bits of your prompt. Locally, the placeholders resolve back to the values the agent actually needs to keep working. This post walks through how the scrub pipeline is wired into the chat request, what is and is not a content-layer problem, and the two design decisions that took the most iteration: which detectors to run in the agent context, and where the placeholder map lives.

Built by the [Nano Collective](https://nanocollective.org), a community collective building AI tooling not for profit, but for the community.

The full project lives at [https://github.com/Nano-Collective/nanocoder](https://github.com/Nano-Collective/nanocoder).

## What ships in v1.29.0

The privacy-aware scrubbing in this release is the integration of the standalone [`@nanocollective/prompt-scrub`](https://github.com/Nano-Collective/nanocoder) package (`^1.0.1`) into the chat request path. Three things are user-facing:

- A new `PrivacyContext` (`source/context/privacy-context.tsx`) that exposes the enabled flag and a ref to the placeholder session map.
- A `/privacy` command, with an `inspect <text>` subcommand that runs the same scrub pipeline against user-supplied text and prints the placeholders that would have been sent.
- A per-turn chat-queue notification on every model call that scrubbed at least one new identifier, so you know when the feature is doing something rather than it happening silently.

Behind the scenes, scrubbing runs at exactly one point in the chat pipeline: just before the AI SDK builds the request. There is no second hop or background rewriter. The reasoning, the assistant text, and the tool-call arguments are rehydrated after the stream completes, before they reach the conversation history. That is the entire shape of the feature.

## The pipeline, in five steps

A single chat turn goes through this:

1. Read the messages array from the conversation loop.
2. Pull out the system prompt (`role: system`); the rest of the array becomes the non-system messages.
3. If scrubbing is enabled, run `scrub()` on the system prompt and each non-tool message, threading the same `privacySessionMapRef.current` through. Emit a notification if the session map grew.
4. Hand the scrubbed messages to the AI SDK, which builds the request exactly as it would have without scrubbing.
5. When the response comes back, run `rehydrate()` over the assistant text, the assistant reasoning, and each tool-call `arguments` JSON string. The model sees placeholders while generating; the agent sees real values while executing.

The implementation lives across three places. The context object is `source/context/privacy-context.tsx`, which is just a typed React context with `{ privacyEnabled, privacySessionMapRef }`. The ref is created in `useAppState` (`source/hooks/useAppState.tsx`) and is the same instance for the lifetime of the app:

```ts
const privacySessionMapRef = useRef<Record<string, string>>({});
```

The scrub and rehydrate calls live in `source/ai-sdk-client/chat/chat-handler.ts`, around the AI SDK request boundary. There is no other integration point: the loop, the tool executor, and the UI all see the same shape they would see without scrubbing, because the placeholders are resolved in-place before they leave that function.

## What the package gives us

`@nanocollective/prompt-scrub` is a small library with a single pipeline:

- A pluggable detector system (each detector is a class or function that takes a string and returns an array of `Finding` objects with `category`, `span`, `value`, and a `placeholderPrefix`).
- A `scrub()` function that runs the detectors in priority order, resolves collisions, applies stable placeholders across a session, and returns the scrubbed text plus the updated session map.
- A `rehydrate()` function that swaps the placeholders back to their originals using the same session map.
- A built-in priority chain. `SecretDetector` wins, then `EmailDetector`, `UrlDetector`, `PathDetector`, `PhoneDetector`, `AddressDetector`. The `NameDetector` and `CodeTellDetector` are opt-in because their false-positive rates are meaningfully higher.

The `Finding` shape is the same the package's rule-pack authors implement against, which is what lets an organisation publish a private detector set as an npm package, declare it in `package.json` under `prompt-scrub.rulePacks`, and have it loaded alongside the built-ins. We are not relying on any of that integration in Nanocoder yet; v1.29.0 uses only the built-ins.

## The first design call: which detectors to run

The instant we wired `scrub()` into the chat handler, two detectors became obviously wrong in the agent context: `PathDetector` and `UrlDetector`.

Consider what a normal prompt looks like once an agent is running. You ask the agent to fix a bug, and a typical conversation already contains:

- The path of the repo you launched Nanocoder in.
- The path to the file you asked it to edit.
- URLs from `git log`, `npm install` output, or `package.json` listings.
- Maybe an AWS endpoint or a webhook URL the agent needs to keep working with.

If we run `PathDetector` and `UrlDetector` over that, the cloud provider sees `Path_1`, `Path_2`, `Path_3`, `Url_1` everywhere the model actually needs to see a real path or URL. The conversation starts to break: the agent refers to `Path_1` in a tool call, but the tool call needs the real value. The user fixes the bug because the model is now reasoning about a known-bad string of placeholders.

That is exactly the failure mode the package's threat model warns about when it says "Semantic leakage: a question that is inherently identifying (your private codebase, a niche bug only you have, a number only your accountant knows) cannot be made anonymous by stripping identifiers." For an agent on a project, the paths and URLs are part of the identifying information by definition.

The fix in `chat-handler.ts` is to pass `options: { disabledDetectors: ['PathDetector', 'UrlDetector'] }` on every scrub call:

```ts
finalSystemContent = scrub({
  content: systemContent,
  sessionMap: privacySessionMapRef.current,
  options: { disabledDetectors: ['PathDetector', 'UrlDetector'] },
}).scrubbedContent as string;
```

Cloud providers still see that you pasted an absolute path, but they do not see emails, phone numbers, API keys, or postal addresses in your prompt. That is the trade the agent context allows, and we made it explicit. The detectors are off at the call site, not globally configured; users who want to extend or constrain the set can do so without us deciding for them.

The other five built-ins (`SecretDetector`, `EmailDetector`, `PhoneDetector`, `AddressDetector`, plus the opt-in `NameDetector` and `CodeTellDetector`) remain enabled. `SecretDetector` is the one we are least willing to compromise on. Missing a credential is materially worse than missing a name, and the detector is tuned accordingly.

## The second design call: where the session map lives

The package's docs describe a session manager that writes the placeholder map to disk in the user's config directory, so an `Email_1` from yesterday's session is the same `Email_1` in today's session. That is the right design for a stand-alone CLI that you run between projects.

It is the wrong design for Nanocoder for two reasons. First, the placeholder map is sensitive data in its own right: it carries the original email, phone, secret, and address values the user did not want sent to the cloud. Putting that map on disk in `~/Library/Application Support/prompt-scrub/sessions/<id>.json` would make the disk a richer privacy target than the prompt was. Second, an agent session is one app process, and an app process already has a place to keep volatile state: a `useRef`. The session map lives there:

```ts
// source/hooks/useAppState.tsx
const privacySessionMapRef = useRef<Record<string, string>>({});
```

The ref is threaded through the chat handler the same way any other piece of app state is, by accepting it as a parameter and reading it at the right point. When the app exits, the ref is gone, which is fine: the user is not asking for placeholder stability across app restarts, and the threat model explicitly says a compromised machine is out of scope anyway. We have not invented encryption at rest; we have just not written the secret values to disk in the first place.

The other reason this matters is `JSON.stringify` round-tripping on tool-call arguments. The model emits `{"path": "/Users/me/project/src/app.tsx"}`. If we had disabled `PathDetector`, that string is exactly what we want to rehydrate. If we had enabled it, we would have to scrub the argument as plain text, get back `{"path": "Path_3"}`, and then rehydrate `Path_3` back to the real value. The current `chat-handler.ts` rehydrates by JSON-round-tripping the entire arguments object, which keeps object shape intact and avoids silent breaks on edge cases:

```ts
finalToolCalls = finalToolCalls.map(tc => {
  try {
    const argsStr = JSON.stringify(tc.function.arguments);
    const result = rehydrate({
      content: argsStr,
      sessionMap: privacySessionMapRef.current,
    });
    return {
      ...tc,
      function: {
        ...tc.function,
        arguments: JSON.parse(result.content as string),
      },
    };
  } catch (e) {
    logger.error('Failed to rehydrate tool call', { toolName: tc.function.name, error: e });
    return tc;
  }
});
```

The try/catch is a deliberate walk-back: if a placeholder has been removed from the map (because the user cleared the session, or because a session map rotation happened mid-stream), rehydration is partially undefined and we fall back to the scrubbed tool call rather than crash the conversation. The agent then sees the placeholder and can recover on the next turn, which is consistent with the threat model: partial coverage is fine, blast radius has to be small.

## Stable placeholders within a session

Stable placeholders are the part that makes the feature feel less like a one-off scrub and more like a session-wide substitution. The package reuses `Email_1` for the same email across the whole conversation, instead of inventing `Email_5` on the next turn. Two reasons:

- It stops the cloud provider from correlating identities across turns. Every reference to "the same customer email" looks like a reference to `Email_1`, regardless of which turn it appears in.
- It stops the local agent from re-deriving the same identity on every turn. The model is told `Email_1` resolves to the same value throughout the session, so its memory of who "the customer" is does not get fragmented across six renames.

Within a single session the mapping is stable. Across sessions it is not. The cloud provider cannot build a long-term profile by joining `Email_1` from yesterday's map to `Email_1` from today's. The threat model calls this out explicitly: stable session mappings address identifier-level correlation within a session; they do not address stylistic fingerprinting, semantic leakage, or cross-session profiling.

## The notification: per-turn deltas, not running totals

The wired-up `onPrivacyEvent` callback reports the per-turn delta: the number of new identifiers added to the session map on this turn, not a running total. The notification is a chat-queue message that reads `Privacy active: scrubbed N new identifier(s)`. Three properties of this:

- It fires only when there is a delta. If a turn finds nothing new, nothing is printed. That keeps the chat readable across long sessions where the same email appears a hundred times.
- It is a soft signal, not a hard gate. There is no "are you sure?" prompt. The detection is local, deterministic, and idempotent; if it ran, the chat moves on.
- It is per turn, not per session. A user who wants to audit the full session opens `/privacy inspect` on representative text.

The notification can be turned off implicitly by disabling scrubbing entirely; we did not add a per-notification mute because the entire feature is opt-in, via `enablePromptScrubbing` in preferences (`source/config/preferences.ts`).

## The `/privacy inspect` command

`/privacy` is registered in `source/commands/lazy-registry.ts` and is a stateless inspector. It calls the same `scrub()` from the chat handler, with the same disabled detectors, but with an empty `sessionMap: {}`:

```ts
const result = scrub({
  content: text,
  sessionMap: {},
  options: { disabledDetectors: ['PathDetector', 'UrlDetector'] },
});
```

That `{}` is deliberate. The point of `inspect` is to show what the scrubber would do today, not what it did historically. A user pasting a draft prompt gets an accurate preview; a user pasting the same prompt three times in a row gets the same preview each time, even if the live session had built up a mapping that would change the placeholder numbers.

The output renders a small boxed panel with three sections: the original text, the text that would be sent to the LLM, and a numbered list of detected identifiers mapping placeholder to original. If nothing is detected, the panel is replaced with the plain message "No sensitive identifiers detected in the input."

There is no second subcommand in v1.29.0. `inspect` is the one; the other surfaces (rule-packs management, session management) live in the package CLI, not in Nanocoder.

## What this release does and does not defend against

The package's threat model is the same one Nanocoder inherits, so it is worth restating the boundary clearly.

`PrivacyContext` defends against identifying content leaking into the prompt body: emails, phones, paths, URLs, API keys, tokens, postal addresses, and (if enabled) names and code identifiers. It defends against cross-turn identifier correlation within a single session by reusing placeholders. It defends against tool-call argument leakage by rehydrating in place rather than relying on the model to guess what `Path_3` was.

It does not defend against a compromised local machine. The session map is plaintext, in memory, but it is still on the box. It does not defend against stylistic fingerprinting: how the user phrases things, the cadence of their questions, the words they choose. It does not defend against semantic leakage: a question that is itself identifying cannot be made anonymous by stripping identifiers from it. And it does not see the network. A user who needs network-layer privacy composes this with a network tool of their own choosing; the scrubber has no opinion about which one.

The cloud-side reasoning is the same. The provider sees placeholders, not values. It can still see that you pasted a URL-shaped string (`Url_` detectors are off in agent context). It can still see the shape of your prompt, the size of your codebase, and the structure of your tool calls. What it does not see, by default, is the identifying content. That is the trade this feature makes: more of your prompt becomes opaque to a third party, in exchange for a meaningful reduction in how much of it is identifying.

## Composability with the rest of the release

A few things in 1.29.0 change how you should think about privacy mode:

- The native VS Code GUI (the headline feature) uses the same `handleChat` plumbing as the terminal UI, so scrubbing applies uniformly across both. There is no separate privacy code path for the GUI.
- The stateless API with history-boundary rehydration pairs well with scrubbing. Because history is rehydrated at history boundaries, a rehydrated history is the same shape the AI SDK would have built from a fresh conversation, and the scrub pipeline does not need to know which messages came from a resumed session vs a fresh one.
- Subagents inherit the parent's `PrivacyContext` by virtue of inheriting the parent's `appState`. A subagent that runs in the same process will see the same placeholders and rehydrate the same way. There is no separate per-subagent session map yet; that is a deliberate choice in v1.29.0, because per-subagent maps would create per-subagent identity islands that the cloud provider could join.

## What we will iterate on

The architecture above is the v1.29.0 baseline. Things we are likely to change:

- The session-map lifecycle. Today it is `useRef({})` for the lifetime of the app. A longer-lived session store, possibly encrypted at rest, would let a user resume a privacy-protected session across restarts without losing the placeholder stability. The threat model calls this out as v1.1.
- Optional detector packs. Rule packs are package-level today; we will not enable them inside Nanocoder until the security review is done. Users who need custom detectors can use the package CLI directly.
- A `NameDetector` opt-in with strict mode, exposed as a preference. The detector is off by default because the false-positive rate is non-trivial, but there are workflows (legal, medical, finance) where it earns its keep.

If you find a case where the scrub pipeline breaks a legitimate tool call, or where the placeholder mapping is too aggressive, please open an issue. The scrub-and-rehydrate path is well-isolated, which means the iteration loop is small: a fix in `chat-handler.ts` or in the package, a regression test, and we ship.

Repo, docs, and the package behind it all live at [https://github.com/Nano-Collective/nanocoder](https://github.com/Nano-Collective/nanocoder).


PrivacyContext: scrubbing prompts without breaking the conversation


Nanocoder v1.29.0 ships a privacy-aware prompt scrubbing layer we have wanted for a while. When you point Nanocoder at a cloud model on a private codebase, the model only sees placeholders for the identifying bits of your prompt. Locally, the placeholders resolve back to the values the agent actually needs.

Three things are in the box. A new `PrivacyContext` that runs in the chat request path, just before the AI SDK builds the request. A `/privacy` command for inspecting what would be scrubbed. A per-turn notification when at least one new identifier is detected, so you see when the feature is doing something.

Built on the standalone `@nanocollective/prompt-scrub` library, the scrub pipeline runs the secret, email, phone, and address detectors by default. `PathDetector` and `UrlDetector` are explicitly disabled in the agent context because every prompt already contains paths and URLs the agent needs to keep working with. Stable placeholders (`Email_1`, `Secret_1`) are reused within a session so the cloud provider cannot correlate identities across turns.

Rehydration runs on the assistant text, the reasoning, and every tool-call argument. The model sees placeholders while generating; the agent sees real values while executing. The session map lives in memory for the lifetime of the app, never on disk.

It is a content-layer defense: it reduces what identifying material reaches the cloud, and it composes with a network-layer tool of your own choosing if you need more. The full deep dive on the architecture and the design trade-offs is in the GitHub Discussion linked below.

#OpenSource #AI

[Repo and docs](https://github.com/Nano-Collective/nanocoder), built by the [Nano Collective](https://nanocollective.org).



A thing we shipped in Nanocoder v1.29.0 that I think is worth talking about on its own, separate from the headline features: a privacy-aware prompt scrubbing layer. The short version is that when you point Nanocoder at a cloud model on a private codebase, the cloud model now only ever sees placeholders for the identifying bits of your prompt, and the local agent sees the real values back.

The longer version is interesting because of the trade-offs.

## The setup

The actual scrubbing logic is a standalone package called `@nanocollective/prompt-scrub`. It exposes a `scrub()` function that runs a set of pluggable detectors (email, phone, secret, address, plus opt-ins for names and code identifiers) over a string, replaces matched spans with stable placeholders (`Email_1`, `Secret_1`, etc.), and updates a session map that the same package uses to `rehydrate()` placeholders back to the original text on the other side.

In v1.29.0, we wired that package into the chat request path in `chat-handler.ts`. The integration point is exactly one place, just before the AI SDK builds the request: we scrub the system prompt, scrub each non-tool message, hand the scrubbed text to the SDK, and when the response comes back we rehydrate the assistant text, the reasoning, and every tool-call argument. The placeholders are never visible to the model as opaque strings; to the model they look like real identifiers that the agent then uses.

## Where the design got interesting

Two decisions took more iteration than I expected.

The first was which detectors to run in the agent context. The package's defaults catch paths and URLs because they are often identifying. In an agent context, though, every prompt already contains paths (your repo, the file you asked it to edit) and URLs (from `npm install`, `git log`, your `package.json`). If we scrubbed those, the agent would not be able to refer to `Path_3` in a tool call and have the tool execute against the real path. We disabled `PathDetector` and `UrlDetector` at the call site, with `options: { disabledDetectors: ['PathDetector', 'UrlDetector'] }` on every scrub call, so cloud providers still see you pasted an absolute path, but they do not see your emails or API keys. That is the trade-off: a small amount of metadata leakage stays in exchange for the agent continuing to work.

The second was where to put the session map. The package's docs describe writing the placeholder map to disk in the user's config directory so `Email_1` is stable across sessions. We do not. The placeholder map is sensitive data in its own right (it carries the original values), and an in-process `useRef` is enough for one Nanocoder session. When the app exits, the map goes with it. We have not invented encryption at rest; we have just not written the secret values to disk in the first place.

## Stable placeholders

Stable placeholders within a session are the part that makes the feature feel less like a one-off rewrite and more like a substitution model. The cloud provider sees the same `Email_1` referenced across every turn, which means it cannot correlate identities across turns by linking `Email_3` in turn 1 to `Email_7` in turn 5. The local agent also benefits: its memory of who "the customer" is does not get fragmented across six renames of the same email in the conversation.

Across sessions the mapping is not stable. The provider cannot join `Email_1` from yesterday's run to `Email_1` from today's. The package's threat model is explicit about the boundary: stable session mappings address identifier-level correlation within a session. They do not address stylistic fingerprinting, semantic leakage, or cross-session profiling.

## The notification

There is a small per-turn notification that fires when the session map grows. The shape is `Privacy active: scrubbed N new identifier(s)`, and `N` is the per-turn delta, not a running total. It fires only when there is a delta, so a long session where the same email recurs does not get spammed. There is no per-notification mute; the entire feature is opt-in via the `enablePromptScrubbing` preference.

## `/privacy inspect`

There is also a `/privacy inspect <text>` command for previewing what the scrubber would do without sending a chat turn. It runs the same `scrub()` with an empty `sessionMap: {}`, so the preview is deterministic, which means paste the same text three times and you get the same placeholders back. The output is a small panel with the original, the scrubbed version, and the placeholder-to-original mapping. Useful for drafting prompts that you want to look a certain way before sending.

## What this release does not defend against

The threat model is worth reading in full, but the short version is: this is a content-layer defense. It reduces identifying material in the prompt body and gives you per-turn visibility into what was caught. It does not see the network, does not defend against a compromised local machine, and does not strip style or semantic content from a question that is identifying on its own. If you need network-layer privacy, the right composition is this plus a network tool of your choosing, such as VPN, Tor, or a self-hosted relay. The scrubber has no opinion about which.

## Try it

Enable it via the `enablePromptScrubbing` preference (or run `/privacy inspect` for a preview without enabling). Scrubbed placeholders stay stable within a session, so re-prompts and follow-ups keep working without needing to re-identify the same customer or path 12 times.

Repo, docs, and the package behind it all live here:

https://github.com/Nano-Collective/nanocoder

Built by the Nano Collective, a community collective building AI tooling not for profit, but for the community.



Nanocoder v1.29.0 scrubs identifying content (emails, secrets, phones, addresses) from prompts before they reach the cloud, and rehydrates tool args locally. /privacy inspect, stable placeholders per session.

https://github.com/Nano-Collective/nanocoder

#AI #OpenSource



Sponsorship buys you a logo on the supporters page. Not the roadmap. Not who gets paid. The Nano Collective puts that rule in writing and enforces it across every channel.


Your diagram was right there in the source. Then HTML-to-Markdown happened, and it's gone.

get-md keeps Mermaid four ways: preserve a fence, recover source from a rendered SVG, reconstruct from a PDF via vision, or validate every fence. Pick the one that fits the input.


A migration chain is only as trustworthy as the step you're on. Every up() output gets Zod-validated, so the fail surfaces at v3, not buried under v9.

That's what json-up does: its ValidationError carries the version it failed at, so the bug is localised, not piled at the end.



Nanocoder will never have a paid tier. Not "not yet", not "free for now". It's structural: no investor return, no upsell, no plan B behind the roadmap. MIT licence and the Nano Collective economics charter shape the project, not a marketing promise.


Fine-tuning doesn't need a GPU cluster. Nanotune ships for Apple Silicon with MLX, wraps the tooling, and treats a 0.5B to 1.5B model on a MacBook as the default path, not a workaround.


Secrets don't only arrive in the prompt. They arrive in the next turn, inside the ls, git log, and cat results the agent reads back. That's why prompt-scrub runs on every message, not just the user one. Tool results are where the leaks accumulate.


Most scanners hand you a ruleset on day one. Sentinel ships with none. A pack written for one stack lies to the next, so the owner of the code is the right author.


A month of whitepaper writing is a lot to lose to a one-paragraph redirect. Before you draft one for the Nano Collective, open a docs issue first, or message Discord. You'll find a co-author, or catch the collision early.


The default crawl sees a sitemap and recurses forever. get-md shipped the kill switch: --max-urls caps a run at 10,000, --max-depth at 3. Hard limits the "the spec is just a suggestion" default forgets.



Your data already tracks a version under whatever name you picked. `json-up` does not ask you to rename it. Pass key: "version" (or "schemaVersion", or anything else) to migrate() and the library reads yours, not its own.

August 2026

Wednesday, August 266 posts