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 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.



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.



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.


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.



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.


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.



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.



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.


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.


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.


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.


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.

Attaching to a running subagent without losing the transcript


Nanocoder v1.29.0 ships a subagent inspector: press `Ctrl+S` while a subagent is running and you jump into its live transcript, including the reason it picked a particular tool and the text it is streaming in. Press `Ctrl+S` again to cycle across parallel subagents, or `Esc` to drop back to the parent session. Under the hood the feature is small, but two of the bugs we hit while building it are worth writing up because they are the kind of thing that only shows up when you actually try to use the thing in anger, and the fix in each case came from a place in Ink we had not looked at before.

This is the deep dive on the `Ctrl+S` attach path. The headline for the release is the native VS Code GUI; this post is for the readers who want to know how the terminal UI behaves when subagents are running in parallel.

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).

## The feature, in one paragraph

The top-level `App` component holds a single piece of state: `attachedAgentId`, a string or `null`. When it is `null`, the parent renders the normal interactive `<InteractiveApp>` view. When it is a subagent's id, the parent renders `<SubagentView agentId={...}>` instead, which reads the subagent's session out of the session store and renders its messages, streaming text, and streaming reasoning, with the header `Main Session > <subagent name>` and a footer `Press Esc to detach`. That's the whole UI. The rest of the work is in the four edge cases that bit us.

## Tracking parallel subagents: a `Map` keyed by agent id

Subagents have been around for a while, but they used to be modelled as a single in-progress notebook that the executor scribbled into. The attach feature needs the system to know about multiple subagents at once, so the executor and the events layer were reworked around a `Map<agentId, SubagentEvent>` in `source/services/subagent-events.ts`. Each entry holds the subagent's name, status, current tool, tool call count, turn count, token count, and a chronological `toolHistory` array. The executor calls `updateSubagentProgressById(agentId, ...)` and `appendSubagentTool(agentId, ...)` to keep the entry fresh, and the UI calls `getAllSubagentProgress()` to read them.

The point of the `Map` is that the cycle key in `Ctrl+S` is just an index into the running entries. There is no separate "running subagents" list to keep in sync; the entries in the map are the running subagents. A subagent that completes is removed from the map by its executor, so it falls out of the cycle automatically.

```ts
// excerpt: source/app/App.tsx
const progresses = Array.from(getAllSubagentProgress().entries());
const runningAgents = progresses
  .filter(([_, p]) => p.status !== 'complete' && p.status !== 'error')
  .map(([id]) => id);

const current = attachedAgentIdRef.current;
if (runningAgents.length === 0) {
  changeAttachedAgent(null);
} else if (!current) {
  changeAttachedAgent(runningAgents[0]);
} else {
  const currentIndex = runningAgents.indexOf(current);
  changeAttachedAgent(
    currentIndex === -1
      ? runningAgents[0]
      : runningAgents[(currentIndex + 1) % runningAgents.length],
  );
}
```

A subtle point: if the currently-attached agent has finished by the time you press `Ctrl+S` again, `currentIndex` is `-1` and we fall back to `runningAgents[0]`. That avoids the trap where the cycle is empty from the user's point of view but the JavaScript modulo would still try to target a finished agent.

## The bug: `<Static>` is append-only

The transcript in Nanocoder's terminal UI renders through Ink's `<Static>` component. `<Static>` is the Ink primitive that gives you a terminal scrollback: it renders each item once and leaves it on screen, so the chat history above the input box behaves like a real terminal pager. The catch is that `<Static>` tracks items by their position in the items array and only ever appends past that index. If you swap the items array out for a different transcript, the new items simply do not print, because `<Static>` thinks everything past its last index is empty.

The first version of `SubagentView` did exactly that. It rendered the subagent's messages into a `<Static>` and reused the same component across cycles. The first attach worked, because the items array was populated from scratch. Cycling to a second subagent meant putting a different items array into the same `<Static>`, and `<Static>` happily rendered nothing. From the user's point of view, `Ctrl+S` cycled the header text but the transcript never changed.

The fix is to give each agent's `<Static>` a different `key`, so React unmounts the old one and mounts a new one when the agent id changes. The line is in `SubagentView`:

```tsx
<ChatQueue
  staticComponents={[]}
  queuedComponents={chatComponents}
  // key the underlying <Static> by agent so cycling to another
  // session remounts it. A reused <Static> only ever appends
  // past its item index, so the new agent's transcript would
  // otherwise never print.
  clearKey={agentId}
  disableStatic={altScreenActive}
  renderLastQueuedComponentLive={false}
/>
```

`ChatQueue` forwards `clearKey` to the `<Static key={clearKey} items={...}>`. When `agentId` changes, React remounts the `<Static>`, the new one starts with an empty item index, and it prints the new agent's transcript from scratch. The same `clearKey` trick is what `/clear` uses to wipe the parent transcript, by the way: the parent maintains a `conversationId` UUID and bumps it on `/clear`, and `InteractiveApp` passes that id down as `clearKey` to its own `ChatQueue`. The two paths share the same mechanism.

## The second bug: terminal garbage on switch

Remounting the `<Static>` solved the "new transcript never prints" problem, but it created a new one. Without an explicit screen wipe, the old agent's transcript stays on the terminal because Ink does not erase what `<Static>` already wrote. The new `<Static>` then paints over the top of the old text, and the result is a buffer of overlapping output: the parent session's screen, with the old agent's messages still visible behind the new agent's messages.

The fix is a one-line terminal write immediately before the state change:

```ts
if (!altScreenActive && process.stdout.isTTY) {
  process.stdout.write('\x1B[2J\x1B[3J\x1B[H');
}
appState.setAttachedAgentId(nextAgentId);
```

`\x1B[2J` clears the screen, `\x1B[3J` clears the scrollback buffer, and `\x1B[H` moves the cursor home. That is the same sequence the CLI's `/clear` path uses, so the screen ends up in the same blank state as a fresh chat. The `!altScreenActive` guard skips the wipe when the user is in `--alt-screen` mode, because in alt-screen the viewport owns the screen and Ink's layout will repaint the new content into the right place on the next render.

This is the part of the fix that turned out to be invisible to users but obvious in retrospect. There is no scrollback for the attached agent while it is in flight, which sounds like a downside until you remember that the agent is still running: you can press `Ctrl+S` to come back to the parent at any time, and the parent's full transcript is still in scrollback. The attached view is a live console, not a saved page.

## The third bug: rapid `Ctrl+S` presses lose toggles

`Ctrl+S` is implemented as a `useInput` handler in `App`. When you press it, the handler reads `appState.attachedAgentId`, computes the next agent id, and calls `appState.setAttachedAgentId(nextAgentId)`. The problem is that React batches state updates and the next `useInput` call sees the previous render's `appState.attachedAgentId` until the new render commits. If you press `Ctrl+S` twice in quick succession, the second press reads the same `appState.attachedAgentId` as the first and tries to cycle to the same agent, which is no-op'd by the `if (attachedAgentIdRef.current === nextAgentId) return;` guard. The keystrokes are swallowed.

The fix is a ref that mirrors the state and updates synchronously inside the handler:

```ts
// mirror of attachedAgentId that updates synchronously, so rapid Ctrl+S
// presses cycle correctly even before React commits the previous change.
const attachedAgentIdRef = React.useRef(appState.attachedAgentId);
React.useEffect(() => {
  attachedAgentIdRef.current = appState.attachedAgentId;
}, [appState.attachedAgentId]);

const changeAttachedAgent = (nextAgentId: string | null) => {
  if (attachedAgentIdRef.current === nextAgentId) return;
  attachedAgentIdRef.current = nextAgentId; // sync update before React commits
  if (!altScreenActive && process.stdout.isTTY) {
    process.stdout.write('\x1B[2J\x1B[3J\x1B[H');
  }
  appState.setAttachedAgentId(nextAgentId);
};
```

The ref is mutated synchronously inside the handler, so the next `Ctrl+S` reads the new value even if React has not committed yet. The `useEffect` keeps the ref in sync with `appState` for the rest of the app, in case `setAttachedAgentId` is called from a non-handler path (it is not, but the invariant is cheap).

This is the same pattern we use for `reasoningExpanded`, `compactToolDisplay`, and the `compactToolCountsRef` accumulator: state for rendering, ref for the async conversation loop. The pattern is set up in `useAppState.tsx`. The trick is that state reads inside synchronous handlers need a ref, while state reads inside async loops are fine with the state value because the loop will re-render on the next batch anyway.

## The detach UX

Detach is `Esc` from inside `SubagentView`. The handler calls `onDetach`, which is wired to `changeAttachedAgent(null)`. That re-enters the same screen-wipe path as a cycle, so the parent session renders into a clean terminal on the next paint.

There is one auto-detach path worth mentioning. If the attached agent's session is removed from the session store while you are attached to it (the executor cleans up on completion or error), the next render of `SubagentView` finds `session === undefined` and triggers a detach via a `useEffect`:

```ts
useEffect(() => {
  if (!session) {
    onDetach();
  }
}, [session, onDetach]);
```

This is the right behaviour: a subagent that finishes mid-attach should not leave you staring at a frozen screen. The detach is silent (no "agent finished" toast), because the parent's own transcript already shows the agent's completion event through the normal message stream.

The view itself polls the session store at 100ms with a `useReducer((x) => x + 1, 0)`-based forceRender, because the session store is a mutable `Map` and the executor mutates it in place. A subscription-based store would be cleaner, but the polling approach is robust to out-of-band writes from the executor's promise chain and does not require sharing the store's internal mechanics.

## What the user sees

A typical session looks like this. You type a prompt that the main agent decides to delegate: "read the changelog and tell me what changed in the CLI flags in 1.29.0." The main agent invokes the `agent` tool with a subagent type. The subagent starts running.

You press `Ctrl+S`. The screen wipes.

```
Main Session > changelog-explorer
... (subagent's streamed text, its full tool history, its reasoning)
```

You press `Ctrl+S` again. If another subagent is running, the screen wipes and the next agent's transcript renders. If not, the parent session renders back. You press `Esc` from inside an attached view to detach immediately.

If a subagent finishes while you are attached, you stay in the view until the next render (typically within 100ms), then auto-detach into the parent. The parent's transcript shows the agent's completion event normally.

## Why not a real "tabbed" subagent console?

We considered a richer UI: a tabbed bar across the top with one tab per running subagent, clickable to switch, and a live status badge per tab. The lean `Ctrl+S` cycle came out ahead for two reasons. First, the terminal UI is not the only place subagents run; the VS Code sidebar shows them as live cards with their own progress, and the ACP path shows them through the editor's `plan` updates. Adding a tabbed UI to the terminal UI would be a third representation, which is one too many. Second, `Ctrl+S` cycle is the same muscle memory as `git rebase --interactive` and vim's buffer-switching, and it costs nothing to teach. The people who want a richer view are already in the VS Code GUI.

## Closing notes

The subagent inspector is a small feature in terms of lines of code, but it sits on top of three assumptions that did not hold at the start: `<Static>` is append-only, terminal scrollback persists across React remounts, and React state updates are not synchronous in synchronous handlers. The fixes are not clever; they are the right tool for each problem (a `key` for remount, a terminal wipe for the screen, a ref for the synchronous read). The pattern that emerged, ref-as-synchronous-mirror-of-state, is one we will keep using for any future keystroke that needs to debounce against rapid presses.

If you find a `Ctrl+S` case that does not behave, please open an issue. The fix is small but the test surface is exactly the kind of thing that benefits from a real reproduction.

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



Nanocoder v1.29.0's `Ctrl+S` subagent attach is the small feature with the most interesting under-the-hood story this release. The user-facing loop is one keystroke: press `Ctrl+S`, jump into a running subagent's live transcript, watch its reasoning and tool calls stream in real time; press `Ctrl+S` again to cycle through parallel subagents, or `Esc` to detach.

The interesting part is what it took to make that reliable. Three things had to be true at once, and none of them were true at the start:

1. Ink's `<Static>` is append-only. A reused `<Static>` tracks items by index and never prints past its last index. Cycling to a second subagent meant the new transcript was silently dropped. The fix was to key the `<Static>` by `agentId`, so React remounts it on each cycle. The same `clearKey` trick is what `/clear` uses to wipe the parent transcript.

2. The terminal does not erase what `<Static>` already wrote. Remounting the component does not clear the screen; the new transcript paints over the old one. We added a one-line `\x1B[2J\x1B[3J\x1B[H` terminal wipe before the state change, the same escape sequence the `/clear` path uses.

3. React state updates are not synchronous inside synchronous handlers. Rapid `Ctrl+S` presses were swallowing keystrokes because the next `useInput` call saw the previous render's `appState.attachedAgentId`. The fix is a `useRef` mirror that updates synchronously inside the handler, so each keystroke reads the latest value.

Parallel subagents are tracked by a `Map<agentId, SubagentEvent>` in `source/services/subagent-events.ts`. The cycle key is just an index into the running entries. A subagent that finishes is removed from the map by its executor, so it falls out of the cycle automatically. The detach view polls the session store at 100ms because the executor mutates it in place, and a subscription-based store would just be moving the problem.

The full project lives 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 a feature in Nanocoder v1.29.0 that is one keystroke: press `Ctrl+S` while a subagent is running and you jump into its live transcript. Press it again to cycle through parallel subagents. Press `Esc` to detach. The user-facing loop is small, but the under-the-hood story is worth writing up because almost none of it was obvious at the start.

## What the feature actually does

The top-level `App` component holds a single piece of state: `attachedAgentId`, a string or `null`. When it's `null`, the parent renders the normal interactive view. When it's a subagent's id, the parent renders `<SubagentView agentId={...}>` instead, which reads the subagent's session out of the session store and renders its messages, streaming text, and streaming reasoning, with a header `Main Session > <subagent name>` and a footer `Press Esc to detach`. That's the whole UI. The rest of the work is in the four edge cases that bit us.

## How parallel subagents are tracked

Subagents used to be modelled as a single in-progress notebook that the executor scribbled into. The attach feature needs the system to know about multiple subagents at once, so the executor and the events layer were reworked around a `Map<agentId, SubagentEvent>` in `source/services/subagent-events.ts`. Each entry holds the subagent's name, status, current tool, tool call count, turn count, token count, and a chronological `toolHistory` array. The executor calls `updateSubagentProgressById` and `appendSubagentTool` to keep the entry fresh.

The point of the `Map` is that the cycle key in `Ctrl+S` is just an index into the running entries. There is no separate "running subagents" list to keep in sync; the entries in the map are the running subagents. A subagent that completes is removed from the map by its executor, so it falls out of the cycle automatically. If the currently-attached agent has finished by the time you press `Ctrl+S` again, `currentIndex` is `-1` and we fall back to `runningAgents[0]`. That avoids the trap where the cycle is empty from the user's point of view but the JavaScript modulo would still try to target a finished agent.

## The bug: `<Static>` is append-only

The transcript in Nanocoder's terminal UI renders through Ink's `<Static>` component. `<Static>` is the Ink primitive that gives you a terminal scrollback: it renders each item once and leaves it on screen, so the chat history above the input box behaves like a real terminal pager. The catch is that `<Static>` tracks items by their position in the items array and only ever appends past that index. If you swap the items array out for a different transcript, the new items simply do not print, because `<Static>` thinks everything past its last index is empty.

The first version of `SubagentView` did exactly that. It rendered the subagent's messages into a `<Static>` and reused the same component across cycles. The first attach worked, because the items array was populated from scratch. Cycling to a second subagent meant putting a different items array into the same `<Static>`, and `<Static>` happily rendered nothing. From the user's point of view, `Ctrl+S` cycled the header text but the transcript never changed.

The fix is to give each agent's `<Static>` a different `key`, so React unmounts the old one and mounts a new one when the agent id changes. The line is in `SubagentView`: `clearKey={agentId}`. `ChatQueue` forwards `clearKey` to the `<Static key={clearKey} items={...}>`. When `agentId` changes, React remounts the `<Static>`, the new one starts with an empty item index, and it prints the new agent's transcript from scratch. The same `clearKey` trick is what `/clear` uses to wipe the parent transcript, by the way: the parent maintains a `conversationId` UUID and bumps it on `/clear`, and `InteractiveApp` passes that id down as `clearKey` to its own `ChatQueue`. The two paths share the same mechanism.

## The second bug: terminal garbage on switch

Remounting the `<Static>` solved the "new transcript never prints" problem, but it created a new one. Without an explicit screen wipe, the old agent's transcript stays on the terminal because Ink does not erase what `<Static>` already wrote. The new `<Static>` then paints over the top of the old text, and the result is a buffer of overlapping output: the parent session's screen, with the old agent's messages still visible behind the new agent's messages.

The fix is a one-line terminal write immediately before the state change:

```ts
if (!altScreenActive && process.stdout.isTTY) {
  process.stdout.write('\x1B[2J\x1B[3J\x1B[H');
}
appState.setAttachedAgentId(nextAgentId);
```

`\x1B[2J` clears the screen, `\x1B[3J` clears the scrollback buffer, and `\x1B[H` moves the cursor home. That's the same sequence the CLI's `/clear` path uses, so the screen ends up in the same blank state as a fresh chat. The `!altScreenActive` guard skips the wipe when the user is in `--alt-screen` mode, because in alt-screen the viewport owns the screen and Ink's layout will repaint the new content into the right place on the next render.

This is the part of the fix that turned out to be invisible to users but obvious in retrospect. There is no scrollback for the attached agent while it is in flight, which sounds like a downside until you remember that the agent is still running: you can press `Ctrl+S` to come back to the parent at any time, and the parent's full transcript is still in scrollback. The attached view is a live console, not a saved page.

## The third bug: rapid `Ctrl+S` presses lose toggles

`Ctrl+S` is implemented as a `useInput` handler in `App`. It reads `appState.attachedAgentId`, computes the next agent id, and calls `appState.setAttachedAgentId(nextAgentId)`. The problem is that React batches state updates and the next `useInput` call sees the previous render's `appState.attachedAgentId` until the new render commits. If you press `Ctrl+S` twice in quick succession, the second press reads the same value as the first and tries to cycle to the same agent, which is no-op'd by the change-detection guard. The keystrokes are swallowed.

The fix is a ref that mirrors the state and updates synchronously inside the handler:

```ts
const attachedAgentIdRef = React.useRef(appState.attachedAgentId);
React.useEffect(() => {
  attachedAgentIdRef.current = appState.attachedAgentId;
}, [appState.attachedAgentId]);

const changeAttachedAgent = (nextAgentId: string | null) => {
  if (attachedAgentIdRef.current === nextAgentId) return;
  attachedAgentIdRef.current = nextAgentId; // sync update before React commits
  if (!altScreenActive && process.stdout.isTTY) {
    process.stdout.write('\x1B[2J\x1B[3J\x1B[H');
  }
  appState.setAttachedAgentId(nextAgentId);
};
```

The ref is mutated synchronously, so the next `Ctrl+S` reads the new value even if React has not committed yet. This is the same pattern we use for `reasoningExpanded` and `compactToolDisplay`: state for rendering, ref for the synchronous handler.

## The detach UX

Detach is `Esc` from inside `SubagentView`. The handler calls `onDetach`, which is wired to `changeAttachedAgent(null)`. That re-enters the same screen-wipe path as a cycle, so the parent session renders into a clean terminal on the next paint.

There is one auto-detach path worth mentioning. If the attached agent's session is removed from the session store while you are attached to it (the executor cleans up on completion or error), the next render of `SubagentView` finds `session === undefined` and triggers a detach via a `useEffect`. This is the right behaviour: a subagent that finishes mid-attach should not leave you staring at a frozen screen. The detach is silent, because the parent's own transcript already shows the agent's completion event through the normal message stream.

The view itself polls the session store at 100ms with a `useReducer((x) => x + 1, 0)`-based forceRender, because the session store is a mutable `Map` and the executor mutates it in place.

## Why not a tabbed subagent console?

We considered a richer UI: a tabbed bar across the top with one tab per running subagent, clickable to switch, and a live status badge per tab. The lean `Ctrl+S` cycle came out ahead for two reasons. First, the terminal UI is not the only place subagents run; the VS Code sidebar shows them as live cards with their own progress, and the ACP path shows them through the editor's `plan` updates. Adding a tabbed UI to the terminal UI would be a third representation. Second, `Ctrl+S` cycle is the same muscle memory as `git rebase --interactive` and vim's buffer-switching, and it costs nothing to teach. The people who want a richer view are already in the VS Code GUI.

## Closing

The subagent inspector is a small feature in terms of lines of code, but it sits on top of three assumptions that did not hold at the start: `<Static>` is append-only, terminal scrollback persists across React remounts, and React state updates are not synchronous in synchronous handlers. The fixes are not clever; they are the right tool for each problem (a `key` for remount, a terminal wipe for the screen, a ref for the synchronous read). The pattern that emerged, ref-as-synchronous-mirror-of-state, is one we will keep using for any future keystroke.

If you find a `Ctrl+S` case that does not behave, please open an issue.

Repo, changelog, and docs are 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.



Nanocoder v1.29.0: Ctrl+S attaches to a running subagent's live transcript, cycles through parallel agents, Esc detaches. The interesting part is the Ink <Static> remount-per-agent trick that fixes the transcript-never-prints bug. https://github.com/Nano-Collective/nanocoder



A whitepaper with a proposer who goes quiet doesn't die quietly. After 60 days idle, the Nano Collective moves its status to Paused, an honest label, not a deletion. Anyone can pick it up. Reactivating it later is welcome, not a clean-up job.



Buffer the whole batch and you OOM before the last URL resolves. get-md's convertBatch yields as each page completes, not in input order, so a 1000-URL run streams to disk the moment it's ready. Memory stays flat at the worker cap.


Your old JSON already has a version: 0.

json-up treats any document missing a `_version` as v0 and runs every prior migration in sequence on first read. Drop the file in and the migrations walk it forward, no pre-edit, no wrapper, no rewrite of legacy data first.



The old scheduler lived inside the TUI. Close the terminal and file watches stopped, cron stopped, triggered runs shared whatever mode the TUI was in. nanocoder daemon exists because event-driven work can't ride on a foreground process.


Fine-tuning has too many knobs to guess from zero. Nanotune ships a starting recipe: 150 iterations, learning rate 5e-5, batch size 4. A known-good default for 0.5B-1.5B models on 100-500 examples, so you tune from a real baseline instead of vibes.


When the model invents a placeholder that isn't in the session map, prompt-scrub doesn't crash and doesn't silently rewrite. The string passes through verbatim, a warning lands on stderr. A hallucinated Secret_2 reaches the user as the literal text "Secret_2". Fail visibly.



Three layers of suppression, three different jobs. Sentinel deduplicates by content hash by default, lets you label a one-off finding to dismiss it, and reserves a per-repo sentinel.yaml for systematic noise. Pick the lightest layer that solves it.



30 USD is the minimum balance before Open Source Collective will process a contributor expense. It is an OSC platform requirement, not a Nano Collective cap. Check it before doing the work, or risk an unpaid invoice.



<100ms with Turndown, 5-10 seconds with the local ReaderLM-v2 path. get-md gives you both, and the choice between them is the engineering call: speed for batch and CI, structure for the single conversion you actually read. Don't pick by default.



One async up() flips the whole chain. json-up gives you two builders: createMigrations() stays sync, createAsyncMigrations() awaits each step. Pay the async tax only where it earns it.



One tool keeps pulling the model back, even after you've said no. Add it to `nanocoder.disabledTools` in `agents.config.json` and the model treats it as if it never existed: zero prompts, no subagent fallback, no profile opt-out. One entry, permanent silence.


A fine-tune without feedback is just training in the dark. Nanotune's loop is train, benchmark, read the failures, add examples for those cases, then train again. The next run starts with a named gap instead of a guess.



Your agent reads `ls /Users/me/work` and the next turn has your full path tree. Same for `cat deploy.yml`. prompt-scrub scrubs every message, user prompt and tool result, so the LLM sees `Path_1` instead of `/Users/me/work`.



An LLM audit will get things wrong. Sentinel designs for that instead of around it: every finding carries honest confidence, the same issue dedups by content hash so it never files twice, and one close keeps it closed for good.



Seven local model servers show up as first-class providers in nanocoder: Ollama, llama.cpp, llama-swap, LM Studio, LocalAI, MLX, vLLM. Local coding is a built-in assumption now, not the power-user escape hatch.



A benchmark that scores on vibes is worse than no benchmark. After `nanotune judge configure`, run `nanotune judge test` and watch what it actually returns. Scores, criteria breakdown, reasoning for a known prompt. One verification step before a pass rate is worth trusting.


A sloppy detector is worse than no detector. prompt-scrub ships NameDetector and CodeTellDetector off by default: a false positive rewrites your code mid-flight, a missed detection just doesn't help. Opt in only when you know the false-positive cost on your own config.


Closing an LLM-audit issue because the model misread the code, then finding the same finding re-filed next run. Label the close with sentinel:false-positive. Sentinel reads the label, the finding's stable identity stays in the dedup store, and the issue stays closed.



Your CI fires an unattended agent, it dies on a stuck loop, exit non-zero, no usable output, morning lost to a stack trace. nanocoder is built headless-first: the agent loop produces a final answer at completion, so CI gets something it can act on instead of a crash to debug.


Your configured iterations are a guess. The loss curve is the answer. Nanotune plots training vs validation and calls out the moment they diverge, so you stop when the model is ready, not when the script says so.


An empty fund that says so is worth more than a full one that lies. The Nano Collective's Economics Charter names the community fund a mechanism, not a balance, and publishes the real number alongside it. The honesty is the commitment.


A converter you reach for during LLM prep should not phone home by default. get-md's Turndown and Readability path stays local and finishes under 100ms, which is the only sane default when the input is also your prompt.



Most "JSON migrations" are scattered `if (old.field)` guards across the codebase, with no record of which shape shipped when. json-up keeps every step in one versioned file: one place to read the history, one place to bump it.



A coding agent should answer to the developer, not to the foundation that funds a model lab.

Nanocoder treats Anthropic, OpenAI, Google, Ollama, and OpenRouter as interchangeable providers in one CLI, so the vendor never holds the user hostage.



Fine-tuning shouldn't depend on whoever wrote the last config. Nanotune encodes the loop as five verbs (init, data add, train, benchmark, export), so the next teammate runs the same commands instead of reverse-engineering a YAML blob.



You can scrub your message and still leak. `ls`, `cat`, `git log`, `grep` - whatever a tool prints is the next prompt, paths and all.

prompt-scrub scrubs every message regardless of origin, so identifiers in tool results never reach the next LLM turn.



Hundreds of out-of-the-box rules, and most of them were written for someone else's stack. You scroll past them on every run. Sentinel ships zero rule packs on purpose. The audit only fires on what your team defines.


A 30-day review held against a proposal you quietly rewrote is worthless. When a whitepaper pivot changes the problem, audience, or shape of the solution, flag it openly. The clock resets so the objections the community raises are about the project you're actually building.



Mermaid in source, an SVG already rendered, and a vector drawing in a PDF are three different problems pretending to be one. Pretending one path handles all three is how your diagrams vanish in conversion. get-md ships four paths: preserve, recover, generate, validate.


Running Nanotune end to end in CI, scripts, and Docker without a TTY


# Running Nanotune end to end in CI, scripts, and Docker without a TTY

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

The headline of the v1.6.0 release is that Nanotune works without a terminal. This article is the long version: what the new shape of the CLI looks like under the hood, how to chain commands the way you would chain any other tool from CI, and where the boundaries are between commands that finish on their own and commands that genuinely need a keyboard.

If you have ever piped `nanotune status` into `tee run.log` and watched a 40-line React reconciler stack trace land in your log file, this is the post that explains why that happened, why it does not happen any more, and how to write pipelines against the new shape.

## Why every command used to crash without a TTY

Nanotune is built on Ink, a React-based TUI library. Ink enables raw mode on `process.stdin` as soon as anything in the component tree calls `useInput`. We used `useInput` to wire up "press any key to exit" frames and help bars across the TUI, which sounds harmless until you realise that raw mode is enabled the moment the React tree mounts, not the moment the user presses a key.

If `stdin` is not a TTY, Ink throws:

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

...and then React tries to render a frame anyway, which is where the stack trace comes from. The throw is fast, the stack trace is long, and exit code is 1, so every command looked broken from the outside, including read-only commands that never needed a keypress in the first place. `nanotune status`, `nanotune data validate`, and `nanotune judge test` all paid the same tax.

The fix lives in `src/lib/tty.ts`. The two helpers are deliberately tiny so they are easy to test and impossible to misread:

```ts
export function supportsRawMode(stdin = process.stdin): boolean {
  return stdin.isTTY === true;
}

export function interactiveRequiredMessage(command: string): string {
  return (
    `\`nanotune ${command}\` needs an interactive terminal.\n` +
    '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.'
  );
}
```

The strict `=== true` check matters. Node leaves `isTTY` as `undefined` (not `false`) on non-TTY streams, so a truthy-but-not-true value would silently let raw mode slip through and reintroduce the crash. The unit test for that case is in `src/lib/tty.spec.ts` and is the guard we rely on.

## The split: render-and-exit vs interactive-only

Every Nanotune command now classifies into one of two buckets, and the bucket determines the behaviour under non-interactive conditions. There is no third mode, and commands do not silently degrade in surprising ways.

### Render-and-exit commands

`status`, `data validate`, `train`, `export`, `benchmark`, and `judge test` render their final output and exit on their own when there is no keyboard. The plumbing for that is two new components:

- `useKeyInput(handler, isActive = true)` is a drop-in for Ink's `useInput` that passes `isActive: false` whenever `supportsRawMode()` returns false. Ink never tries to enable raw mode, so there is nothing to throw.
- `useAutoExit(done, failed)` calls Ink's `exit()` as soon as `done` is true and there is no keyboard to wait on. If `failed` is true, it sets `process.exitCode = 1` first, so shell chains behave correctly.
- `<ExitHint>` is a small component that renders the "Press any key to exit" line only when there is a keyboard to act on. Without one it returns `null`, so captured output is clean.

Concretely, `useAutoExit(true, !hasConfig)` in `status.tsx` and `useAutoExit(status === 'done' || status === 'error', status === 'error')` in `data/import.tsx` are the only places that decide whether to call `exit()`. The status command exits as soon as it has rendered the report. The import command exits as soon as the import resolves. Both surface a real exit code on failure.

### Interactive-only commands

`init`, `data add`, `data list`, `chat`, and `judge configure` genuinely need a keyboard: they prompt, paginate, or run a REPL. There is no honest way to run them without a TTY. v1.6.0 makes that explicit in `src/cli.tsx`:

```ts
function renderInteractive(name: string, node: ReactElement): void {
  if (!supportsRawMode()) {
    console.error(interactiveRequiredMessage(name));
    process.exitCode = 1;
    return;
  }
  render(node);
}
```

If a script accidentally runs `nanotune chat` in CI, it now prints one clear sentence and exits 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.
```

Two consequences worth noting. First, the message is the same wording across every interactive-only command, because it comes from the same helper. Second, the non-zero exit code means a CI job that accidentally invokes one of these fails the step instead of carrying on as if it succeeded. That is the right failure mode for a misuse, and it is the change that makes the split safe to lean on from automation.

## The new `--yes` flag on `data import`

`data import` is the one command in the render-and-exit bucket that, until 1.6.0, needed a keystroke to confirm. It is now flagged explicitly:

```ts
dataCommand
  .command('import <file>')
  .option('-y, --yes', 'Skip the confirmation prompt (for scripts and CI)')
  .action(async (file, options) => {
    if (!options.yes && !supportsRawMode()) {
      console.error(interactiveRequiredMessage('data import'));
      console.error('Pass --yes to import without confirmation.');
      process.exitCode = 1;
      return;
    }
    render(<DataImportCommand file={file} yes={options.yes} />);
  });
```

Three things to take away from the snippet:

- The check happens in the CLI layer, before the React tree mounts. There is no TTY frame that crashes mid-render and no `useEffect` racing the prompt.
- The error wording is the same `interactiveRequiredMessage` helper used elsewhere, with one extra line that points the user at the flag they need.
- The component itself short-circuits past the preview screen when `yes` is true (`status` starts at `'importing'` rather than `'preview'`), so the rendered output is the same on a TTY as it is in a pipe.

`--yes` is a deliberately small flag. It does not change what gets imported. It does not skip validation. It only skips the y/n prompt. If you want the import to be re-validated by `nanotune data validate` afterwards, you still have to run it.

## A full non-interactive pipeline

The simplest useful pipeline is the one the changelog points at: validate, train, export. With the new exit-code semantics on render-and-exit commands, the chain is just `&&`:

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

In CI that might look like:

```yaml
jobs:
  retrain:
    runs-on: macos-14   # Apple Silicon runners; MLX + llama.cpp binaries target arm64
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
        with: { version: 11 }
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npm install -g @nanocollective/nanotune
      - run: nanotune data import data/examples.jsonl --yes
      - run: nanotune data validate
      - run: nanotune train --iterations 200
      - run: nanotune export -q q8_0
      - run: nanotune benchmark --preset medium --timeout 60000
```

A few notes on why each step is shaped that way:

- `data import --yes` is the only data command that would otherwise need a keystroke. The other data commands (`add`, `list`) are interactive-only and should not appear in a non-interactive pipeline.
- `data validate` exits non-zero on duplicate examples, broken alternation, missing fields, or under the minimum example count, so the `&&` chain breaks early and CI fails loudly. This was the practical reason to fix exit codes in 1.6.0; before, `data validate` would have crashed with a stack trace before reporting any problems.
- `train --iterations 200` overrides the configured iteration count at the CLI, which keeps the pipeline reproducible regardless of what is in `config.json` on the runner.
- `export -q q8_0` produces an 8-bit GGUF. The pre-built llama.cpp binaries are downloaded automatically by Nanotune, so the runner does not need a compiler toolchain.
- `benchmark --preset medium --timeout 60000` selects the laptop preset (8 threads, 20 GPU layers, 4096 ctx, 256 max tokens) and gives each test a 60-second ceiling, which avoids a slow generation holding the step open. Benchmark reports land in `benchmarks/` as both JSON and Markdown.

You can drop `data validate` if you trust the input, but it is cheap and gives you a precise error if the JSONL drifts. The validation report covers duplicates, broken turn alternation, missing fields, context-message consistency, and minimum example count.

## Docker without `-t`

The classic Docker failure mode was:

```
$ docker run nanotune:latest nanotune status | tee status.log
ERROR Raw mode is not supported on the target process.
    at ...
    at ...
    ... (40 lines)
```

In 1.6.0 the same command prints a clean status report and exits. A working Dockerfile looks like:

```dockerfile
FROM node:22-bookworm-slim
RUN npm install -g @nanocollective/nanotune
WORKDIR /project
COPY data/ ./data/
COPY nanotune.config.json ./
# NOTE: no USER nanotune, no TTY allocation, no interactive flags needed.
ENTRYPOINT ["nanotune"]
```

Then:

```bash
docker build -t nanotune:latest .
docker run --rm nanotune:latest data validate
docker run --rm nanotune:latest train --iterations 100
docker run --rm nanotune:latest export -q q4_k_m -o model-q4km
```

Notice there is no `-t` flag on `docker run`. There is no `script` wrapper. There is no `unbuffer`. The container does not need an interactive PTY because every command in the chain is a render-and-exit command that finishes on its own.

If you accidentally include `nanotune chat` in the Dockerfile's `CMD`, you will get the single-sentence `interactiveRequiredMessage` and a non-zero exit code. That is the signal to fix the command, not a bug to work around with `-t`.

## cron and systemd timers

cron jobs and systemd timers are the other common non-interactive context. They are simpler than CI because there is no YAML layer, just shell:

```cron
# /etc/cron.d/nanotune-retrain
0 3 * * 1  nanotune  cd /srv/nanotune && nanotune data validate >> /var/log/nanotune.log 2>&1 && nanotune train >> /var/log/nanotune.log 2>&1 && nanotune export >> /var/log/nanotune.log 2>&1
```

Things worth checking on cron specifically:

- `cron` does not allocate a TTY, so `process.stdin.isTTY` is `undefined`. Render-and-exit commands detect that and exit cleanly.
- `MAILTO=""` in the crontab prevents the cron daemon from trying to email the output to the user. With render-and-exit commands the output is meaningful, so the right place for it is a log file (`>> /var/log/nanotune.log 2>&1`).
- If the chain fails, you want the next run to keep going rather than blocking on a stuck `nanotune train`. That was the behaviour under 1.5.x too, but it now works because the command exits on its own instead of hanging on a "press any key" frame.

For systemd, the equivalent `Service` block looks like:

```ini
[Service]
Type=oneshot
User=nanotune
WorkingDirectory=/srv/nanotune
ExecStart=/usr/bin/env bash -c 'nanotune data validate && nanotune train && nanotune export'
StandardOutput=append:/var/log/nanotune.log
StandardError=inherit
```

`StandardOutput=append:` writes to a log file without truncating, which keeps history. `StandardError=inherit` lets systemd route stderr to the journal alongside stdout.

## Things that are deliberately still interactive

It is worth being explicit about what v1.6.0 did not change, because the boundary is part of the design.

`nanotune init` walks you through creating a `nanotune.config.json`, including the project name, base model, training defaults, and the `contextMessage` role. That is a guided setup, not a batch operation. Running it in CI would just produce a half-configured stub.

`nanotune data add` builds examples turn by turn, with a "Add another turn?" prompt and an Esc-to-save escape hatch. The whole flow is a REPL-shaped conversation. We have not shipped a flag that lets you pipe in examples one per line, because the multi-turn shape is hard to express without a real prompt.

`nanotune chat` is the inference REPL. It uses Ink to render streaming tokens and reads slash commands (`/reset`, `/system`, `/stats`, `/help`, `/exit`) from the keyboard. There is no scripted equivalent on purpose; if you want a non-interactive smoke test of an exported model, use `nanotune benchmark` with a tiny dataset instead.

`nanotune data list` is interactive because it paginates a potentially long examples table and lets you delete rows by index. If you need a non-interactive listing, `cat data/train.jsonl` is the right tool.

`nanotune judge configure` writes a `judge.json` that can hold a literal API key, and it walks you through provider and model selection. The key file is now written with `0600` permissions (also new in 1.6.0), but the configuration flow itself is still interactive on purpose.

## What this means for contributors

If you are adding a new command or touching an existing one, there are two rules that keep the non-interactive story intact.

1. Never call Ink's `useInput` directly. Use `useKeyInput` from `src/components/index.ts`. It wraps Ink's `useInput` with a `supportsRawMode()` guard, so the crash cannot recur by accident.
2. Decide the command's bucket explicitly. Render-and-exit commands should call `useAutoExit(done, failed)` and render their keyboard hints through `<ExitHint>`, both of which no-op when there is no keyboard. Interactive-only commands should be wired through the `renderInteractive` helper in `src/cli.tsx`, which prints the standard message and exits 1 on a non-TTY.

If a command is genuinely render-and-exit but you forget the `useAutoExit` call, the command will hang forever on the "Press any key to exit" frame in CI, which is the symptom to look for in a code review. If a command is interactive-only but you accidentally call `render(node)` directly, the test that fails first is the one in `src/lib/tty.spec.ts` that asserts the message wording is plain text (no `at ` and at most three lines).

The other internal change worth knowing: `c8`'s coverage `exclude` previously pointed at `source/app/App.tsx`, a path that has never existed, which let spec files count as covered source and inflated the badge to 88.62%. The new exclude is `src/**/*.spec.ts{,x}` and `dist/**`, which moves the reported figure to a real 78.97%. That is not a bug, but it is the kind of number that surprises people on first read, so: yes, the coverage number went down. The tests did not.

## Putting it together

The shape v1.6.0 leaves you with is roughly: anything that can run without a keyboard runs without a keyboard and exits with a real code; anything that genuinely cannot do that fails fast with a clear message and a non-zero exit. The pipeline you would write against any normal Unix tool is the pipeline you can now write against Nanotune, with `data import --yes` as the only flag you need to remember.

If you hit a command that does not behave the way you expect under CI, the place to start is `supportsRawMode()` in `src/lib/tty.ts`. That is the single source of truth for the TTY check, and it is the function that decides between render-and-exit and interactive-only in every command. If a future command needs to land in the render-and-exit bucket, it should call `useAutoExit` and render hints through `<ExitHint>`. If it needs to land in the interactive-only bucket, it should go through `renderInteractive` in the CLI layer.

Source, issues, and the changelog live at [github.com/Nano-Collective/nanotune](https://github.com/Nano-Collective/nanotune). If something fails under CI in a way the rules above do not cover, open an issue with the command, the output, and the CI environment, and we will work through it.



Nanotune v1.6.0 makes every command safe to chain from CI, cron, or a Docker container without a TTY.

Up to 1.5.x, even read-only commands like `nanotune status` crashed with a 40-line React stack trace the moment they ran under a pipe or a CI step, because Ink enabled raw mode as soon as the React tree mounted. v1.6.0 splits the CLI into two explicit buckets:

- Render-and-exit commands (`status`, `data validate`, `train`, `export`, `benchmark`, `judge test`) finish on their own when there is no keyboard, set a real exit code on failure, and suppress keyboard hints so captured output is clean.
- Interactive-only commands (`init`, `data add`, `data list`, `chat`, `judge configure`) print one clear sentence and exit 1 instead of crashing, which lets CI catch the misuse rather than carrying on.

The practical change is that pipelines now work the way you would expect:

```bash
nanotune data validate && nanotune train && nanotune export && nanotune benchmark --preset medium
```

`data validate` exits non-zero on duplicate examples, broken turn alternation, missing fields, or under the minimum example count, so the chain breaks early in CI. `data import` gets a new `--yes` flag for scripted imports.

In Docker, no `-t` flag is needed. In cron, no `unbuffer` wrapper. In systemd, no `pty` allocation. The only thing to remember is that the genuinely interactive commands (`chat`, `init`, `data add`, `data list`, `judge configure`) refuse to run without a TTY rather than silently degrading, which is the failure mode you want.

The internal plumbing is small and testable: `src/lib/tty.ts` exposes `supportsRawMode()` (strict `isTTY === true`, so Node's `undefined` does not slip through) and `interactiveRequiredMessage(command)` for the standard wording. The component layer adds `useKeyInput` (the only sanctioned way to read keys), `useAutoExit(done, failed)` (exits without a keyboard and sets a non-zero code on failure), and `ExitHint` (renders keyboard hints only when there is a keyboard to act on them).

Source, changelog, and issues: https://github.com/Nano-Collective/nanotune



A short one from the Nanotune maintainers. v1.6.0 just shipped, and the headline is unglamorous: every command now works without a terminal. For anyone who has been bitten by this in CI, that is the entire release. For anyone who hasn't, here is the story.

## What was actually broken

Nanotune is a React-Ink TUI. Ink enables raw mode on stdin as soon as anything in the tree calls `useInput`, which is the hook you use to read keystrokes. We use `useInput` all over the place for things like "press any key to exit" frames and help bars, so raw mode was being enabled the moment the React tree mounted, not the moment the user pressed a key.

If stdin was a TTY, that is fine. If stdin was not a TTY (CI, a pipe, a Docker container without `-t`, cron, anything that does not allocate a PTY), Ink threw `ERROR Raw mode is not supported on the target process` and React's reconciler tried to render a frame anyway. The throw is fast, the stack trace is forty lines, and exit code is 1, so every command looked broken from the outside. Read-only commands. `nanotune status`. `nanotune data validate`. All of them.

Looking at the issue tracker, this has been the most common "why does this not work in CI" report for the last several releases. It was clearly overdue to fix.

## The fix in two lines

A new `src/lib/tty.ts`:

```ts
export function supportsRawMode(stdin = process.stdin): boolean {
  return stdin.isTTY === true;
}

export function interactiveRequiredMessage(command: string): string {
  return (
    `\`nanotune ${command}\` needs an interactive terminal.\n` +
    '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.'
  );
}
```

The strict `=== true` matters because Node leaves `isTTY` as `undefined` (not `false`) on non-TTY streams. A truthy check would let `undefined` slip through and reintroduce the crash on some Node versions. The test that pins this is in `src/lib/tty.spec.ts` and asserts that `supportsRawMode({})` returns `false`.

Every command now branches on `supportsRawMode()`. There are two buckets and nothing in between.

## Render-and-exit commands

`status`, `data validate`, `train`, `export`, `benchmark`, and `judge test` render their final output and exit on their own when there is no keyboard. The components that make this work:

- `useKeyInput(handler, isActive = true)` is a drop-in for Ink's `useInput`. It passes `isActive: false` whenever `supportsRawMode()` returns false, which means Ink never tries to enable raw mode at all.
- `useAutoExit(done, failed)` calls Ink's `exit()` as soon as `done` is true and there is no keyboard. If `failed` is true it sets `process.exitCode = 1` first.
- `<ExitHint>` renders "Press any key to exit" only when there is a keyboard. Otherwise it returns `null` so captured output is clean.

Two consequences that matter in practice. First, a failed run now sets a non-zero exit code, so `nanotune train && nanotune export` chains correctly. Second, captured output is clean: no "press any key" line at the bottom of your CI log.

## Interactive-only commands

`init`, `data add`, `data list`, `chat`, and `judge configure` genuinely need a keyboard (prompts, menus, the chat REPL). For these, `src/cli.tsx` has a `renderInteractive` helper:

```ts
function renderInteractive(name: string, node: ReactElement): void {
  if (!supportsRawMode()) {
    console.error(interactiveRequiredMessage(name));
    process.exitCode = 1;
    return;
  }
  render(node);
}
```

If a script runs `nanotune chat` from CI by accident, the user gets one clear sentence and a non-zero exit code. The non-zero code is the important bit: it lets CI catch the misuse rather than carrying on as if the command succeeded.

## The new `--yes` flag

The one render-and-exit command that previously needed a keystroke was `data import`, which asks for confirmation before merging a JSONL/CSV/JSON file. v1.6.0 adds `-y, --yes`:

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

Without a TTY and without `--yes`, the command tells you the flag is required rather than failing obscurely. With `--yes`, it imports and exits.

## A real CI pipeline

The thing you can now write that you couldn't before:

```yaml
jobs:
  retrain:
    runs-on: macos-14
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
        with: { version: 11 }
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npm install -g @nanocollective/nanotune
      - run: nanotune data import data/examples.jsonl --yes
      - run: nanotune data validate
      - run: nanotune train --iterations 200
      - run: nanotune export -q q8_0
      - run: nanotune benchmark --preset medium --timeout 60000
```

A few notes on why this works:

- `data validate` exits non-zero on duplicate examples, broken turn alternation, missing fields, or under the minimum example count. The chain breaks early.
- `train --iterations 200` overrides whatever is in `config.json` on the runner, so the pipeline is reproducible regardless of how the checkout was configured.
- `export -q q8_0` produces an 8-bit GGUF; the pre-built llama.cpp binaries are downloaded automatically.
- `benchmark --preset medium --timeout 60000` selects the laptop preset and gives each test a 60s ceiling so a slow generation does not hang the step.

No `-t` flag on the Docker job. No `script` wrapper. No `unbuffer`. Just commands chained with `&&`.

## What stayed interactive on purpose

Worth being explicit about what v1.6.0 did not change:

- `nanotune init` walks you through creating a config; that is a guided setup, not a batch operation.
- `nanotune data add` is a REPL-shaped conversation with a "Add another turn?" prompt and an Esc-to-save escape hatch. There is no pipe-friendly version by design.
- `nanotune chat` is the inference REPL with `/reset`, `/system`, `/stats`, `/help`, `/exit` slash commands. There is no scripted equivalent on purpose; if you want a non-interactive smoke test of an exported model, use `nanotune benchmark` with a tiny dataset.
- `nanotune data list` paginates examples and lets you delete rows by index; if you need a non-interactive listing, `cat data/train.jsonl` is the right tool.
- `nanotune judge configure` writes a `judge.json` (now with `0600` permissions, also new in 1.6.0) and walks you through provider and model selection.

These refuse to run without a TTY rather than silently degrading, which is the failure mode you want from a misuse.

## What this means for contributors

Two rules that keep the non-interactive story intact:

1. Never call Ink's `useInput` directly. Use `useKeyInput` from `src/components/index.ts`, which wraps it with a `supportsRawMode()` guard.
2. Decide the command's bucket explicitly. Render-and-exit commands call `useAutoExit(done, failed)` and render hints through `<ExitHint>`. Interactive-only commands go through `renderInteractive` in the CLI layer.

If a render-and-exit command forgets the `useAutoExit` call, it will hang forever on the "Press any key to exit" frame in CI, which is the symptom to look for in code review. If an interactive-only command accidentally calls `render(node)` directly, the unit test that fails first is the one in `tty.spec.ts` that asserts the message is plain text (no `at `, at most three lines).

## Closing thought

The shape v1.6.0 leaves you with is roughly: anything that can run without a keyboard runs without a keyboard and exits with a real code; anything that genuinely cannot fails fast with a clear message and a non-zero exit. The pipeline you would write against any normal Unix tool is the pipeline you can now write against Nanotune, with `data import --yes` as the only flag worth remembering.

Source, changelog, and issues: https://github.com/Nano-Collective/nanotune

If you hit a command that does not behave the way you expect under CI, the place to start is `supportsRawMode()` in `src/lib/tty.ts`. That is the single source of truth for the TTY check, and it is the function that decides between render-and-exit and interactive-only in every command.



Nanotune v1.6.0: every command chains from CI, cron, and Docker without a TTY. `data validate && train && export && benchmark` just works. `data import --yes` for scripts. Full write-up: https://github.com/Nano-Collective/nanotune #nanotune



No lawyer signed our Economics Charter. It is a Markdown file under version control, with git as the audit trail. Financial terms get 30 days notice and apply to new work only. Anyone can read what was promised when, and your terms stay in effect unless you agree otherwise.



Most converters render PDFs to images and route them through cloud vision by default, then bill you in API credits. get-md ships text-only. PDF vision is opt-in: useLLM, a remote model, and two peer deps you install yourself. Cost only exists if you asked for it.



"Validation failed" with no field path is a grep you didn't budget for. json-up's `ValidationError` carries the `issues` array, so the offending field is named in the message you already have.



A checked-in API key is a leak waiting for a bot. nanocoder reads NANOCODER_PROVIDERS (or NANOCODER_PROVIDERS_FILE) over anything in agents.config.json, so your keys stay in the shell and the repo stays clean.



Five commands. No YAML. No flags. By lunch you have fine-tuned a model and exported a GGUF running in Ollama or llama.cpp. That is the whole nanotune workflow: init, data, train, export, done.



Randomising placeholders per turn looks safer. It isn't. If "Email_1" becomes "Email_3" next turn, the change is the signal: the model pins you from what moved.

prompt-scrub pins one placeholder per identifier per session. Names stay still, so there's nothing left to correlate.


A suppression filter that learns from feedback will learn to swallow the next real bug. Sentinel (alpha) keeps dedup, false-positive labels, and sentinel.yaml as three independent levers. Each closes a different scope of false positive.


A merged whitepaper used to function as a build endorsement. The Nano Collective treats that as a bug. Merge publishes the thinking. Stage 3 is the build call, after 30 days of public review, recorded on-page with rationale so the yes runs against what the project actually is.



Under 100ms for a typical HTML page, no service in the path, no rate limit to dodge. When your converter is faster than your LLM round-trip, prep stops being where the pipeline loses time. get-md makes that the default.


3 errors, one migrate() call. ValidationError and MigrationError point at your data. VersionError points at your config: sort order, duplicates, empty arrays.



Your first prompt shouldn't require memorising twenty-plus provider config blocks. Nanocoder's /setup-providers wizard exists because hand-writing agents.config.json was the thing blocking real adoption. Templates, model fetch, save.


The default for fine-tuning is a wall of YAML and flags you read for an hour before you see a number. Nanotune's init asks plain questions, then you run data, train, benchmark. Dataset in, a feedback signal out, before lunch.



Your prompts travel through a network the LLM provider can read. Run prompt-scrub on the content, then put whatever you trust on the request path: VPN, Tor, a proxy. Scrub, send, rehydrate. Network choice stays yours.



Close one false positive fast enough and your brain flags the next five as noise. That is how a real finding gets skipped. Sentinel (alpha) treats a false-positive label as permanent, so dismissing one never costs you the next five.



A migration that runs cleanly can still hand back garbage. json-up checks the up() result against the schema, not just the input, so a broken step fails where you can see it instead of three migrations later.



Most coding agents put the cloud key in the first paragraph and the local providers in the fifth. Nanocoder puts Ollama, llama.cpp, LM Studio, MLX, vLLM, LocalAI, llama-swap, and Atomic Chat in the same provider schema as the cloud ones. Same fields, same wizard.



The slow part of fine-tuning is never the training run. It's the convert-and-pray that comes after. Nanotune's export writes a GGUF the same day, so the trained model drops straight into Ollama or llama.cpp without a conversion script in between.


A scrubber that reaches for the network ends up doing two jobs badly. prompt-scrub stops at the text: it strips identifiers in place, hands you back a session id, and gets out of the way. You pick the request path, the transport, the trust model. The seam stays where it should.



Your audit tool shouldn't need its own model config. Sentinel runs its scheduled audit through Nanocoder against the same providers you already set up for coding. Ollama, vLLM, llama-swap, all carry over. One provider stack, not two.



A local agent doesn't crash loudly. It stalls on a long token, then dies at the 2-minute default. nanocoder's agents.config.json: requestTimeout and socketTimeout both to -1 in your local-provider block. Agentic loops on a laptop routinely exceed the default.



You run the benchmark and every failure lands on the same two prompts you forgot to train on. Nanotune's bench output is the next dataset: add the cases that broke, rerun train, rerun bench. The loop closes in an afternoon, not a release cycle.


Why Mermaid validation was rejecting valid diagrams - and what fixed it


A bug in the v1.6.0 release of `validateMermaid` only showed up once we tried to use the option for what it was built for. The validator was annotating valid output, including correct diagrams the vision path had reconstructed from a PDF, as broken. The root cause was not Mermaid. It was a piece of browser-only code Mermaid ships with: DOMPurify.

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

## The symptom

`validateMermaid: true` is supposed to flag ` ```mermaid ` fences that don't parse. In practice, with `mermaid` installed, every labelled diagram was being flagged. A `graph TD` with `A[Start]` and `B{Choice}` got a `> [!WARNING]` callout. A `sequenceDiagram` with `Alice->>Bob: Hi` got one. A `classDiagram`, a `stateDiagram`, an `erDiagram`, a `mindmap`, all got one. The error message attached to every callout was the same: `DOMPurify.addHook is not a function`.

The diagrams themselves were fine. Mermaid was rejecting them by accident, and the validator was translating that accident into a syntax error.

That made the option actively harmful. The whole point of the flag is to catch what the PDF vision path, or any other model-assisted path, gets wrong. If the validator annotates a correct vision reconstruction as broken, it is inverting the contract: the trust check itself becomes the source of untrustworthy output.

## Why Mermaid needs a DOM

When you call `mermaid.parse(text)`, the parser walks the diagram and, at some point, runs the label text through a sanitizer. The sanitizer is DOMPurify. DOMPurify does not need the labels for any of that sanitization work; it is doing it because labels in Mermaid diagrams can contain user HTML, and DOMPurify is what guarantees user HTML does not become an XSS vector in a rendered output.

DOMPurify is a browser package. Its contract, going back to its first release, is that it attaches itself to whatever DOM API happens to be on the global scope. In a browser that is `window`, `document`, `Node`, `Element`, `HTMLTemplateElement`, and a handful of others. DOMPurify calls `globalThis.window.document` and friends the first time it runs. If `window` is `undefined`, DOMPurify does not fall back to "no DOM". It throws.

So the contract is: by the time Mermaid imports DOMPurify, the global scope has to look like a browser. Under Node there is no such global. The `mermaid.parse` call path that goes through the label sanitizer walks straight into `DOMPurify.addHook is not a function` and throws.

This is not a Mermaid design choice. It is a reasonable assumption that breaks in any environment without a DOM. JSDOM, happy-dom, jsdom-global, and a hand-rolled polyfill all fix it. The interesting question is how to install one without breaking the host process.

## The fix shape

The validator now does three things, in order, before it ever calls `mermaid.parse`:

1. Check whether a DOM is already installed. If it is, do nothing. A browser, a test suite that set up JSDOM, an earlier validator call: none of them get clobbered.
2. If not, dynamically import `happy-dom-without-node`, construct a `Window`, and copy the DOM globals it exposes onto `globalThis`. The imports happen after the check, so the dependency is only loaded on the validation path, and only when the host needs it.
3. After Mermaid finishes parsing, restore the global scope to exactly what it looked like on entry. Keys that were present are put back. Keys that were not present are removed.

The order matters. DOMPurify binds to the global scope the first time Mermaid imports it. Installing the DOM after the import, or installing it but not before the parser reads the labels, does not help. The install has to complete before `await import("mermaid")` returns.

## The two edge cases the install hides

### Saving and restoring `process`

`new Window({ url: "..." })` from happy-dom writes several properties onto `globalThis` as a side effect of construction. One of them is `process`. The happy-dom `Window` is itself a small browser-shaped object, but its constructor needs to expose a couple of node-style shims for happy-dom's own internals. `process` is one of them.

If you build the Window and then walk away, the rest of your code, anything that calls `process.exit`, anything that reads `process.argv`, anything that does `process.env.X`, is now running against happy-dom's shim instead of Node's real `process`. The shim looks similar; it is not the same. The shim's `process.exit` does not exit. Its `process.env` is empty.

The fix is mechanical. Save the original `process` immediately before construction, then write it back immediately after:

```typescript
const originalProcess = scope.process;
const win = new Window({ url: "https://example.com" });
if (originalProcess !== undefined) scope.process = originalProcess;
```

The window itself can stay on the global scope for the duration of validation; that is what DOMPurify expects. Only `process` needs to be restored eagerly, because losing it breaks the host process mid-import.

A regression test in `mermaid-validator.spec.ts` pins this: after `validateMermaid` returns, `globalThis.process` is the same object it was on entry, and `typeof globalThis.process.exit === "function"`. If a future refactor reorders those two lines and `process` leaks, the test fails.

### Assigning to `navigator`

`happy-dom-without-node` exposes a `Window.navigator`. The validator copies it onto `globalThis` so DOMPurify can read it. On most Node versions that is a normal property assignment. On newer Node versions (the change landed somewhere in the 20.x line) `navigator` is a getter-only property on the global scope, defined by the runtime itself, and writing to it with `scope.navigator = value` throws `TypeError: Cannot set property navigator of #<Object> which has only a getter`.

The install path uses a guarded assignment:

```typescript
const assign = (key: string, value: unknown) => {
  try {
    scope[key] = value;
  } catch {
    Object.defineProperty(scope, key, {
      value,
      configurable: true,
      writable: true,
    });
  }
};
```

`defineProperty` with `configurable: true` rewrites a getter-only property into a plain data property, which is what `assign` actually wants. The catch is for the assignment form, the inner block is for the rewrite. The same helper restores globals on the way out, so a host that ships with its own `navigator` polyfill gets the original back when the validator finishes.

## Distinguishing syntax errors from environmental ones

Even with the DOM installed, two diagram types (`pie` and `gitGraph`) still fail inside validation. They throw inside a parser chunk Mermaid lazy-loads the first time you ask for one of those types, and the lazy loader is not the same code path as the DOM-bound label sanitizer. With the DOM in place, those throws come up as "module not initialized" rather than "DOMPurify is missing", but they are still environmental, and still not the user's fault.

The validator now classifies a throw by its error message before deciding what to do with it:

```typescript
function isSyntaxError(message: string): boolean {
  return /parse error|no diagram type detected|expecting|lexical error|syntax error/i.test(
    message,
  );
}
```

A throw whose message matches the pattern is treated as a real syntax complaint, and the block is annotated with the `> [!WARNING]` callout. A throw whose message does not match is logged once via `console.warn` and the diagram is left alone. The block count warning is module-level so a 50-block document with a single lazy-loaded parser chunk failing only logs once, not 50 times. Two diagram types that hit the lazy-load path (`pie`, `gitGraph`) are documented in the changelog as skipped.

This is the more important half of the fix. Even if the install dance worked perfectly, there is no world in which the validator should report "invalid syntax" for a diagram that Mermaid failed to parse for environmental reasons. Doing so corrupts the output (the author's diagram is correct), and worse, it tells the user the trust check is lying. Saying nothing and continuing is the honest move.

## Idempotency

A separate but related fix: re-running the validator on Markdown it has already annotated used to stack a second warning onto the same block. The fix is a tight regex match against the 150 characters preceding each block, looking for the exact warning text the validator itself inserts. If the warning is already there, the block is left alone.

The fence-matching regex itself was tightened at the same time. The previous version was loose about whitespace around the closing fence, which produced unstable matches across passes and contributed to the stacking. The new regex anchors on `\r?\n` boundaries so identical input produces identical splits across passes.

## Why `happy-dom-without-node`

The dependency choice is deliberate and worth stating. `happy-dom-without-node` is a fork of happy-dom that does not pull `node:os` or any other `node:`-prefixed module at runtime. That makes it usable in three environments with the same import line: plain Node (the standard install), React Native (where `node:os` is undefined), and the browser (where it falls through to whatever is there). The regular `happy-dom` package would have worked for Node and the browser but would have broken React Native, where `validateMermaid` is a real install path.

The library only loads it dynamically, and only on the validation path, only if `validateMermaid: true` is set and a Mermaid fence is present. The default install footprint is unchanged. A user who never turns the option on never touches the dependency.

## What changed for users

Three concrete things, on top of "the validator now does what its name suggests":

- Diagrams with node labels, the most common case, are no longer annotated as invalid. The fix lands for `A[Start]`, `B{Choice}`, `-->|yes|`, and every class, state, ER, gantt, and mindmap diagram that uses them. The change shows up immediately in any document that previously produced a wall of false-positive warnings.
- The validator is now safe to call from a long-running process. It does not leak `window`, `document`, `process`, or any other DOM-shaped global onto the host's scope. A test in `mermaid-validator.spec.ts` asserts the round-trip explicitly.
- Two diagram types remain unsupported: `pie` and `gitGraph`. Both fail inside a parser chunk Mermaid lazy-loads, and the failure is environmental rather than syntactic. The validator logs once and moves on. The diagrams themselves render fine through any other path; the validator is just opting out of claiming it checked them.

## The wider pattern

This is one of two near-identical install-and-restore dances in the codebase. The Markdown parser does the same thing for Readability, which also needs a DOM, in `src/parsers/markdown-parser.ts`. The two implementations diverge in detail (Readability needs the document to live for the duration of a parse, not just the duration of a call), but the discipline is the same: snapshot the global scope on entry, install what you need, restore what you saved, only ever touch globals that were not already present.

The discipline is what makes a Node library that uses DOM packages safe to drop into a long-running service. Any library that copies DOM globals onto `globalThis` and forgets to undo it leaks. Any library that doesn't even check whether a DOM was already there can clobber a host that set one up first. The check, the snapshot, and the restore are three lines that, together, are the difference between "works" and "works in a long-running process too".

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


A bug in `validateMermaid` shipped in get-md v1.6.0 that we finally tracked down in 1.7.0: every labelled diagram was being flagged as broken syntax.

The error message was always the same: `DOMPurify.addHook is not a function`. The diagrams were fine. Mermaid is a browser-shaped package, and the label sanitizer it ships with (DOMPurify) attaches to whatever DOM is on the global scope at import time. Under plain Node there is no DOM, so any diagram carrying node labels (`A[Start]`, `B{Choice}`, `-->|yes|`, sequence, class, state, ER, gantt, mindmap) walked straight into a throw. The validator was treating every throw as a syntax error, which is the worst possible behaviour for a trust check.

The fix in 1.7.0:

- Install a headless DOM (`happy-dom-without-node`) dynamically, *before* importing Mermaid. DOMPurify binds at module load time, so order matters.
- Snapshot the global scope, restore it exactly on the way out. The host process is unchanged.
- Handle two edge cases the install hides: happy-dom replaces `globalThis.process` during `Window` construction, and `navigator` is getter-only on newer Node versions. Both are saved and restored.
- Classify parser throws by error message. Only genuine syntax errors annotate the document. Anything environmental (the `pie` and `gitGraph` parser chunks fail this way) logs once and leaves the diagram alone.

The full breakdown, including the install-and-restore code, lives on the GitHub Discussion linked below. Worth reading if you have ever shipped a Node library that uses a DOM-shaped dependency.

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


Here's a debugging story from the get-md 1.7.0 release that I think is worth sharing.

In 1.6.0 we shipped `validateMermaid: true`, an opt-in option that runs every ` ```mermaid ` fence in the output through Mermaid's own parser and annotates the ones that fail. The idea was straightforward: if you're using the PDF vision path to reconstruct diagrams, you want to know which ones the model got wrong so you can repair them rather than ship broken Markdown.

The first time someone ran it on a real document, every labelled diagram came back flagged. `graph TD` with `A[Start]`, decision diamonds, labelled edges, sequence diagrams, class diagrams, state diagrams, ER diagrams, mindmaps: all of them annotated as `> [!WARNING]` Invalid Mermaid syntax. The error message attached to every annotation was `DOMPurify.addHook is not a function`.

The diagrams were fine. Mermaid was rejecting them by accident. The validator was translating that accident into a syntax error.

The reason turned out to be a chain of dependencies. Mermaid ships DOMPurify for sanitizing label text. DOMPurify is a browser package and its contract is that it attaches to whatever DOM is on the global scope at import time. Under plain Node there is no DOM, so any label that goes through the sanitizer walks straight into `DOMPurify.addHook is not a function` and throws.

The validator was treating every throw as a syntax error, which is the worst possible behaviour for a trust check. The whole point of the option is to flag genuine mistakes. If it flags correct output, it is inverting the contract.

The fix in 1.7.0 is a headless-DOM install dance:

1. Before importing Mermaid, check whether `globalThis.window` is already defined. If it is, do nothing: a browser, a test suite that set up JSDOM, an earlier validator call. None of them get clobbered.
2. If not, dynamically import `happy-dom-without-node`, construct a `Window`, and copy the DOM globals it exposes onto `globalThis`.
3. Snapshot the global scope first. Restore it exactly on the way out: keys that were present go back, keys that were not present get removed.
4. Only then import Mermaid. Order matters: DOMPurify binds to the global scope the first time Mermaid is imported, so the install has to complete before the import returns.

Two edge cases the install hides that I had not appreciated before writing it:

- `new Window({ url: "..." })` from happy-dom writes `process` onto `globalThis` as a side effect of construction. The happy-dom Window is itself a small browser-shaped object, but its constructor needs to expose a couple of node-style shims for happy-dom's own internals. If you build the Window and walk away, the rest of your code runs against happy-dom's `process` shim instead of Node's real `process`. The shim looks similar; it is not the same. The fix is to save the original `process` immediately before construction and write it back immediately after.
- `navigator` is a getter-only property on the global scope on newer Node versions. Writing to it with `globalThis.navigator = value` throws `TypeError: Cannot set property navigator of #<Object> which has only a getter`. The install path uses a guarded assignment that falls back to `Object.defineProperty` with `configurable: true` to rewrite the getter-only property into a plain data property.

A separate fix is the error classifier. Even with the DOM in place, `pie` and `gitGraph` diagrams still fail inside validation. They throw inside a parser chunk Mermaid lazy-loads the first time you ask for one of those types, and the failure is environmental rather than syntactic. The validator now classifies a throw by its error message before deciding what to do with it. A throw whose message matches the pattern `parse error|no diagram type detected|expecting|lexical error|syntax error` (case-insensitive) is treated as a real syntax complaint, and the block is annotated. A throw whose message does not match is logged once via `console.warn` and the diagram is left alone.

This is the more important half of the fix. Even if the install dance worked perfectly, there is no world in which the validator should report "invalid syntax" for a diagram that Mermaid failed to parse for environmental reasons. Doing so corrupts the output (the author's diagram is correct) and worse, it tells the user the trust check is lying.

A related fix is idempotency: re-running the validator on Markdown it has already annotated used to stack a second warning onto the same block. The fix is a regex match against the 150 characters preceding each block, looking for the exact warning text the validator itself inserts. If the warning is already there, the block is left alone. The fence-matching regex itself was tightened at the same time.

`happy-dom-without-node` (rather than `happy-dom`) was a deliberate choice. The `-without-node` variant does not pull `node:os` or any other `node:`-prefixed module at runtime, which makes it usable in three environments with the same import line: plain Node (the standard install), React Native (where `node:os` is undefined), and the browser (where it falls through to whatever is there). The library only loads it dynamically, and only on the validation path, and only if `validateMermaid: true` is set and a Mermaid fence is present. The default install footprint is unchanged.

The wider pattern is one I had not internalized before this work. Any Node library that uses a DOM-shaped dependency has to follow the discipline: snapshot the global scope on entry, install what you need, restore what you saved, only ever touch globals that were not already present. The check, the snapshot, and the restore are three lines that, together, are the difference between "works" and "works in a long-running process too".

The full breakdown including the install-and-restore code is in the GitHub Discussion linked below. Worth a read if you have ever shipped a Node library that uses a DOM-shaped dependency.

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


In get-md v1.6.0, validateMermaid flagged every labelled diagram as broken syntax. Root cause: DOMPurify (bundled with Mermaid) needs a DOM, and plain Node doesn't ship one. Fixed in 1.7.0.

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

#mermaid #nodejs

Reconstructing diagrams from PDFs by vision model - and the limits we kept


The new opt-in PDF diagram reconstruction in get-md 1.7.0 is, by the numbers, a small feature. A handful of source files, an optional peer dependency pair, and a 10-page cap. The interesting part is not the feature itself. It is the three deliberate limits around it: remote providers only, a 10-page render cap, and a hard short-circuit on pure-scan PDFs. Each one of those limits looks, at first glance, like something a more complete implementation would lift. None of them should be lifted, and this post is the case for keeping them.

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

## What the path actually does

With `useLLM: true`, a remote vision-capable provider, and `pdfjs-dist` plus `@napi-rs/canvas` installed, get-md renders the first 10 pages of a PDF to JPEG images at 2x scale and sends them to the model alongside the extracted text. The model's system prompt asks it to emit Mermaid fences inline where a diagram appeared in the page. That output rides the same Markdown pipeline as a text-only result, including the new `validateMermaid` step.

The mechanics are spread across four files worth naming, because the limits live in each of them and it is useful to know where:

- `src/extractors/pdf-renderer.ts` renders pages to JPEG and enforces the 10-page cap with a `console.warn` naming it.
- `src/extractors/pdf-extractor.ts` extracts the text that the vision path is layered on top of, and short-circuits to an empty result when there is no text at all.
- `src/index.ts` holds `supportsVision`, `tryRenderPdfToImages`, and `emptyPdfResult`, and is the only place where remote-provider detection happens.
- `src/converters/remote-llm-converter.ts` is the path that actually talks to a vision model, including the soft-fail fallback to text-only when the vision request itself errors.

The headline release post covered the surface area. This one is the limits, and why they are not arbitrary.

## Limit one: remote providers only

The vision gate in `supportsVision` is short enough to quote in full:

```typescript
function supportsVision(options?: MarkdownOptions): boolean {
  if (!options?.useLLM) return false;
  if (!options.llm) return false; // defaults to local-llama without explicit config
  return options.llm.sdkProvider !== "local-llama";
}
```

Two conditions, both must hold. `useLLM` has to be on, and the configured provider has to be a non-local one. The `!options.llm` check matters: without an explicit `llm` config the path defaults to `sdkProvider: "local-llama"`, and that branch never even asks the question. This is the part that surprises people who turn on `useLLM` and expect the local path to magically handle diagrams.

The reason is honest, and it is about what local-llama actually is. The local ReaderLM-v2 path in this codebase is text-only. It has no vision input. It does not accept images. If the renderer fed it JPEGs, they would be ignored, dropped, or counted as a malformed user message, depending on the model. Running the renderer at all on a text-only path would burn the 10-page render budget for nothing the model can see.

So the gate is not a design preference. It is the absence of a feature that does not exist in the underlying model. The 1.7.0 release notes state this plainly: "The local ReaderLM-v2 path is text-only, and so is `useLLM` with no `llm` config, since that defaults to local-llama." A user who wants diagram reconstruction and runs locally has only one honest path today: route through a remote provider that supports multimodal input. Wrapping the local path with a fake vision layer would be a worse user experience than telling them up front.

The remote-only choice also keeps the default install footprint reasonable. `pdfjs-dist` and `@napi-rs/canvas` are loaded lazily, on demand, only when `supportsVision` returns true. A user who never sets `useLLM`, or who sets it without an explicit remote provider, never touches either dependency. The renderer is imported via `await import("./extractors/pdf-renderer.js")` and the canvas imports inside the renderer function itself, so the cost is paid only when the feature is used. Lifting the remote-only limit, in either direction, breaks one or the other of those properties.

There is one case the limit makes genuinely awkward, and it is worth naming: a privacy-respecting user who wants to run everything on their own hardware and is fine paying a model-quality cost for it. The current answer for that user is no, the PDF vision path will not work for them. The future answer is a vision-capable local model behind the same gate, but that is a different feature, not a relaxation of this one.

## Limit two: the 10-page render cap

The cap lives in one place:

```typescript
const MAX_PAGES_TO_RENDER = 10;
if (pdf.numPages > MAX_PAGES_TO_RENDER) {
  console.warn(
    `[get-md] PDF has ${pdf.numPages} pages, which exceeds the rendering limit of ${MAX_PAGES_TO_RENDER}. ` +
      `Only the first ${MAX_PAGES_TO_RENDER} pages will be processed for diagrams.`,
  );
}
const pagesToRender = Math.min(pdf.numPages, MAX_PAGES_TO_RENDER);
```

10 pages, with a warning that names the cap, and a `Math.min` so the loop never iterates past it. Text extraction still covers the whole document, so a long PDF loses only the diagram reconstruction, not the content.

The cap is not arbitrary. It is a context-budget decision that the model side enforces whether we like it or not. Each rendered JPEG at 2x scale is hundreds of thousands of pixels. A modern vision-capable model accepts a handful of images before the multimodal message parts crowd the context window, push out the text, and start producing degraded output on both. Asking the same model to reconstruct diagrams from page 1 through page 400 of a handbook is not a stretch goal. It is a request that gets back lower-quality Markdown for every page, including the ones the user cared about.

Picking 10 is partly empirical. It is enough pages that a typical whitepaper, slide deck, or design doc has its diagrams covered. It is small enough that even a multi-image request stays well inside a normal context window. Lifting it would not improve the result on long documents; it would degrade the result on the same long documents. Lifting it without degrading the result would require a chunked, multi-request strategy with merge logic, which is the kind of feature that needs design, not just a higher constant.

There is also a second reason, which is operational. The renderer holds onto `pdfjs-dist` and `@napi-rs/canvas` for the duration of a conversion. A 400-page render at 2x is a noticeable CPU and memory spike on the host process. The cap turns the worst case into a predictable one. A user who hits the cap gets a warning in stderr and the first 10 pages of diagrams; they do not get a multi-minute hang and an out-of-memory error.

The honest workaround for long PDFs is structural. If you know your diagrams cluster early, the cap covers you. If they cluster late, render the relevant section as its own PDF first. If they are scattered, this is not the right tool for the job yet, and the path would tell you that with a warning rather than producing a result that quietly degraded partway through.

## Limit three: pure-scan PDFs short-circuit early

This is the one the release notes call out as a known limitation:

> 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.

The relevant code is in `src/index.ts`, in both the buffer and the URL paths:

```typescript
if (!pdfText.trim()) {
  return emptyPdfResult(buffer.length);
}
inputHtml = buildPdfHtml(reconstructPdfHtml(pdfPages), pdfMeta);
forceExtractContentOff = true;

const images = await tryRenderPdfToImages(buffer, options);
```

The vision render call sits *after* the empty-text short-circuit, not before it. The text comes back empty, `emptyPdfResult` returns a `MarkdownResult` with `markdown: ""` and `inputLength` set to the buffer size, and the function exits. `tryRenderPdfToImages` is never reached. The user gets an empty result that is the same shape a text-less PDF has produced since 1.6.0.

Read in isolation that looks like an oversight. In context it is the deliberate consequence of two earlier decisions. First, `pdf-parse` is the text extractor of record, and what it returns is the only signal the rest of the pipeline uses to decide the document is real. Second, the renderer is intentionally lazy: it imports `pdfjs-dist` and `@napi-rs/canvas`, hands pages to a vision model, and pays for all of that, only on a code path where text was extracted. Lifting the empty-text short-circuit to "still run the vision renderer and ask the model to read the whole thing" turns this from a cheap opt-in into the most expensive path in the library, on the input type where the user is most likely to be unhappy with the cost.

There is also a correctness angle. `emptyPdfResult` returns a result with `readabilitySuccess: false`, an empty body, and `inputLength` set. A caller that already learned in 1.6.0 to detect "this PDF yielded no text, treat it as needing OCR" gets the same signal in 1.7.0. The 1.6.0 release notes are explicit about this contract: "Scanned/text-less PDFs return an empty result with a non-zero `inputLength` (a signal OCR is needed)." Carrying the contract forward in 1.7.0, even with a vision path sitting one branch away, is the conservative move. A user who expects "give me back what you can, even if the text is empty" would get a worse tool, not a better one.

The honest fix for the pure-scan case is upstream: run OCR, or use a tool whose job is OCR, then feed the OCR'd text back in. The vision path will not paper over that for you, and that is the right design call.

## What "fails soft" actually means here

There are two fail-soft paths layered on top of the three limits, and they are part of the same opinion. The renderer fails soft when dependencies are missing or a render throws: a `console.warn` and the conversion continues without images. The vision request fails soft when the model itself rejects the multimodal message: `RemoteLlmConverter.convert` catches the error, swaps in the text-only system prompt, drops the image parts, and retries the same call. Either way the user gets Markdown. They get less Markdown than the full path promised, but they get Markdown.

The retry is interesting because it is the only place in the path where the user-facing text could change shape. The vision request produces a richer system prompt ("you are provided with the text of the page, as well as images of the rendered page, if the page contains diagrams, flowcharts, or architecture diagrams, reconstruct them as Mermaid code block fences"). The fallback reverts to the plain text-to-Markdown system prompt. The text the model sees is the same; what it does not see is the images. A user who later turns off `useLLM` and re-runs the same file should land on the same text-only path, and the fallback makes the failure mode of "vision did not work this run" behave the same as "vision was not asked this run".

Pair this with `validateMermaid: true` and the soft-fail story is honest end-to-end. A user who runs the vision path gets whatever the model thinks the diagrams were. A user who pairs that with validation gets any reconstruction the model got wrong, flagged with a `> [!WARNING]` callout, kept in the output for repair. The two features are designed to be used together, and the limits in the vision path are written with the assumption that the validator will catch what the vision model misses.

## What the limits are not

Three things the limits are not, because each one comes up in user feedback:

- They are not a sign the feature is unfinished. A finished-feeling vision path that quietly degrades long PDFs, quietly fails on scans, and quietly ignores the local provider would be worse than the version that warns loudly and stops at the right edge.
- They are not a roadmap commitment to lift them. "Remote providers only" depends on a vision-capable local model existing and being integrated, which is a different feature. "10 pages" depends on a chunked multi-request strategy that does not exist yet. "No empty text" depends on a different extraction path that does not exist yet.
- They are not a restriction on what users can do. Every limit has a clean escape hatch the docs spell out: a remote provider with multimodal support, a sectioned PDF or a different tool for long documents, OCR or a separate OCR-first pipeline for pure scans. The limits are the shape of the feature, not a wall around it.

## What we kept, and what we did not

The PDF vision path in 1.7.0 is what survived the review pass: a deliberately narrow feature with three limits and two soft-fail paths, every limit encoding a tradeoff the user should be able to reason about. The narrowness is the point. A vision path that handled every PDF, ran locally, and never failed would either not work (it would silently produce wrong output), or be the most expensive thing in the library (it would run heavy multimodal inference on every scan, every long PDF, every input type).

The constraints below are the ones we kept:

- Remote providers only, because local-llama is text-only by design.
- 10 pages only, because context budget and host memory are real and the cap makes both predictable.
- No pure scans, because empty text is the contract that lets the rest of the pipeline tell "this is a real PDF" from "this is a scan that needs OCR".

If you want to dig into the renderer or the soft-fail paths, `src/extractors/pdf-renderer.ts`, `src/converters/remote-llm-converter.ts`, and the `supportsVision` and `emptyPdfResult` helpers in `src/index.ts` are the entry points. The [Diagrams and Mermaid guide](https://docs.nanocollective.org/get-md/docs/guides/mermaid) and [Remote LLM guide](https://docs.nanocollective.org/get-md/docs/guides/remote-llm) document the configuration shape and the failure modes end-to-end. Feedback on the limits, especially the ones that hurt your workflow, is welcome on GitHub or Discord.

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

The three limits the PDF vision path keeps on purpose


Three limits in get-md 1.7.0's PDF diagram vision path, and why each one is on purpose.

The opt-in vision reconstruction in this release, remote model renders the first 10 pages of a PDF and asks for Mermaid back inline where a diagram appeared, looks, on paper, like a feature that should "just handle every PDF." It does not, and the limits are the feature.

1. **Remote providers only.** The local ReaderLM-v2 path is text-only. There is no vision input. Wrapping the local path with a fake vision layer would silently produce worse output. The gate in `supportsVision` is one short function: `useLLM` on, explicit `llm` config, `sdkProvider !== "local-llama"`. If you want diagrams, route through a remote multimodal provider.

2. **10 pages only.** A 2x JPEG is hundreds of thousands of pixels. Ask a vision model to read 400 pages and the context window crowds, the text degrades, and the diagrams you actually cared about come back worse. The cap is empirical and honest. A warning names it. Text extraction still covers the whole document.

3. **Pure scans short-circuit early.** A PDF with no extractable text still returns an empty result before the renderer is even called. The `emptyPdfResult` contract from 1.6.0, "this needs OCR", is preserved. The vision path is not OCR. Run OCR first if your input is a scan.

Two soft-fail paths sit on top: missing renderer dependencies warn and continue, and a failed vision request retries the same call text-only. Either way you get Markdown. Pair the path with `validateMermaid: true` and the soft-fail story is honest end-to-end.

The narrowness is the point. A vision path that handled every PDF, ran locally, and never failed would be the most expensive thing in the library, and would silently produce wrong output where it failed.

Full code walkthrough in the GitHub Discussion.

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


A short post about a part of get-md 1.7.0 I want to defend before someone files a "this should work for X too" issue.

The new opt-in PDF diagram reconstruction is the kind of feature that *looks* like it should be turned up. It renders the first 10 pages of a PDF to JPEG, sends them to a vision-capable model alongside the text, and asks for Mermaid fences back where the diagrams appeared. A reasonable reader's question is: why isn't this more aggressive? Why doesn't it run on every page of every PDF? Why doesn't it work locally? Why doesn't it handle scans?

The answer is that each limit encodes a tradeoff, and the tradeoff is the feature.

**Remote providers only.** The local ReaderLM-v2 path in get-md is text-only. There is no vision input. If we rendered pages for the local path, we'd burn the renderer budget for input the model would silently drop. The gate is a four-line function: `useLLM` on, an explicit `llm` config (because the default is local-llama), and `sdkProvider !== "local-llama"`. That's it. If you want PDF diagrams reconstructed, route through a remote multimodal provider. We load `pdfjs-dist` and `@napi-rs/canvas` lazily, only when that gate passes, so the default install footprint stays small.

**10 pages only.** A 2x JPEG is hundreds of thousands of pixels. Ask a vision model to read 400 pages and the multimodal message parts crowd the context window, the text degrades, and the diagrams you actually cared about come back worse. The cap makes the worst case predictable: a warning names it, and text extraction still covers the whole document. Lifting the constant without a chunked multi-request strategy would degrade the result on the same long documents. We picked 10 because it covers a typical whitepaper or design doc and stays inside a normal context window. If your diagrams cluster late, render that section as its own PDF. If they are scattered through 400 pages, this is not the right tool for the job yet.

**Pure scans short-circuit early.** A PDF with no extractable text returns an empty result before the renderer is even called. The `emptyPdfResult` contract from 1.6.0, "this needs OCR", is preserved. The vision path is not OCR. Run OCR first if your input is a scan. We considered letting the vision path run on scans, and the only honest version of that is also the most expensive path in the library, on the input type where the user is most likely to be unhappy with the cost. We chose not to.

**The two soft-fail paths on top.** Missing renderer dependencies warn and the conversion continues without images. A failed vision request retries the same call text-only, swapping the system prompt and dropping the image parts. Either way you get Markdown. Pair the vision path with `validateMermaid: true` and the soft-fail story is honest end-to-end: the validator catches what the vision model got wrong, the diagrams stay in the output with a `> [!WARNING]` callout for repair, and you do not silently lose content.

A vision path that handled every PDF, ran locally, and never failed would either not work, or be the most expensive thing in the library. The narrowness is the point. The limits are the shape of the feature.

If a limit blocks a real workflow for you, that is useful signal. Open an issue, or find us on Discord. But the limits themselves are not going to lift quietly, and I wanted to write down why before the first "why doesn't this do X" lands.

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


The PDF vision path in get-md 1.7.0 keeps three limits on purpose: remote providers only, 10 pages, and no pure scans. Each one encodes a tradeoff worth reading before you rely on it.

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

September 2026

Tuesday, September 16 posts