
You've pasted an env block into ChatGPT to "ask a quick question." It left your machine. prompt-scrub rewrites those tokens to stable placeholders before the message does, and keeps the real values on disk.


30 days is the floor. Every whitepaper at the Nano Collective sits in public review for at least that long - status badge shows the close date, anyone can file issues. The build decision waits for the window to close.



"AI conversion" usually means someone else's machine. In `get-md`, `useLLM: true` with no `llm` block runs ReaderLM-v2 on-device via node-llama-cpp. One ~1.12GB download, then the page never leaves your laptop.


Most migration libs throw a generic Error and leave you parsing the message. json-up throws three named types: VersionError, MigrationError, ValidationError. You know what actually went wrong without guessing.


Your tool's parameter values get shell-quoted before they hit the body, so even '; rm -rf /; #' lands in echo as one literal string. nanocoder custom tools block injection at the template layer, not by trusting the model to behave.


Your training data shouldn't leave the machine it's written on.

Nanotune assumes local is the default. LoRA on Apple Silicon, MLX under the hood, no upload anywhere in the pipeline.



The Nano Collective has relaunched its website. This post is a walkthrough of what changed, why, and what it sets up for the next round of announcements.

The starting point is the same one we use for the docs site and the READMEs: the [Brand Guidelines](https://docs.nanocollective.org/collective/organisation/brand) are the source of truth for how the collective is talked about and presented. The previous site drifted from those guidelines in several places. The new site is an attempt to remove that drift.

## The headline change: principles lead

The three principles the collective holds itself to (**Privacy First, Open Source, Local First**) now lead the homepage in the order they appear in the brand guidelines: privacy-respecting, local-first, open for all. That ordering is not decoration. It is the filter applied when deciding what the collective builds, how it builds it, and who gets to shape it.

The previous version had these principles further down the page, framed as values. They are not values. They are the filter. The redesign puts them where the filter belongs.

A note on why this matters for the projects specifically. The principles page in the brand guidelines spells out that the second paragraph of the canonical collective description can be dropped where space is tight, but the principles should never be paraphrased loosely. The site now reflects that. The same three phrases appear in the same order wherever they show up.

## Information architecture

Two structural changes to how the site is organised:

**1. Flagship projects get landing pages.** [Nanocoder](https://github.com/Nano-Collective/nanocoder) and [Nanotune](https://github.com/Nano-Collective/nanotune), the two projects most often pointed at when introducing the collective, each have a dedicated landing page now. The previous site had a single paragraph for each. The new pages describe what the project does, link to the repo, link to the docs, and stay in the same voice as the project's own README.

**2. The full project list is alphabetised on its own page.** The four shipped projects (Nanocoder, Nanotune, get-md, json-up) are listed in alphabetical order on the projects page, with one paragraph each and a link to the corresponding repo. The brand guidelines ask for alphabetised listings unless there is a deliberate reason to prioritise; with the landing pages for the two flagship projects carrying the bulk of the weight, the projects page can default to alphabetised.

get-md and json-up are worth naming explicitly. They often get skipped in copy that leads with the AI-shaped projects, but they are real, shipped, maintained tools under the umbrella. The new site gives them the same one-paragraph treatment as the others.

## Live proof replaces curated snapshots

The old "community" section was a curated screenshot of activity: a Discord message, a GitHub notification, a Reddit thread. The new site has:

- **Live GitHub, Discord, and Reddit stats** on the homepage, updated in real time rather than maintained by hand.
- **A public growth page** that plots the same data over time, so the trajectory is visible to anyone who wants to look.
- **A feed of the latest discussions** surfaced directly from the relevant channels.

These are small changes in isolation, but they matter for the same reason the [Open Collective ledger](https://opencollective.com/nano-collective) matters for finances: live data is harder to misrepresent than curated data. The collective's stated commitment to transparency by default is now extended to its own growth metrics.

A **public analytics page** also ships with the redesign. The collective treats its own site the same way it treats the projects it ships: traffic patterns are visible to anyone who wants to look.

## The branded asset generator

One of the smaller-but-meaningful pieces is a branded asset generator built into the site. Every social post, blog header, and shared image now comes out of the same generator with the same visual rules applied.

The reason this matters: per-channel manual asset tweaks were quietly drifting the brand across surfaces. The previous site's visuals would appear slightly differently on LinkedIn than on the docs site than on a GitHub social card, because each surface was being produced by hand. The generator removes that variation by enforcing the same rules at the source.

It also lowers the bar for contributors. Anyone in the collective who needs to produce a social image now uses the generator rather than asking the design-adjacent folks to produce one. That's a small thing in isolation; in aggregate it's the difference between a brand that's enforced by the people who have time to enforce it and a brand that's enforced by the codebase.

## Visual language

The new visual treatment is high-contrast and deliberately developer-terminal in feel:

- Black-and-white layouts with sharp edges. No rounded pastel blocks.
- Monospace detailing in section headers, badges, labels, and inline code-equivalents.
- An electric-blue accent reserved for interactive elements and emphasis.
- An animated ASCII-art backdrop on the homepage that nods to the kind of environment the collective's tools run in.
- Editorial typography replacing the previous display fonts.

The brief was simple: make the site look like what we actually ship. Our READMEs start with the canonical project tagline ("Built by the Nano Collective, a community collective building AI tooling not for profit, but for the community") and lean on monospace detailing, plain typography, and clear structural hierarchy. The site now reads the same way.

## Under the hood

The codebase was tightened as part of the redesign. Entrance animations are subtler, the layout system is consolidated, the dependency footprint is smaller, and the build pipeline is faster. None of this is headline material on its own, but it removes the small drag that compounds over time.

## What this sets up

ContentForest has been live for a while and now has its own page on the site. The broader pattern (software whose primary job is to coordinate agents and surface their work to humans) is one the collective will keep shipping on. The new site is the place those announcements land.

Nothing else is promised here. The collective is volunteer-led today, and the explicit mission is to grow the contributor community and progressively decentralise. The site is one of the things that has to be in shape for that to work, and it's in better shape now. The next announcements will show up when the projects they're about are ready to be talked about, not before.

## How to read more

- The new site: [nanocollective.org](https://nanocollective.org)
- The brand guidelines (the rules the new site now reflects): [docs.nanocollective.org/collective/organisation/brand](https://docs.nanocollective.org/collective/organisation/brand)
- The organisation overview (how the collective is structured and funded): [docs.nanocollective.org/collective/organisation](https://docs.nanocollective.org/collective/organisation)
- The projects page (the full list and how projects come to life): [docs.nanocollective.org/collective/projects](https://docs.nanocollective.org/collective/projects)

If something on the new site reads as off-message, that's a bug. Open an issue on the docs repo and we'll iterate. The guidelines are versioned and meant to be updated when the brand shifts.

New Nano Collective website: principles first, live proof, tighter codebase


The Nano Collective has relaunched its website. The previous version was soft and colourful. The new one looks and reads like what the collective actually builds.

The headline change is the information architecture. The homepage leads with the three principles the collective holds itself to (Privacy First, Open Source, Local First) rather than burying them. The principles are in that order because that's the order they appear in the [Brand Guidelines](https://docs.nanocollective.org/collective/organisation/brand): privacy-respecting, local-first, open for all. Now the site reflects that.

The flagship projects, [Nanocoder](https://github.com/Nano-Collective/nanocoder) and [Nanotune](https://github.com/Nano-Collective/nanotune), each have a dedicated landing page instead of sharing a single paragraph. The full project list (Nanocoder, Nanotune, get-md, json-up) is on the projects page, alphabetised as the brand guidelines ask.

A few things shipped under the hood that are worth naming:

- **Live community proof.** GitHub, Discord, and Reddit stats on the homepage, plus a feed of the latest discussions. Numbers update in real time rather than being curated snapshots.
- **A growth page** that publishes the same data over time, so the trajectory is visible to anyone who wants to look.
- **A branded asset generator** for consistent social imagery across channels.
- **A public analytics page** so the collective's own site traffic is treated the same way it treats everything else: open and inspectable.
- **A leaner codebase** under the same site, with entrance animations and a tightened layout system.

The visual treatment is deliberate. Black-and-white layouts, sharp edges, monospace detailing, an electric-blue accent, an animated ASCII-art backdrop. The brief was to make the site look like what we actually ship: open-source, local-first, developer-facing. The previous design was pleasant. The new one is honest about what the collective is.

This is also the foundation for what's coming. The site now has the room to announce the tools along the shape we keep talking about, software whose job is to coordinate agents and surface their work to humans, starting with ContentForest and continuing from there. Nothing promised, nothing dated.

The Nano Collective is a community-led group building open-source AI tooling not for profit, but for the community. Read the new site at https://nanocollective.org.


**TL;DR:** We rebuilt the Nano Collective website. The redesign is less about the new visuals and more about the site finally matching the brand guidelines we already had. The three principles lead the homepage, flagship projects get real landing pages, and community stats are live rather than curated.

---

A bit of context. We're the [Nano Collective](https://nanocollective.org), a small community-led group of developers, designers, and maintainers building open-source AI tooling not for profit, but for the community. Everything is [fiscally hosted by the Open Source Collective](https://opencollective.com/nano-collective) and published transparently. We have four shipped projects under the umbrella right now: [Nanocoder](https://github.com/Nano-Collective/nanocoder) (a terminal coding agent), [Nanotune](https://github.com/Nano-Collective/nanotune) (fine-tuning tooling for small local models), [get-md](https://github.com/Nano-Collective/get-md) (HTML to Markdown converter), and [json-up](https://github.com/Nano-Collective/json-up) (type-safe JSON migrations). We also have a number of whitepapers in the [docs site](https://docs.nanocollective.org) covering longer-term ideas (Sentinel, the Private Inference Proxy, the Prompt Scrubber, the Marketplace, the Nano OS, and the Docs Forest).

The old site was fine. It was soft, colourful, and pleasant to look at. The problem was that it didn't read like what we actually ship. Our README files start with the canonical project tagline ("Built by the Nano Collective, a community collective building AI tooling not for profit, but for the community") and lean on monospace detailing, plain typography, and clear structural hierarchy. The old site didn't carry any of that.

## What changed in the design

The new visual treatment is high-contrast and deliberately developer-terminal in feel:

- Black-and-white layouts, sharp edges, no rounded pastel blocks.
- Monospace detailing in section headers, badges, and labels.
- An electric-blue accent reserved for interactive elements and emphasis.
- An animated ASCII-art backdrop on the homepage that nods to the kind of environment our tools actually run in.

Editorial typography replaced the previous display fonts. The effect is a site that reads like internal engineering documentation, closer to our READMEs and release notes than to a marketing page.

## What changed in the information architecture

The three principles (Privacy First, Open Source, Local First) now lead the homepage in the order they appear in the [Brand Guidelines](https://docs.nanocollective.org/collective/organisation/brand). The previous version had them further down, framed as values rather than as the filter they actually are.

Nanocoder and Nanotune each got a dedicated landing page. The full project list moved to a structured projects page, alphabetised, with one paragraph per project and a link to each repo. get-md and json-up are also on the page; flagging them matters because they often get overlooked in copy that leads with the AI-shaped projects.

## What changed in proof

The old site had a "community" section that was a curated screenshot of activity. The new site has:

- **Live GitHub, Discord, and Reddit stats** on the homepage, updated in real time.
- **A public growth page** that plots the same data over time, so the trajectory is visible.
- **A feed of the latest discussions** surfaced directly from the relevant channels.
- **A public analytics page** so traffic to the collective's own site is treated the same way we treat our own work: open and inspectable.

## What changed in the day-to-day

There's a branded asset generator now. Every social post, blog header, and shared image can come out of the same generator with the same visual rules applied. That's a small thing in isolation, but it ends the per-channel manual tweaks that were quietly drifting the brand across surfaces.

Behind the scenes the codebase was tightened. Entrance animations are subtler, the layout system is consolidated, and the dependency footprint is smaller. Nothing flashy, just less to maintain.

## What this site is for next

The redesign creates room for the next round of announcements. ContentForest has been live for a while and has its own page; the broader pattern of software that coordinates agents and surfaces their work to humans is one we'll keep shipping on. The new site is the place those announcements land.

Nothing else to promise. The collective is volunteer-led today and our explicit mission is to grow the contributor community and progressively decentralise. The site is one of the things that has to be in shape for that to work, and it's in better shape now.

If any of this lands (the principles-first ordering, the live stats instead of curated ones, the asset generator removing manual drift), come find us at https://nanocollective.org. The codebase for the site is public, the [docs](https://docs.nanocollective.org) are public, and the contributor channels are linked from both.


The Nano Collective site has been rebuilt around the three principles the collective is actually built on: privacy-respecting, local-first, open for all. Black-and-white layout, monospace detailing, electric-blue accent, live community stats. https://nanocollective.org


get-md v1.6.0 is out. The library is no longer HTML-only: PDF, DOCX, and Markdown inputs join HTML and URLs, with auto-detection on the file extension or magic bytes. Behind that headline is a launch-hardening pass over the whole multi-format surface that closes a set of real bugs surfaced during review.

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

## What changed

`convertToMarkdown` and the CLI now accept four input formats: HTML strings, URLs, PDF, DOCX, and Markdown files. Pass a `Buffer` or a `ContentSource` and get-md routes it to the right extractor automatically. The CLI detects format from the file extension, and for stdin it inspects the `%PDF` magic bytes directly.

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

// PDF
const pdf = await convertToMarkdown(pdfBuffer);
console.log(pdf.markdown);

// DOCX
const docx = await convertToMarkdown(docxBuffer);

// Markdown (skips HTML parsing, runs optimization passes only)
const md = await convertToMarkdown("# Heading\n\nAlready markdown.");
```

## PDF ingestion

Pass a PDF `Buffer` (auto-detected via the `%PDF` magic bytes) or point the CLI at a `.pdf` file or URL. Text is reconstructed into real structure: wrapped lines reflow into paragraphs, ALL-CAPS lines become headings, `•` and numbered lines become lists with wrapped continuations folded in, and repeated running headers and footers are dropped.

Title, author, and creation date are pulled from the PDF info dictionary into the frontmatter, alongside the computed `wordCount` and `readingTime`. The `-- N of M --` page markers that `pdf-parse` emits by default are stripped before output. Readability is disabled for PDF input so body text is never dropped as boilerplate (a class of bug that was reachable in earlier code).

Scanned or text-less PDFs return an empty result with a non-zero `inputLength`, which is the signal that OCR is needed rather than a successful extraction. The extractor is powered by `pdf-parse`.

## DOCX ingestion

Pass a DOCX `Buffer` (auto-detected via the ZIP/`PK` magic bytes) or point the CLI at a `.docx` file or URL. Two new exports are available for direct use:

```typescript
import {
  convertDocxToMarkdown,
  convertDocxToHtml,
} from "@nanocollective/get-md";

const md = convertDocxToMarkdown(buffer, { /* options */ });
const html = convertDocxToHtml(buffer);
```

Supported structure: headings, bold/italic/underline/strikethrough, tables, and ordered/unordered lists. List type is resolved from `word/numbering.xml`, not guessed from `numId` parity, which previously caused ordered lists to flip to unordered at random. Nested tables no longer corrupt the outer table (the traversal now uses direct children). Decompression is capped at 100 MB, and corrupt, encrypted, or `document.xml`-less archives raise clear errors. The extractor is powered by `node-stream-zip`.

## Markdown input

`.md` and `.markdown` files (or `inputType: "markdown"`, or a `ContentSource` with `type: "markdown"`) skip HTML parsing entirely and run only the optimization passes: metadata, frontmatter, and structure normalization.

Existing frontmatter is preserved: your `title` and `author` are kept, and only the computed `wordCount` and `readingTime` are appended. Earlier code could produce a doubled frontmatter block or clobber the real title when a `.md` file already had YAML at the top. That path is fixed. The `--no-links`, `--no-images`, and `--no-tables` filters are honored on Markdown input as well.

## Bug fixes from the launch review

The multi-format surface got a top-to-bottom pass before this release shipped. Highlights:

- **PDF no longer loses body text.** Readability was running on PDF-derived HTML and could strip content it scored as boilerplate. It is now disabled for PDF input, matching the DOCX behaviour.
- **PDF page-marker noise removed.** The `-- N of M --` separators no longer leak into the output.
- **PDF metadata and structure.** Title, author, and date flow into the frontmatter. Extracted text is reconstructed into headings, paragraphs, and lists instead of one flat blob.
- **DOCX list types are correct.** Ordered vs. unordered comes from `word/numbering.xml`, not from a `numId`-parity guess.
- **DOCX tables.** Nested tables no longer corrupt the outer table. Decompression is bounded and archive errors are clear.
- **DOCX buffers via `convertToMarkdown`.** A DOCX `Buffer` now converts through `convertToMarkdown` (via PK/zip detection), matching the PDF buffer path instead of throwing.
- **Markdown input.** A `.md` file that already had frontmatter no longer produces a doubled block or clobbers the real title. `--no-links`, `--no-images`, and `--no-tables` are honored for Markdown input.
- **Build before test.** `scripts/test.sh` and the badges workflow now build first, since the CLI end-to-end tests spawn the compiled `bin/get-md.js` (stale `dist/` would skew results).

## CLI

The CLI advertises all four formats and detects the input type from the extension, or from the `%PDF` magic bytes on stdin:

```bash
getmd handbook.pdf -o handbook.md
getmd contract.docx -o contract.md
getmd notes.md -o cleaned.md
getmd https://example.com/article -o article.md
```

## Documentation

The Conversion API page covers PDF and DOCX buffers, binary auto-detection, `inputType`, the `convertDocx*` exports, and Markdown input. The CLI reference documents format detection and the DOCX/`.md` input paths. Getting Started and Quick Start show PDF, DOCX, and Markdown examples alongside the HTML path.

## Tests

592 passing (up from 528 at 1.5.0). New coverage for PDF extraction, page-marker stripping, info-dict metadata, and structure reconstruction; DOCX buffer routing, `numbering.xml` list resolution, and corrupt-archive errors; Markdown-input frontmatter preservation and content filtering; and real DOCX and PDF CLI end-to-end runs.

## Upgrading

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

Or:

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

Node.js 22 or later is required. No peer dependencies are required for the standard HTML/PDF/DOCX/Markdown paths.

If you hit any issues or want to discuss the new format support, open an issue or find us on [Discord](https://discord.gg/ktPDV6rekE).

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

get-md v1.6.0: PDF, DOCX, and Markdown ingestion alongside HTML


get-md v1.6.0 ships today. The library is no longer HTML-only: PDF, DOCX, and Markdown inputs join HTML and URLs, with auto-detection on the file extension or magic bytes (`%PDF` for PDF, the ZIP/`PK` signature for DOCX).

What's actually in the release:

- PDF ingestion via `convertToMarkdown` or the CLI. Text is reconstructed into real structure: paragraphs, headings, lists, with running headers and the `-- N of M --` page markers stripped. Title, author, and creation date flow into the frontmatter from the PDF info dictionary. Scanned PDFs return an empty result with a non-zero `inputLength`, which is the signal that OCR is needed rather than a successful extraction.

- DOCX ingestion, plus two new exports (`convertDocxToMarkdown`, `convertDocxToHtml`) for callers who want the DOCX path without going through the unified entry point. List type is resolved from `word/numbering.xml` rather than guessed, and nested tables no longer corrupt the outer table.

- Markdown input. A `.md` file with existing frontmatter is no longer doubled or has its real title clobbered. The optimization passes run without re-parsing the body as HTML.

- A top-to-bottom pass over the new multi-format surface closed a set of real bugs that surfaced during review: PDF body text no longer dropped by Readability, DOCX list ordering no longer flips at random, DOCX buffers now route through `convertToMarkdown` instead of throwing, and the test scripts now build before running.

592 tests passing, up from 528 at v1.5.0.

Install:

```
npm install @nanocollective/get-md@1.6.0
```

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

Repo: https://github.com/Nano-Collective/get-md
Docs: https://docs.nanocollective.org/get-md/docs


We've just shipped get-md v1.6.0, and the headline change is that get-md is no longer HTML-only. PDF, DOCX, and Markdown inputs now join HTML strings and URLs, with format auto-detection on the file extension or the magic bytes (`%PDF` for PDF, the ZIP/`PK` signature for DOCX).

Here's what's actually in the release.

## PDF, DOCX, and Markdown inputs

`convertToMarkdown` now accepts a `Buffer` or a `ContentSource` and routes it to the right extractor automatically. The CLI does the same: pass a `.pdf`, `.docx`, or `.md` file and it figures out the format from the extension. For stdin, it inspects the `%PDF` magic bytes directly.

On the PDF side, text is reconstructed into real structure rather than one flat blob. Wrapped lines reflow into paragraphs, ALL-CAPS lines become headings, and bulleted or numbered lines become lists (with wrapped continuations folded in). Repeated running headers and footers are dropped. Title, author, and creation date flow into the frontmatter from the PDF info dictionary. The `-- N of M --` page markers that `pdf-parse` emits by default are stripped. Readability is disabled for PDF input so body text is never silently dropped as boilerplate. Scanned or text-less PDFs return an empty result with a non-zero `inputLength`, which is the signal that OCR is needed rather than a successful extraction.

On the DOCX side, list type (ordered vs. unordered) is now resolved from `word/numbering.xml` rather than guessed from `numId` parity. That guess was the source of a class of bug where ordered lists would flip to unordered at random. Nested tables no longer corrupt the outer table (we use direct-children traversal now). Decompression is capped at 100 MB, and corrupt, encrypted, or `document.xml`-less archives raise clear errors. Two new exports are available for callers who want the DOCX path directly: `convertDocxToMarkdown(buffer, options)` and `convertDocxToHtml(buffer)`.

On the Markdown input side, `.md` and `.markdown` files (or `inputType: "markdown"`) skip HTML parsing entirely and run only the optimization passes: metadata, frontmatter, and structure normalization. A subtle bug here was that an existing YAML frontmatter block on a `.md` file could get doubled, or its real `title` could get clobbered by the computed frontmatter. That's fixed; existing `title` and `author` are preserved, and only `wordCount` and `readingTime` are appended. The `--no-links`, `--no-images`, and `--no-tables` filters are honored on Markdown input as well.

## Bug fixes from the launch review

The multi-format surface got a top-to-bottom pass before this release shipped. We closed a real set of bugs that surfaced during review:

- PDF no longer loses body text (Readability was running on PDF-derived HTML and could drop content it scored as boilerplate; it's now disabled for PDF input, matching DOCX).
- PDF page-marker noise is removed (`-- N of M --` separators no longer leak into the output).
- PDF metadata and structure (title/author/date flow into the frontmatter, and extracted text is reconstructed into headings/paragraphs/lists instead of one flat blob).
- DOCX list types are correct (resolved from `word/numbering.xml` instead of a `numId`-parity guess).
- DOCX tables (nested tables no longer corrupt the outer table; decompression is bounded and archive errors are clear).
- DOCX buffers via `convertToMarkdown` (a DOCX `Buffer` now converts through `convertToMarkdown` via PK/zip detection, matching the PDF buffer path instead of throwing).
- Markdown input (a `.md` file that already had frontmatter no longer produces a doubled block or clobbers the real title; `--no-links`/`--no-images`/`--no-tables` are honored for Markdown input).
- Build before test (`scripts/test.sh` and the badges workflow now build first, since the CLI end-to-end tests spawn the compiled `bin/get-md.js`).

## Tests and docs

592 tests passing, up from 528 at v1.5.0. New coverage covers PDF extraction, page-marker stripping, info-dict metadata, and structure reconstruction; DOCX buffer routing, `numbering.xml` list resolution, and corrupt-archive errors; Markdown-input frontmatter preservation and content filtering; and real DOCX and PDF CLI end-to-end runs.

The Conversion API page now covers PDF and DOCX buffers, binary auto-detection, `inputType`, the `convertDocx*` exports, and Markdown input. The CLI reference documents format detection and the DOCX and `.md` input paths. Getting Started and Quick Start show PDF, DOCX, and Markdown examples alongside the HTML path.

## Install

```
npm install @nanocollective/get-md@1.6.0
```

Node.js 22 or later is required. No peer dependencies are required for the standard HTML, PDF, DOCX, or Markdown paths.

If you've been holding off on get-md because of the HTML-only surface, this is the release to revisit. And if you've been hitting one of the bugs above on a pre-release branch, this should clear it.

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


get-md v1.6.0 is out. PDF, DOCX, and Markdown inputs join HTML and URLs, with auto-detection from file extension or magic bytes. Plus a launch-hardening pass over the whole multi-format surface.

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

#OpenSource #Markdown


Your agent's tool outputs become its next prompt. `ls`, `git log`, `cat`, `grep` all flow back into the model, full of usernames, paths, and URLs - and most scrubbers only watch the user side. prompt-scrub scrubs every message regardless of origin.


Donations should have nowhere to hide. At the Nano Collective the charter names the only two destinations for every dollar before you give it: the cost of running the collective, or the community fund that pays OSS contributors. That is the whole model.


100ms or 5-10 seconds. get-md does both: Turndown for batch, CI, and real-time; the local ReaderLM-v2 path when the page's structure matters more than the speed. You pick, per call.



A schema change without a migration is a follow-up no one gets to. json-up puts version, schema, and up() in the same PR, so the change ships complete or it doesn't ship.



20+ named adapters, plus anything OpenAI-compatible. The Nanocoder provider list (Ollama, llama.cpp, MLX, Claude, Copilot, OpenRouter) is less a checklist and more a switching surface. The agent you write today runs against whichever backend you point it at tomorrow.



A regex can't tell you if a haiku scans. Nanotune's LLM judge scores open-ended answers against criteria you pick - helpful, accurate, concise, or your own - and shows reasoning per criterion, not just a yes/no. Cloud or local Ollama. Vibe-based evals stop passing.


A VPN doesn't redact the email in your prompt. Privacy at the wire and privacy at the content are different products. prompt-scrub is the second one. It scrubs what the model actually reads, not the route it travels.



Sponsor money at the Nano Collective pays for infra and a ring-fenced community fund for OSS bounties. That is the whole list. No roadmap say, no contributor targeting, no exclusivity, no slot caps. Same words in the charter and on the sponsor page.



Display-rendering a page and feeding it to an LLM are not the same job. Same source, different output. Pretending they are is why so much crawled content enters prompts broken.

`get-md` ships them as two artifacts.



Your JSON already has a version field and the convention is wrong. Rename it and every reader breaks. json-up lets you pass `key: 'version'` (or anything else) to migrate over it as-is, so the schema catches up without a breaking rename.


A risky refactor with an agent feels like a hostage negotiation: commit nothing, hope for the best. /checkpoint create first, let the AI try it twice, /checkpoint load the better one. Files and history roll back together.


A 0.5B to 1.5B fine-tune is useless if it can't leave your laptop. nanotune export fuses your LoRA into the base and writes GGUF down to q4_k_s, so you drop the same file into llama.cpp, Ollama, or LM Studio without rebuilding anything.

Nanocoder as an ACP agent - driving it from Zed


The headline of v1.28.0 lists "ACP for Zed" alongside a tool-surface consolidation and a session-resume fix. The first item deserves its own write-up, because what actually shipped is a different agent: same Nanocoder, same tool definitions, same provider plumbing, but a headless core speaking JSON-RPC instead of an Ink terminal UI. This post walks through what changes when the editor becomes the UI, what gets rendered there, how the protocol mapping works, and how ACP differs from the WebSocket-based VS Code integration that has been around since the extension shipped.

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

## The shortest possible description

There is a new flag:

```bash
nanocoder --acp
```

When launched with `--acp`, Nanocoder does not draw anything. It reads JSON-RPC from stdin and writes JSON-RPC to stdout. The editor spawns the process, owns the lifecycle, and renders everything - conversation text, tool cards, permission prompts, `ask_user` options, session modes, model selectors - using its own UI. The Ink terminal UI is replaced wholesale by the editor's agent panel.

That is the whole shape. The interesting part is what got built to make it work.

## The module: `source/acp/`

The ACP support lives in a new top-level module rather than being threaded through the existing UI code, which keeps the conversation loop and the Ink renderer independent of the JSON-RPC layer. As of v1.28.0 the module contains:

- `acp-server.ts` - the `@agentclientprotocol/sdk` server wiring, lifecycle, and stdio transport.
- `acp-agent.ts` - the top-level `Agent` implementation that the SDK calls back into.
- `acp-session.ts` - session lifecycle: creation, restoration, the in-memory history map keyed by `sessionId`.
- `acp-conversation.ts` - the conversation loop, streaming, tool-call emission, and the `FINAL_TURN_INSTRUCTION` that nudges the model to wrap up rather than loop.
- `acp-tool-call.ts` - maps internal tool definitions to the ACP `ToolCall` / `ToolCallUpdate` shape, including the `ToolKind` mapping, follow-along `location` data, and the before/after diff for edits.
- `acp-content.ts` - converts Nanocoder message blocks (markdown, resource links, embedded resources, fenced code) to and from the ACP content block types.
- `acp-permission.ts` - maps tool approval requirements to ACP permission options, respecting the current development mode.
- `acp-question.ts` - normalises `ask_user` option shapes (string vs `{label, value}` objects) into strings the editor can render as buttons.
- `acp-capabilities.ts` - what we tell the client we support: `loadSession`, `sessionCapabilities.close`, plus the fixed list of session mode ids and protocol-version negotiation.
- `acp-types.ts` - module-local type aliases.

Specs sit next to each file (`*.spec.ts`). The total module is around 3.4k lines including tests.

## JSON-RPC replaces the terminal

In the Ink CLI, conversation state is held inside the React/Ink renderer: a `MessageList` keeps the visible history, a `UserInput` owns the input box, a `ToolExecutionCard` renders each in-flight tool call, and the mode/ctx/tune indicators live on a status line. None of that runs over ACP. The renderer is simply not loaded.

What does run is the same conversation loop the CLI uses, but it emits to an `AcpAgent` adapter instead of to Ink. The adapter translates three things:

1. **Streaming text chunks** into ACP `session/update` notifications with `agentMessageChunk` content blocks.
2. **Tool calls** into `toolCall` notifications carrying a `kind` (read, edit, delete, move, search, execute, think, fetch, etc.), the touched file paths as `locations`, and for edits a `diff` payload with `oldText` and `newText`.
3. **Approvals and questions** into `requestPermission` / `ask_user` calls that block on the editor's response.

The benefit is concrete: the editor gets to render the agent inside its own UI primitives. Zed, for example, draws the streaming text inside its agent panel, attaches a `diff` viewer to each edit tool call, and pops its own allow/deny dialog for permission requests. The Ink equivalent of "a tool card with a diff viewer inside it" is something we would have to design and maintain ourselves; ACP gets it for free as long as the tool call carries a `diff` block.

## What gets rendered in the editor

The current list of affordances that work over ACP, taken from the ACP feature doc and the source:

- **Streaming responses**, including reasoning / thinking content, drawn inline in the agent panel.
- **Tool calls as rich cards.** File tools report their `kind` (e.g. `edit`, `read`, `execute`) and the file paths they touch as `locations`, so the editor can render a "follow-along" cursor alongside the conversation. `string_replace` and `write_file` additionally attach a `diff` block (`oldText`, `newText`) so the editor can show a before/after view in the card itself.
- **Permission prompts**, surfaced as the editor's own allow/deny dialog. The decision is fed back into the same approval pipeline the CLI uses; nothing in the conversation loop has to know it is being driven by ACP rather than Ink.
- **Development modes** - `normal`, `auto-accept`, `yolo`, `plan` - exposed as ACP session modes. Selecting one in the editor is equivalent to pressing Shift+Tab in the CLI. Sessions start in `auto-accept` by default.
- **Model display and switching.** The editor shows the current model and lets you switch between the models configured for your active provider. Pinning a model per editor session is also possible via `args` in `settings.json` (see below).
- **`ask_user`.** When the agent asks a clarifying question, the options appear as selectable buttons in the editor. The model receives whichever option the user picks. Selection only - there is no free-form typed answer over ACP, which is a protocol-level constraint.
- **`@`-mentioned files.** Files referenced through the editor's file-mention UI are sent as resource links and included in the prompt. The editor's live buffer is used when available, so unsaved edits are picked up.
- **Session reload.** Reopening a thread is supported, so the editor does not error when restoring a session on startup.

## What does not work over ACP (yet)

The feature doc lists three honest limitations:

- **Session history is in-memory.** Within a single running agent process, reopening a thread restores its history. After the editor and the agent process fully restart, a reloaded thread starts empty. It is usable, but prior messages are not replayed. This is a deliberate scope cut: the CLI's session-resume work in v1.28.0 replays into the Ink chat view via a `session-history-renderer`, but ACP does not yet replay through the protocol. The internal `acp-session.ts` keeps a `Map<sessionId, history>`, which is the seam where replay would attach.
- **`ask_user` is selection-only.** ACP permission options have no text input. The model receives the picked option rather than a typed answer. For most clarifying questions this is fine; for anything that needs free-form prose the workaround is to phrase the question so the options cover the meaningful choices.
- **Images and audio are not processed.** Non-text attachments are noted to the model but not interpreted. This is true of the CLI too right now; the ACP layer does not paper over it.

There is also a fourth, unspoken one worth knowing about: the editor spawns the agent in its current working directory, so project-level config (`agents.config.json`) and relative paths resolve against the open folder. That is usually what you want. If you open a folder without a configured provider, the agent exits with "No provider configured" and the editor surfaces the error.

## Tool kinds and follow-along locations

The `ToolKind` mapping in `acp-tool-call.ts` is worth a quick look, because it is what lets the editor draw the right kind of tool card:

```ts
const TOOL_KINDS: Record<string, ToolKind> = {
  read_file: 'read',
  write_file: 'edit',
  string_replace: 'edit',
  delete_file: 'delete',
  file_op: 'move',
  find_files: 'search',
  search_file_contents: 'search',
  list_directory: 'read',
  execute_bash: 'execute',
  ...
};
```

For file tools, the converter also extracts `locations` so the editor can render a "follow-along" line: open `src/auth/session.ts`, then `src/auth/session.ts:42`, then back. That is the same data the Ink CLI uses to draw path hints, just delivered in a structured field the editor can act on.

The diff builder is the more interesting bit. For `string_replace`, the converter reads the file off disk, applies the proposed `old_str` / `new_str` in memory, and emits:

```ts
{type: 'diff', path: absPath, oldText, newText}
```

For `write_file` it diffs the existing contents (if any) against the new contents. The editor then renders the diff in the tool card and lets the user step through it before the tool executes - which is to say, permission is reviewed with the proposed change already visible, not after.

A subtle detail: the diff builder only synthesises a whole-file diff for `string_replace` when the replacement is unambiguous. If the same `old_str` matches multiple regions, it skips the synthetic diff rather than guessing. The model gets a normal approval request and the editor gets the raw before/after from the tool args; this avoids the worst failure mode where a "diff" disagrees with what the code actually does.

## Session modes

`acp-capabilities.ts` exposes the four development modes as ACP session modes:

```ts
const ACP_MODES: SessionModeId[] = ['normal', 'auto-accept', 'yolo', 'plan'];
const MODE_MAP: Record<SessionModeId, DevelopmentMode> = {
  normal: 'normal',
  'auto-accept': 'auto-accept',
  yolo: 'yolo',
  plan: 'plan',
};
```

The mapping is identity today, which is the point. The ACP session mode is just a label the editor flips; the approval pipeline that interprets it is the same one Shift+Tab flips in the CLI. A mid-session change in the editor updates the in-memory development mode and the next approval request goes through the new policy - no special case for ACP.

`plan` is the most useful one to know about here, because the editor integration is where it really starts to earn its keep: switch to plan mode, ask the model to investigate a refactor, get a structured plan back, switch to `normal` and ask it to execute, all without leaving the editor. Conversation history carries across the switch because it is just a mode flip on the existing session.

## Capability negotiation

A short but important detail in `acp-capabilities.ts`:

```ts
export function negotiateProtocolVersion(clientRequested: ProtocolVersion): ProtocolVersion {
  // Clamp the client's requested version down to ours. Never claim support
  // for a newer protocol than this SDK implements.
}
```

The SDK exposes the protocol version; we declare a fixed one. If the editor asks for a newer protocol than we implement, we respond with ours rather than failing the handshake. This avoids the failure mode where a forward-compatible editor feature silently breaks because of a minor version mismatch. `loadSession: true` is the other capability we advertise, alongside `sessionCapabilities.close` - that is, we can reload a session by id, and we support the close handshake.

## Setup in Zed

Zed is the reference ACP client for this release. Two lines in `settings.json` (Cmd+, on macOS, or `zed: open settings` from the command palette):

```json
{
  "agent_servers": {
    "Nanocoder": {
      "command": "nanocoder",
      "args": ["--acp"]
    }
  }
}
```

To pin a specific provider or model for the editor session:

```json
{
  "agent_servers": {
    "Nanocoder": {
      "command": "nanocoder",
      "args": ["--acp", "--provider", "ollama", "--model", "qwen2.5-coder:7b"]
    }
  }
}
```

Otherwise Nanocoder resolves the provider and model the same way the CLI does - from the project's `agents.config.json`, falling back to the global config. The agent is spawned in the editor's current working directory, so project-level config and relative paths resolve against the open folder.

One practical snag worth knowing about: if Zed was launched from the desktop rather than a terminal, it may not see your shell's `PATH`. The fix is to point `command` at an absolute path to the binary (or to the Node runtime plus the script), or to launch Zed from a shell so it inherits `PATH`. This is not an ACP issue; it is just how macOS app launches work.

## ACP vs. the VS Code extension

Both connect Nanocoder to an editor, and both predate v1.28.0 in some form, but they are different mechanisms. The shape of the difference matters for picking which one to use:

| | Transport | Flag | Editor role |
| --- | --- | --- | --- |
| ACP | JSON-RPC over stdin/stdout | `--acp` | Editor is the UI |
| VS Code extension | WebSocket on port 51820 | `--vscode` | Editor adds previews on top of the CLI UI |

With ACP, the **editor is the UI.** The agent runs headless, and the editor renders the conversation, tool cards, diffs, and approval prompts using its own primitives. The Ink terminal UI is not loaded. The agent does not have its own window to draw in.

With the VS Code extension, the **CLI UI stays in charge.** You still run `nanocoder --vscode` in a terminal; the extension connects over a local WebSocket on port 51820 and adds two things on top: live diff previews for proposed file changes, and active-editor context (the focused file and any selection, pushed to the CLI continuously and rendered as a `⊡ In App.tsx` pill on the input status line).

That difference shows up in three places that matter in practice:

1. **Where you launch the agent.** With ACP, the editor spawns it. With VS Code, you launch it from a terminal or from VS Code's command palette (`Nanocoder: Start Nanocoder CLI`), and the extension connects to the running process.
2. **Where conversation history lives.** With ACP, the agent is bound to the editor's session lifecycle. With VS Code, it lives in the CLI process; the extension is purely additive.
3. **What "the UI" is.** With ACP, the editor's agent panel is the only UI. With VS Code, the terminal UI is the UI; the extension adds diff previews and editor context, but the conversation text, mode indicator, and input box are still the Ink CLI's.

Practically: if your editor supports ACP, that is the cleaner integration today, because the conversation loop is rendering in one place and the editor owns it. The VS Code extension remains the right choice for editors that do not yet speak ACP, and it picks up one nice feature from the v1.28.0 tool consolidation: the `⊡ In <file>` status-line pill now points at the slimmed-down file tools and reads more cleanly because there are fewer of them.

## What is still rough

A few things worth being honest about:

- **Session resume over ACP is not implemented.** The CLI replay landed in v1.28.0 via `session-history-renderer`; the ACP path has the data in `acp-session.ts` but does not push it back through the protocol on `loadSession`. Reopening a thread within a single running agent works; reopening across an editor restart starts empty.
- **`ask_user` has no text input.** Selection only. For most clarifying questions this is fine; for any question that genuinely needs prose it is a constraint.
- **No image / audio attachments.** The model is told they were mentioned but cannot see them. The CLI is the same way.
- **Long edits can produce large diffs.** The diff is sent inline in the tool-call notification; very large files mean very large protocol messages. There is no streaming diff yet.
- **ACP protocol version is fixed.** We clamp to our version rather than negotiating upward. A forward-compatible editor will work; a feature-gated one that requires a newer version than we expose will silently fall back to the subset we support.

None of these block day-to-day use. They are the places where the integration gets noticeably less polished if you happen to hit them.

## Why this matters

The headline framing of v1.28.0 is "ACP for Zed." The more interesting framing is that Nanocoder now has a second front-end. The conversation loop, tool definitions, provider plumbing, session management, and development modes are all unchanged - the ACP adapter is one more consumer of the same internal APIs the Ink CLI uses. Adding another editor that speaks ACP (there are several in flight upstream of the protocol) is now a matter of writing the JSON-RPC transport, not porting the UI. That is the structural payoff, and it is the reason the module is structured as it is.

If you try it and something is broken or surprising, please open an issue. The [Nanocoder repo](https://github.com/Nano-Collective/nanocoder) is the right place, and the ACP-specific docs under `docs/features/acp.md` track the current state of what is and is not supported.

Nanocoder as an ACP agent: driving it from Zed


The v1.28.0 release of Nanocoder adds something we have been wanting for a while: an Agent Client Protocol server that lets editors like Zed drive Nanocoder natively, with the editor as the UI rather than a terminal panel.

When you launch `nanocoder --acp`, the agent runs headless and speaks JSON-RPC over stdin/stdout. The editor becomes responsible for everything you used to see in the terminal: streaming text, tool cards with kind and location metadata, before/after diffs for `string_replace` and `write_file`, permission prompts, the four development modes (normal, auto-accept, yolo, plan), model display and switching, and `ask_user` buttons. The Ink terminal UI is simply not loaded.

The new module lives at `source/acp/`. It splits into the parts that have to be separate to keep the conversation loop renderer-agnostic: the SDK server wiring (`acp-server`), the agent implementation (`acp-agent`), session lifecycle (`acp-session`), the conversation loop and streaming (`acp-conversation`), tool-call mapping with `ToolKind` and diff synthesis (`acp-tool-call`), content block conversion (`acp-content`), permission mapping (`acp-permission`), and `ask_user` option normalisation (`acp-question`). Capability negotiation clamps to our protocol version rather than failing the handshake when an editor asks for newer.

Zed is the reference client. Registration is two lines in `settings.json`:

```json
{
  "agent_servers": {
    "Nanocoder": {
      "command": "nanocoder",
      "args": ["--acp"]
    }
  }
}
```

How this differs from the VS Code extension: ACP replaces the UI entirely; the VS Code extension adds diff previews and active-editor context on top of the existing CLI UI, which still owns the conversation.

Repo, ACP module, and docs 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.


A walkthrough post on the Agent Client Protocol server we shipped in Nanocoder v1.28.0, what the integration actually does inside the editor, and how it differs from the WebSocket-based VS Code extension.

## What `--acp` actually does

There is a new flag:

```bash
nanocoder --acp
```

When launched with that flag, Nanocoder does not draw anything. The Ink terminal UI is not loaded. The agent reads JSON-RPC from stdin and writes JSON-RPC to stdout. The editor spawns the process, owns the lifecycle, and renders everything using its own UI primitives.

The mapping is structured. Streaming text becomes `session/update` notifications with `agentMessageChunk` content blocks. Tool calls become `toolCall` notifications carrying a `ToolKind` (read, edit, delete, move, search, execute, etc.), the touched file paths as `locations`, and for `string_replace` and `write_file` a `diff` payload with `oldText` / `newText` that the editor can render in the tool card. Permission requests become `requestPermission` calls that block on the editor's allow/deny dialog and feed back into the same approval pipeline the CLI uses.

The four development modes - `normal`, `auto-accept`, `yolo`, `plan` - are exposed as ACP session modes. Sessions start in `auto-accept`. `plan` is where this really earns its keep: ask the model to investigate a refactor in plan mode, get a structured plan back, switch to `normal` and ask it to execute, all without leaving the editor. Conversation history carries across the switch because it is just a mode flip on the existing session.

## The module structure

The ACP support lives at `source/acp/` as a self-contained module rather than being threaded through the Ink renderer. The split:

- `acp-server.ts` - the `@agentclientprotocol/sdk` server wiring and stdio transport.
- `acp-agent.ts` - the `Agent` implementation the SDK calls back into.
- `acp-session.ts` - session lifecycle and the in-memory `Map<sessionId, history>`.
- `acp-conversation.ts` - the conversation loop, streaming, tool-call emission.
- `acp-tool-call.ts` - tool name to `ToolKind`, location extraction, and the diff synthesis for edits.
- `acp-content.ts` - message block conversion (markdown, resource links, embedded resources, fenced code).
- `acp-permission.ts` - maps tool approval requirements to ACP permission options.
- `acp-question.ts` - normalises `ask_user` options (string vs `{label, value}` objects) into renderable strings.
- `acp-capabilities.ts` - `loadSession: true`, `sessionCapabilities.close`, the fixed session mode list, and protocol version negotiation that clamps to our version.

The whole module is around 3.4k lines including tests. The conversation loop and tool definitions are unchanged from the CLI; the ACP adapter is one more consumer of the same internal APIs.

## What is rough

Three honest limitations:

- **Session history is in-memory across an editor restart.** Within a single running agent process, reopening a thread restores its history. After the editor and the agent process fully restart, a reloaded thread starts empty. The CLI's session resume in v1.28.0 uses a `session-history-renderer` to replay into Ink; ACP does not yet replay through the protocol on `loadSession`.
- **`ask_user` is selection-only.** ACP permission options have no text input. The model gets the picked option rather than a typed answer.
- **No image / audio attachments.** Non-text mentions are noted but not interpreted. The CLI is the same way.

## ACP vs. the VS Code extension

Both connect Nanocoder to an editor. They are different mechanisms:

| | Transport | Flag | Editor role |
| --- | --- | --- | --- |
| ACP | JSON-RPC over stdin/stdout | `--acp` | Editor is the UI |
| VS Code extension | WebSocket on port 51820 | `--vscode` | Editor adds previews on top of the CLI UI |

With ACP the **editor is the UI.** The agent runs headless and the editor renders conversation, tool cards, diffs, and approvals using its own primitives.

With the VS Code extension the **CLI UI stays in charge.** You still run `nanocoder --vscode` in a terminal; the extension connects over a local WebSocket and adds two things on top: live diff previews for proposed file changes, and active-editor context (focused file and selection, pushed to the CLI continuously and rendered as a `⊡ In App.tsx` pill).

Three places that difference shows up:

1. **Where you launch the agent.** ACP: the editor spawns it. VS Code: you launch it from a terminal or from VS Code's command palette, and the extension connects.
2. **Where history lives.** ACP: bound to the editor's session lifecycle. VS Code: in the CLI process; the extension is purely additive.
3. **What "the UI" is.** ACP: the editor's agent panel. VS Code: the terminal UI, with the extension adding diff previews and editor context on top.

If your editor supports ACP, that is the cleaner integration today. The VS Code extension remains the right choice for editors that do not yet speak ACP.

## Setup in Zed

Two lines in `settings.json`:

```json
{
  "agent_servers": {
    "Nanocoder": {
      "command": "nanocoder",
      "args": ["--acp"]
    }
  }
}
```

Pinning a provider and model is also possible via `args`:

```json
{
  "agent_servers": {
    "Nanocoder": {
      "command": "nanocoder",
      "args": ["--acp", "--provider", "ollama", "--model", "qwen2.5-coder:7b"]
    }
  }
}
```

One practical snag: if Zed was launched from the desktop rather than a terminal, it may not see your shell's `PATH`. Use an absolute path in `command`, or launch Zed from a shell. Standard macOS app launch behaviour, not an ACP thing.

Full setup notes and limitations in the ACP docs at https://github.com/Nano-Collective/nanocoder. If you try it and something is broken or surprising, please open an issue.


Nanocoder v1.28.0 ships an Agent Client Protocol server: `nanocoder --acp` runs headless, the editor becomes the UI (streaming, tool cards, before/after diffs, permissions, session modes, ask_user). https://github.com/Nano-Collective/nanocoder


Closing a PR at 1am and wondering if any of it will ever be paid for is a quiet kind of resentment.

The Nano Collective has a defined answer: scoped bounties, designated donations agreed before money moves, bespoke partnerships. All transparent on the Open Collective ledger.


Point get-md at a sitemap.xml and walk away. It fans out across every URL with bounded concurrency, reports per-page failures inline, and lands a folder of clean markdown before your coffee gets cold. One command, in place of the bash for-loop no one wants to maintain.



Most of your JSON lives between versions, not at them. Migration tools don't validate, validators don't migrate. json-up treats them as one thing: each migration step carries its own Zod schema, so the shape that comes out is the shape you asked for, not the shape you hoped for.


Extensions that don't know each other aren't much of a system. Commands, subagents, tools, and event subscriptions all sat in separate folders, no shared manifest. Nanocoder's Skills bundle folds them into one .nanocoder/skills/ folder, so siblings see each other.



You can't string-match your way to knowing if a fine-tune is any good. We ran an LLM-as-judge in nanotune, on the same local models the rest of the tool uses, so eval stops being an act of faith.



get-md v1.6.0 expands the input surface from HTML+URL to HTML/PDF/DOCX/Markdown with auto-detection, plus a launch-hardening pass over the new multi-format path.

Full write-up: {{link to article on website}}


get-md v1.6.0: HTML/PDF/DOCX/Markdown to Markdown for LLM pipelines


A VPN hides your IP. The model still sees your prompt. prompt-scrub edits the text before it leaves your machine, so the model sees a placeholder where your email was. Different layers. They stack.


One tip for sending prompts to a cloud LLM today: scrub the message locally first, send the scrubbed copy to whatever model you use, then rehydrate the reply from the on-disk session map. Same client, same model, same network path. Three commands and your context stays local.



The Nano Collective's Economics Charter was published before there was anything in the fund. No investors, no equity, no pitch. The terms are on record so contributors decide on facts.


Your HTML-to-MD converter just mangled a nested code block inside a table cell, and your LLM is hallucinating around the wreckage. get-md's Turndown path is tuned for LLM input, with an optional local ReaderLM-v2 pass for the structures a regex can't reach.


The worst kind of migration is the one that runs clean and leaves your data wrong. json-up checks the output of every up() against a Zod schema, so the failure you wanted is the failure you get, and it's loud.



# prompt-scrub v1.0.0: a local-first scrubber for prompts and their responses

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

This is the first public release of `prompt-scrub`, a small Node.js utility that runs entirely on your machine. It detects identifying content inside a prompt (emails, paths, secrets, phone numbers, URLs, postal addresses, and a couple of opt-in categories), replaces each finding with a stable placeholder like `Email_1` or `Path_2`, and lets you rehydrate the model's response back to the original values locally after it comes back.

The motivation is simple: most accidental identifier leakage to a cloud LLM lives in the text of the prompt and the text of its response. Stripping it there, deterministically, before the prompt leaves your machine is a useful layer in a privacy posture, and one that does not need a network round-trip, a new account, or a hosted service to work.

## What it actually does

The package exposes two functions and a CLI.

`scrub()` takes either a plain string or an array of `{ role, content }` messages, runs the configured detectors over the text, replaces each finding with a category-namespaced placeholder, and returns the scrubbed content plus a session id:

```typescript
import { scrub, rehydrate } from '@nanocollective/prompt-scrub';

const prompt = "My key is sk-12345 and my email is alice@example.com";
const { scrubbedContent, sessionId } = scrub({ content: prompt });
// scrubbedContent: "My key is Secret_1 and my email is Email_1"
```

You send `scrubbedContent` to whatever LLM provider you already use. When the response comes back, `rehydrate()` walks the text, looks up each placeholder in the session map, and swaps them back. Unknown placeholders (placeholder text the model hallucinated, or placeholders from a previous session) are passed through unchanged and surfaced as warnings so you can decide whether to trust them:

```typescript
const response = "Your email Email_1 looks correct and your key Secret_1 is fine.";
const { content, warnings } = rehydrate({ content: response, sessionId });
// content: "Your email alice@example.com looks correct and your key sk-12345 is fine."
```

The session id is the link between the two steps. It points at a small JSON file under your OS config directory that holds the placeholder-to-original mapping. The file is written atomically, with restrictive permissions, and includes a corrupt-file quarantine path so a half-written map does not silently disable rehydration. The location is overridable via the `PROMPT_SCRUB_CONFIG_DIR` environment variable.

## Detectors

Eight detectors ship in the box.

On by default:

- email
- phone
- postal address
- path (Unix-style and Windows-style)
- secret (tuned for common API key and credential shapes, since missing a credential is worse than missing a name)
- url

Off by default, opt-in:

- name (proper-noun detector, with a stricter allowlist mode)
- code-tell (user-enumerated private identifiers, for things like internal project codenames)

URL detection also accepts a trusted-host allowlist with subdomain matching, so internal services you control can pass through without a placeholder if that is what you want. Overlapping detector findings (an email that looks like a URL fragment, say) resolve by a documented priority order, with longer span winning on ties. Determinism is deliberate: the same input and session always produce the same scrubbed output, which keeps provider prompt-cache prefixes byte-stable.

## The CLI

A small command-line wrapper around the same logic. The recommended workflow is `inspect` first, then `scrub`:

```bash
# See exactly what would change without writing anything
echo "My email is alice@example.com" | prompt-scrub inspect

# Scrub stdin (or a file), prints the session id to stderr
echo "My email is alice@example.com" | prompt-scrub scrub

# Rehydrate a response using --session-id
echo "Contact Email_1 for details." | prompt-scrub rehydrate --session-id <id>

# Inspect a session map
prompt-scrub sessions list
prompt-scrub sessions show <id>

# See the active detector set, including any rule-pack additions
prompt-scrub rules list
```

`inspect` is the part we want people to actually use. It does not write a session file and it prints a SHA-256 hash of the scrubbed output so you can verify byte-stable cache prefixes across runs:

```
Detected entities:
  [Email]    alice@example.com                → Email_1    (chars 12-29)

No session written.
Hash: 41beda4af0b83488fdf6eea9347775450a1c7c887a6ef377212340f36c445132
```

## Extensibility

Two extension points:

- Custom detectors can be passed in via the library API (`customDetectors` in `ScrubOptions`). Each one returns matches in the same shape the built-ins do, so they slot into the same priority / span logic.
- Rule packs are separate npm packages that contribute additional detectors. They are declared in your config or in `package.json`, merged into the active set, and visible in `rules list`. This is the path for sharing detectors across projects without forking the package.

## What this is, and what it is not

`prompt-scrub` reduces identity leakage at the content layer. It is partial defence, not anonymity, and the README and the [Threat Model](https://github.com/Nano-Collective/prompt-scrubber/blob/main/docs/features/threat-model.md) are explicit about the distinction because the distinction matters.

It does defend against:

- Accidental secret leakage in prompts. The secret detector is tuned for high precision on the common API key, token, and credential shapes.
- Accidental identifier leakage in one-off prompts. Emails, phone numbers, postal addresses, paths, and URLs are caught with conservative defaults, and the original values stay on disk under the session map.

It partially mitigates:

- Cloud LLM providers reading identifying content. After scrubbing, the prompt contains `Email_1` instead of your address. That is materially less identifying, but not zero, and a determined provider can still correlate across a session if it has access to its own logs.
- Long-term profile building from prompt content. Stable session mappings prevent identifier-level correlation within a single session. They do not address stylistic fingerprinting, the way you phrase things goes out unchanged.
- Tool call results in agentic settings. The scrubber runs on every message regardless of origin, so `ls`, `git log`, `cat`, and `grep` outputs are scrubbed before the next LLM turn. Coverage is limited to the configured detectors.

It does not defend against:

- A compromised local machine. The scrubber runs locally. If your environment is compromised, your prompt is too. The session maps on disk are plaintext JSON in v1, and an attacker with your account can read them. Encryption at rest is a v1.1 follow-up.
- 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.
- Stylistic fingerprinting. The v1 brute-force approach does not rewrite style.
- The network or key layer. Your IP address, request timing, and headers are outside the scrubber's scope. Pair it with a network tool of your own choosing if you need that.

A user who believes this tool makes them anonymous is worse off than one who never used it, because they stop reading their prompts and trust the defaults. Always use `inspect` first. The Threat Model document spells out the full picture in one place.

## Install

```bash
# As a global CLI
npm install -g @nanocollective/prompt-scrub

# As a Node.js dependency
npm install @nanocollective/prompt-scrub
```

The package is open source under the project's licence. Source, full docs, and the Threat Model live at the repo:

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

## Feedback wanted

This is the first public release. The things we would most like to hear about:

- Detector coverage. Which common shapes do you paste in that we are missing? Which opt-in category (name, code-tell) should be on by default for your workflow?
- Rule pack packaging. The extension shape is in, but we have not yet seen real-world rule packs, and the format is open to change while the package is at 0.x.
- The Threat Model. We chose partial-defence framing deliberately. If the documentation is unclear about what is and is not defended, we want to know before we ship more code on top of it.
- The inspect UX. The hash output and the dry-run diff are intended to be the thing people actually use. If they are awkward in practice, that is a fast fix.

Issues and PRs are welcome at the repo. There is also a [Nano Collective Discord](https://discord.gg/ktPDV6rekE) for the wider conversation about what the collective is building and why.


prompt-scrub v1.0.0: a local-first scrubber for prompts and their responses


We just shipped the first public release of `prompt-scrub`, a small Node.js utility from the Nano Collective that does one thing: it strips identifying content out of prompts and messages before they leave your machine, and rehydrates the model's response back to the original values locally.

It is local-first, runs in your own process, and ships with detectors for emails, phone numbers, postal addresses, paths, secrets (API keys, tokens, common credential shapes), and URLs, with name and code-tell detectors available as opt-ins. A small CLI wraps the same logic, with an `inspect` command that shows exactly what would change before you commit to sending anything.

The shape we care about:

- `scrub()` turns `alice@example.com` into `Email_1` and returns a session id.
- `rehydrate()` swaps `Email_1` back to `alice@example.com` once the response comes back, and surfaces unknown placeholders as warnings so you can decide whether to trust them.
- The mapping is deterministic per session, which keeps provider prompt-cache prefixes byte-stable.
- The session map lives in your OS config directory, written atomically with restrictive permissions.

This is partial defence, not anonymity. `prompt-scrub` does not address stylistic fingerprinting, semantically identifying questions, or anything at the network and key layer. We say so explicitly in the Threat Model, because a user who believes the tool makes them anonymous is worse off than one who never used it. Always run `inspect` first.

Install:

```
npm install -g @nanocollective/prompt-scrub
```

Source, full docs, and the Threat Model: https://github.com/Nano-Collective/prompt-scrubber

This is the first public release. We want to hear what detectors are missing, how rule packs should be packaged, and whether the Threat Model is clear enough. Issues and PRs at the repo.



We just shipped the first public release of `prompt-scrub`, and we want to talk about it.

`prompt-scrub` is a small Node.js utility that runs entirely on your machine. You give it a prompt, it detects identifying content (emails, phone numbers, postal addresses, paths, secrets, URLs, with name and code-tell as opt-ins), replaces each finding with a stable placeholder like `Email_1` or `Path_2`, and gives you back the scrubbed text plus a session id. You send the scrubbed text to whichever LLM provider you already use. When the response comes back, you hand it to `rehydrate()` with the session id and the placeholders are swapped back to your real values. That is the whole shape.

We built it because most accidental identifier leakage to a cloud LLM is right there in the text of the prompt. Stripping it locally, deterministically, before the prompt leaves your machine seemed like a useful layer, and one that did not need a hosted service or a new account to work.

A few choices worth flagging:

- It is deterministic per session. The same input and session id produce the same scrubbed output every time, which is what you want if your provider caches prompt prefixes.
- The session map is a small JSON file under your OS config directory, written atomically with restrictive permissions. If the file gets corrupted, it gets quarantined rather than silently disabling rehydration.
- The `inspect` command prints what would change without writing a session file, plus a SHA-256 hash of the scrubbed output so you can verify cache stability across runs.
- Eight detectors ship in the box. Six are on by default; the name and code-tell detectors are opt-in because their false-positive cost is higher.
- Rule packs let you publish additional detectors as separate npm packages.

What it is not:

- Anonymity. 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.
- Style rewriting. The way you phrase things goes out unchanged.
- Network protection. Your IP, request timing, and headers are outside the tool's scope.

We state all of this explicitly in the Threat Model. A user who believes the tool makes them anonymous is worse off than one who never used it, because they stop reading their prompts. Always run `inspect` first.

Install:

```bash
npm install -g @nanocollective/prompt-scrub
```

Source, docs, and the Threat Model: https://github.com/Nano-Collective/prompt-scrubber

This is our first public release at 1.0.0, and the thing we most want feedback on right now is detector coverage (what common shapes do you paste in that we are missing?), rule-pack packaging (the extension shape is in, but we have not yet seen real-world rule packs), and the Threat Model framing. Issues and PRs at the repo.

We hang out in the Nano Collective Discord if you want to talk about any of it: https://discord.gg/ktPDV6rekE


prompt-scrub v1.0.0 ships today: a small local-first scrubber that strips identifying content out of prompts before they reach a cloud LLM, and rehydrates responses back locally. npm install -g @nanocollective/prompt-scrub

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



The worst part of fine-tuning is rarely the training run. It's assembling examples that match a schema, deduping them, catching broken turn alternations before you waste an hour. nanotune's data commands handle the lot against one known schema, so the time goes into what to teach



Before your first PR on a Nano Collective project, read the Economics Charter. It spells out scope-before-money, that nothing is paid retrospectively, and how a bounty actually gets agreed. Ten minutes of reading now is weeks of mismatched expectations avoided later.



Converting your own HTML to Markdown shouldn't need a cloud account. get-md's local LLM path runs ReaderLM-v2 on-device via node-llama-cpp. No API key, no round-trip, no quota. The principle: tools that touch your files should run on your hardware.


Parsing error messages in a catch block is a smell. json-up throws 3 named errors - ValidationError, MigrationError, VersionError - so you branch on the type, not the string.



Your coding agent's scheduler should live on your machine, not someone else's cloud.

Nanocoder ships a per-project daemon that fires commands on file changes and cron, with no TUI open and no remote worker involved.


A VPN, Tor, or a proxy hides the route. None rewrite email, path, or API key in the prompt.

prompt-scrub fixes the leak at the content layer: identifiers become placeholders before they leave the machine, then rehydrate locally. Compose it with any network tool you trust.



A fine-tuned model you can actually run at home: `nanotune train`, then `nanotune export` fuses the LoRA into the base and writes GGUF directly. Drop the file in Ollama, no cloud, no PyTorch, no llama.cpp build. The laptop does the whole loop.


The default deal with sponsors is quiet influence. Bigger cheque, softer feedback, roadmap drifts toward the money.

At the Nano Collective, sponsors fund the work and do not direct it. Written on the sponsor page, same on every surface, enforced as a hard rule.


The reflex is to throw an LLM at HTML-to-Markdown. get-md ships Turndown + Mozilla Readability as the fast path instead, sub-100ms per page, deterministic, zero API spend. An LLM mode is there for when the structure actually needs it.


The reflex for JSON versioning is a schema table in the database next to the rows. json-up puts `_version` on the data itself and treats unversioned input as v0. The migration ships with the file, no schema table, no coupling, works the same on disk, in a blob, in a local store.



Picking up a new editor shouldn't mean rebuilding your agent integration from scratch. Nanocoder speaks ACP, so it slots into Zed as a native agent with a single settings.json entry - no per-editor extension, no rewrite.



Eight detectors, one priority chain, and the order is the point.

prompt-scrub puts SecretDetector first because missing a credential is worse than missing a name. Then Email, URL, Path, Phone, Address, Name, CodeTell. Overlapping spans resolve by priority, not detector race.


"Write a haiku about coding" breaks string-match benchmarks. Default modes like contains or startsWith score CLI answers fine, fail on open-ended output. Nanotune ships an LLM-as-a-judge for those: configurable criteria, 0-10 scores, reasoning per criterion.


Before you write a whitepaper, raise the idea. Discord, the docs repo, or the organisation repo: any of the three. Most answers are yes, and the rest save you a month of writing for an idea that was never going to fly.



DOM parsers assume a browser. JSDOM assumes Node. Mobile apps get a fork.

get-md ships against happy-dom-without-node instead, so the same convertToMarkdown() runs in Node, in a React Native app, and in the browser. One call, three runtimes, no platform branch.


Two functions and a builder, that's the whole sync API in json-up. createMigrations().add().add().build() and migrate({state, migrations}). The surface is small because the problem is small.


Four extension systems is three too many.

Nanocoder collapses commands, subagents, tools, and event triggers into one primitive: a Skill. One .md file, or one bundle under .nanocoder/skills/, same surface either way.



1 byte off, and the cache misses. prompt-scrub's scrub() is byte-stable per session, so placeholder order stays fixed and prompt caches stay hot. inspect --hash prints the SHA-256 so you can check.


Tune, auto-detected - how the new tool profiles pick themselves


The headline of v1.28.0 mentions that the tool surface was consolidated from 33 to 19 and that an automatic tune profile is now the default. Both halves of that sentence deserve a closer look, because the interesting design work is not in the count, it is in how a single config flag (`toolProfile: 'auto'`) decides at runtime which tools a given model sees, which prompt sections it gets, and how the answer changes the moment you switch models. This post walks through the mechanics: the consolidation itself, the parameter-count heuristic, the 5-layer config hierarchy that resolves `tune`, the interaction with development modes, and what local-model workflows gain from a profile that re-resolves live on model switch.

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

## The shortest possible description

Three concrete tool profiles exist (`full`, `minimal`, `nano`) plus one meta-profile (`auto`) that picks between them from the active model id. The default is `auto`, so most users never set anything. The work in v1.28.0 was the consolidation that let the default be sensible, plus the live re-resolution that makes the default honest.

```ts
// source/tools/tool-profiles.ts
type ConcreteProfile = Exclude<ToolProfile, 'auto'>;

const TOOL_PROFILES: Record<ConcreteProfile, string[]> = {
  full: [],                                                 // no filtering
  minimal: ['read_file', 'write_file', 'string_replace',
            'execute_bash', 'find_files',
            'search_file_contents', 'list_directory', 'agent'],
  nano:   ['read_file', 'string_replace', 'write_file',
            'execute_bash', 'search_file_contents'],
};
```

A few details worth knowing about that shape:

- `full` is the empty array. Empty means "no filtering applied" - all registered tools, including MCP servers, remain available. The convention lets `minimal` and `nano` be hand-maintained allowlists while `full` stays correct as new tools land.
- MCP tools are excluded from `minimal` and `nano` by construction: only built-in tool names appear in the allowlists. A user with custom MCP servers who switches to a small model and is surprised at the missing tool is being told, honestly, that the surface area has been trimmed.
- The drift guard test (`source/tools/tool-profiles.spec.ts`) iterates each profile and asserts that every named tool is registered with `ToolManager`. A renamed tool that leaves a dangling entry behind fails the test on the next CI run, rather than silently filtering nothing.
- `nano` drops the `agent` tool - subagent delegation is off the table for the smallest models. This is a deliberate scope cut: delegation adds prompt weight, error-recovery complexity, and a turn-multiplier that tiny local models do not benefit from.

## The consolidation: why 19

The 33-to-19 number is a result, not a target. Three buckets drove it:

- **Tasks** collapsed from four tools into a single `write_tasks`. The model no longer juggles task ids, completion flags, and per-task update calls; it just writes the current state of the list. That removed three tools and removed a class of bug where the model left stale ids behind.
- **File ops** merged `delete_file`, `move`, `copy`, and `create_directory` into one `file_op` with an `operation` discriminator. Four tools became one. The merger is shape-preserving for the common case and the move/copy/create variants keep their previous semantics under the same schema.
- **Git** shrank from eleven tools to six: `status`, `diff`, `log`, `add`, `commit`, `pr`. Rare operations - branch, checkout, stash, push, fetch, remote management - route through `execute_bash`. The git subagent workflow still uses the typed tools where it adds value; the model can always shell out when it needs the long tail.

Roughly 6.3k lines went away across this work, including dedup across config loaders, git exec, command dispatch, and the conversation-loop flush path. The consolidation is also what made `auto` defensible as a default: with a hand-curated allowlist for each profile, the heuristic at the top is small enough to be obviously right and the drift guard keeps it that way.

## The heuristic: how `auto` picks from the model id

The decision lives in `inferToolProfile`, and it is short on purpose:

```ts
// source/tools/tool-profiles.ts
function modelParamsBillions(model: string): number | null {
  const lower = model.toLowerCase();

  // Millions suffix (e.g. 135m) - always tiny.
  const millions = lower.match(/(\d+(?:\.\d+)?)\s*m\b(?![a-z])/g);
  if (millions && millions.length > 0) {
    return 0.5; // treat any sub-billion model as tiny
  }

  // Billions suffix - take the last match (model tags put the size last).
  const billions = [...lower.matchAll(/(\d+(?:\.\d+)?)\s*b\b(?![a-z])/g)];
  if (billions.length > 0) {
    const last = billions[billions.length - 1];
    return parseFloat(last[1]);
  }

  return null;
}

export function inferToolProfile(model?: string): ConcreteProfile {
  if (!model) return 'full';
  const params = modelParamsBillions(model);
  if (params === null) return 'full'; // cloud / unknown - assume capable
  if (params <= 4)  return 'nano';
  if (params <= 15) return 'minimal';
  return 'full';
}
```

A few decisions worth being explicit about:

- **Cloud models get `full` by default.** A model id with no size hint (`gpt-4o`, `claude-opus-4-8`, `o3-mini`) is treated as "the user is paying for capability, give it the surface area". The threshold for "I know this is small" is a size suffix in the id; the absence of that hint is the signal of capability. A small open-source model without a `:NxB` tag will be misclassified as `full`, which is the safer failure mode - a too-large tool set is a runtime perf issue, not a correctness issue.
- **The `<=4B` boundary is the nano threshold**, `<=15B` is minimal, anything larger is full. The spec suite locks these: `llama3.2:1b`, `deepseek-r1:1.5b`, `gemma2:2b`, `phi3:3.8b`, and `smollm:135m` all resolve to `nano`; `qwen2.5-coder:7b`, `llama3.1:8b`, `mistral-nemo:12b` to `minimal`; `gpt-oss:20b`, `qwen2.5-coder:32b`, `llama3.3:70b` to `full`.
- **The "last match wins" rule** handles tag-style ids where the size is at the end (`qwen2.5-coder:7b`) and base-model references where the size might be earlier in a longer string. Picking the last match is the same heuristic Ollama and LM Studio use when parsing tags; it is the least surprising choice.
- **`auto` propagates through every helper.** `isSingleToolProfile('auto', 'llama3.2:1b')` returns true. `isNanoProfile('auto', 'qwen2.5-coder:7b')` returns false. `getToolsForProfile('auto', 'qwen2.5-coder:7b')` returns the eight-tool minimal list. The auto meta-profile is resolved once per call, and the rest of the codebase never needs to know `auto` exists.

## What the resolved profile actually changes

`auto` and its resolved concrete profile feed four distinct code paths.

**1. The tool list.** `ToolManager.getAvailableToolNames` is the single authority for tool availability. It runs the tune profile first, then the mode exclusions, then the user-configured `disabledTools` list, in that order. When `toolProfile: 'auto'` resolves to `minimal` for a 7B model, the tool list the model sees is the eight-tool allowlist above; the conversation loop builds the prompt against that exact list.

```ts
// source/tools/tool-manager.ts (excerpt)
if (tuneConfig?.enabled) {
  const profile = resolveToolProfile(tuneConfig.toolProfile, model);
  if (profile !== 'full') {
    const profileTools = getToolsForProfile(profile);
    if (profileTools.length > 0) {
      names = profileTools;
    }
  }
}
```

**2. The system prompt.** `buildSystemPrompt` switches its sections based on the resolved profile. Under `nano`, the `CORE PRINCIPLES` section is dropped, the `TASK APPROACH`, `FILE OPERATIONS`, and `CONSTRAINTS` sections use the `-nano` variants (each capped at a few lines), the verbose `SYSTEM INFORMATION` block becomes a single `## SYSTEM` line, and `AGENTS.md` is omitted by default. The full doc puts the result at roughly 150-250 tokens for `nano`, versus 500-700 for `minimal` and the full multi-thousand-token default.

**3. Single-tool enforcement.** Both `minimal` and `nano` enable single-tool mode in the conversation loop:

```ts
// source/hooks/chat-handler/conversation/conversation-loop.tsx
const enforceSingleTool =
  tune?.enabled && isSingleToolProfile(tune.toolProfile, currentModel);
if (enforceSingleTool && allToolCalls.length > 1) {
  allToolCalls = allToolCalls.slice(0, 1);
}
```

Small local models struggle to choose one tool from a list and produce a coherent response. Truncating to the first call and forcing a wait-for-result cycle matches how the model wants to work and turns "model tried to do three things and forgot the schema on the second" into a recoverable failure mode.

**4. The status bar and `/usage`.** The development-mode indicator resolves the profile against the live model and shows `tune: nano (auto)` (or just `tune: nano` on narrow terminals). `/usage` rebuilds from the live tune, mode, and model - the `toolDefinitions` count reflects what is actually loaded, and the system-prompt token count reflects the nano-variant sections. The spec explicitly guards this with `t.true(nanoBreakdown.toolDefinitions < fullBreakdown.toolDefinitions)` so a regression that lets `/usage` count the full registry under `nano` is caught on the next run.

## The 5-layer config hierarchy

`resolveTune` in `source/config/tune.ts` is what makes the per-provider example from the docs work:

```ts
export function resolveTune(
  appConfig?: AppConfig,
  providerConfig?: AIProviderConfig,
  preferences?: UserPreferences,
  sessionOverride?: TuneConfig,
): TuneConfig {
  let resolved: TuneConfig = {...TUNE_DEFAULTS};

  if (appConfig?.tune)              resolved = {...resolved, ...appConfig.tune};
  if (providerConfig?.tune)         resolved = {...resolved, ...providerConfig.tune};
  if (preferences?.tune)            resolved = {...resolved, ...preferences.tune};
  if (sessionOverride)              resolved = {...resolved, ...sessionOverride};

  return resolved;
}
```

Five layers, highest priority wins:

1. **Hardcoded defaults** - `enabled: false`, `toolProfile: 'full'`, `aggressiveCompact: false`. The "do nothing" baseline.
2. **Top-level config** - `tune` block in `agents.config.json`. Applies to every provider.
3. **Per-provider config** - `tune` inside a provider entry. The docs' Ollama example pins `toolProfile: 'minimal'` and `aggressiveCompact: true` to that provider; switching to a different provider falls back to layer 2.
4. **Preferences** - the user's `/tune` choices, persisted to `nanocoder-preferences.json`. Survives session restarts.
5. **Session override** - in-memory changes made during the current session. Highest priority.

The useful consequence is that an operator can ship a project-level `agents.config.json` with `tune.toolProfile: 'auto'` as a global default, layer a per-provider `toolProfile: 'minimal'` on top of the Ollama provider that everyone on the team uses for the 7B model, and let individual users still flip into `nano` from the `/tune` UI without touching config. The merge is shallow (`...resolved, ...layer`), so a layer that sets `enabled: true` does not erase `toolProfile` set by a lower layer - only the keys present on the higher layer win.

## Interaction with development modes

The tune profile is not the only thing filtering the tool list. `MODE_EXCLUDED_TOOLS` removes mode-incompatible tools on top of the profile filter, and the tune `enabled` flag is independent of the mode. In practice, three combinations matter:

- **`plan` + `minimal`** is the small-model planning setup. The four exploration tools (`read_file`, `find_files`, `search_file_contents`, `list_directory`) survive the mode exclusions, the slim prompt keeps the model on task, and the typed plan output is the canonical small-model workflow. The companion local-model safety additions in v1.28.0 (read-before-edit guards and tool-call loop detection) cover the failure modes that come up most often when a small model is left running on its own.
- **`plan` + `nano`** trims further. The exploration surface is `read_file` and `search_file_contents` only, the plan-mode prompt uses the nano variant, and `find_files` is gone. Useful on the smallest hardware, where even a glob-style file finder is too expensive to invoke.
- **`plan` + `full`** keeps the full plan surface, including the read-only git tools and the diagnostics. This is the mode for a capable model that needs a structured plan before doing anything destructive.

The mode filter runs after the tune filter in `getAvailableToolNames`, so a profile that excludes `find_files` and a mode that excludes `delete_file` together produce the intersection. The order is intentional: the profile says "this model cannot handle the full surface", the mode says "this session is read-only" - whichever is tighter wins.

A small but important fix shipped alongside this: the executor used to capture the development mode once at startup and silently ignore any later Shift+Tab switch. That is now resolved at every approval decision, so a subagent that starts in `normal` and gets promoted to `yolo` mid-run actually runs in `yolo`. The tune profile does not change with a mode switch (it follows the model), but the mode policy applied on top of the profile does, which is the interaction that mattered.

## Live re-resolution on model switch

The `currentModel` state is the only input the profile helpers need, and it is the same React state passed into every consumer that builds a tool list or a prompt. When a user changes model mid-session - via the model picker, a CLI flag, or a config reload - the next render of `buildSystemPrompt`, the next call to `getAvailableToolNames`, and the next render of the status-bar indicator all see the new model id and produce output against the new resolved profile. There is no explicit "rebuild" call: the profile is recomputed from the live model each time, which is what makes `tune: nano (auto)` switch to `tune: minimal (auto)` the instant you swap from `qwen2.5-coder:1.5b` to `qwen2.5-coder:7b`.

`warnIfHistoryWontFit` runs alongside the switch and surfaces a warning if the previous conversation is too large for the new model's context window. The conversation itself is kept - the model change is not a session reset - but the next turn rebuilds the tool list and the prompt against the new model, so a transition from a 70B cloud model to a 7B local model is a graceful trim rather than a hard cut.

For operators who want to pin a profile explicitly, the per-provider config layer is the place. The Ollama example in the docs is the canonical case: a team that uses Ollama for the 7B coding model and OpenRouter for the 70B model gets `minimal` automatically on Ollama and `full` automatically on OpenRouter, without touching the per-session state.

## What local-model workflows actually gain

In numbers, the gain is not subtle. A 7B model under `auto` resolved to `minimal` sees an eight-tool registry instead of a 19- (or 33-) tool one, and a system prompt in the 500-700 token range instead of the multi-thousand-token default. A 1-3B model under `auto` resolved to `nano` sees five tools, a 150-250 token prompt, single-tool enforcement on top, and `AGENTS.md` omitted. Both also skip the `agent` tool entirely, which removes a class of recovery bug that small models hit when subagent output drifts out of their context window.

In workflow terms:

- A small local model running unattended is materially safer than it was. The read-before-edit guards and tool-call loop detection that shipped alongside the consolidation land in the same code path the new profiles use, so a `nano` profile plus an unattended small model is a different shape of risk than the pre-v1.28.0 setup.
- Switching between a local 7B and a cloud model mid-session is a one-prompt operation, not a config edit. The status bar tells you what `auto` resolved to, so you can see the trim happen rather than guessing whether the smaller tool set is in effect.
- Operators can ship a project-level default that is right for the team's primary provider without forcing it on the one developer using a different model on their own machine. The 5-layer merge handles the override.

## What is still rough

A few honest limits:

- **Profile resolution is name-based, not metadata-based.** The heuristic parses a size suffix from the model id. A small local model whose tag does not carry a `:NxB` (or `NxM`) hint gets `full`. The safe failure mode, but worth knowing if you have a custom Ollama tag like `my-fine-tune` for a small base.
- **The MCP story under `minimal`/`nano` is "exclude", not "reduce".** A user with a dozen MCP servers and a small local model sees none of them, not a curated subset. Curating per-profile MCP allowlists is reasonable future work but is not in v1.28.0.
- **`auto` is silent on capability boundaries it cannot see.** A 70B model on a slow inference server will still get `full`; the profile does not account for throughput. If your cloud model is hitting context-budget or latency issues, the lever is still `/tune`, not the auto heuristic.
- **The drift guard catches renamed tools but not renamed provider names.** If you rename a custom tool, the test only checks the built-in profiles' allowlists; custom tools are loaded dynamically.

## Closing

The v1.28.0 tool consolidation was not really about the count. It was about making it cheap to ship hand-curated tool allowlists, which made it cheap to make `auto` the default, which made the five-line `modelParamsBillions` heuristic the thing the user actually sees. The 5-layer config hierarchy is what lets an operator tune the default without forcing it, the development-mode filter is what keeps the profile honest about read-only and approval policy, and the live re-resolution is what makes the whole thing feel like one runtime rather than five configs you have to remember to flip.

If you try `auto` on a small local model and it picks the wrong profile, or if you want a model size to map differently, the easiest place to push is `source/tools/tool-profiles.ts` - the heuristic is small and the spec is the spec. Open an issue on the [Nanocoder repo](https://github.com/Nano-Collective/nanocoder) if you hit something that the heuristic cannot read.



Nanocoder v1.28.0 ships two changes that compound into one quiet usability win.

The built-in tool surface was consolidated from 33 tools down to 19. Tasks collapsed into a single `write_tasks`. File ops merged into one `file_op`. Git shrank to six typed tools, with the long tail routing through `execute_bash`.

On top of that, the new default tune profile is `auto`. It parses a size suffix from the active model id and resolves to `full`, `minimal`, or `nano` at runtime. A 7B local model under `auto` gets the eight-tool minimal allowlist, a 1-3B model gets the five-tool nano set with single-tool enforcement and an ultra-slim prompt, and a cloud model with no size hint gets the full surface unchanged. Switch models mid-session and the profile re-resolves live - the next turn rebuilds the tool list, the system prompt, and the status bar against the new resolved profile.

The tune config resolves through a 5-layer merge (hardcoded defaults -> top-level config -> per-provider config -> user preferences -> session override), so an operator can pin a profile for one provider while letting other providers stay on `auto`. Development modes layer on top of the profile: `plan` + `nano` is the small-model planning setup, `plan` + `minimal` adds the four-tool exploration surface, and `plan` + `full` keeps everything including the read-only git tools.

Full write-up on the Nanocoder repo: https://github.com/Nano-Collective/nanocoder

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



The headline of Nanocoder v1.28.0 mentions "tool surface consolidated from 33 to 19, automatic tune profile as default." That's two changes, not one, and the second is the more interesting one if you actually run small local models.

Here's the thing we wanted to land: a single `toolProfile: 'auto'` config value that does the right thing at runtime, with no per-model config drift, no manual tune tweaking every time you swap between your 7B local model and your cloud model, and no prompt-engineering ceremony to get a small model to behave.

What shipped:

- The tool surface genuinely is smaller. Tasks are one tool now (`write_tasks` with a replace-the-whole-list semantic - no ids for the model to juggle). File ops are one tool (`file_op` with an `operation` discriminator covering delete/move/copy/create_directory). Git is six typed tools, with branch/checkout/stash/push routing through `execute_bash`. ~6.3k lines went away.
- `auto` parses a size suffix from the active model id and picks `full`, `minimal`, or `nano`. `:1b`, `:1.5b`, `:2b`, `:3.8b`, `:135m` -> nano. `:7b`, `:8b`, `:12b` -> minimal. `:20b`, `:32b`, `:70b`, or anything with no size hint (cloud models) -> full.
- The resolved profile re-resolves on model switch. The status bar shows what `auto` picked (`tune: nano (auto)` on a wide terminal, just `tune: nano` when narrow). `/usage` reflects the live profile - the tool-definitions token count is whatever the resolved profile actually loaded.
- Development modes layer on top. `plan` + `nano` is the smallest viable planning setup. `plan` + `minimal` is the small-model planning sweet spot. `plan` + `full` keeps the typed read-only git and diagnostics. The mode filter runs after the tune filter, so the tighter of the two wins.
- The tune config resolves through 5 layers: hardcoded defaults, top-level `agents.config.json` `tune` block, per-provider `tune`, user preferences (`nanocoder-preferences.json`), and session override. Shallow merge, so a layer that sets `enabled: true` doesn't erase `toolProfile` set by a lower layer.

Why this matters for small-model workflows specifically:

The `nano` profile drops the `agent` tool entirely (subagent delegation adds prompt weight and recovery complexity that tiny models do not benefit from), enforces single-tool mode in the conversation loop, omits `AGENTS.md` from the prompt by default, and uses short-form prompt sections (the `-nano` variants of TASK APPROACH, FILE OPERATIONS, CONSTRAINTS). Result: ~150-250 token system prompt instead of the multi-thousand-token default, which is most of a 1-3B model's context window. Combined with the read-before-edit guards and tool-call loop detection that also landed in v1.28.0, unattended small models are a different shape of risk than they were before.

A few things we're honest about:

- The heuristic is name-based. A small local model whose tag does not carry a `:NxB` (or `NxM`) hint gets `full`. The safe failure mode (a too-large tool set is a perf issue, not a correctness issue), but worth knowing if you've renamed an Ollama tag.
- MCP tools are excluded from `minimal` and `nano` by construction. A user with custom MCP servers and a small local model sees none of them, not a curated subset. Curating per-profile MCP allowlists is reasonable future work but not in this release.
- A 70B model on a slow inference server still gets `full`. The heuristic doesn't know about throughput. If your cloud model is hitting context-budget or latency issues, the lever is `/tune`, not the auto heuristic.

The code is the code if you want to look: `source/tools/tool-profiles.ts` is the heuristic (~130 lines including the spec), `source/config/tune.ts` is the 5-layer merge, `source/utils/prompt-builder.ts` is where the profile actually changes the prompt, and `source/components/development-mode-indicator.tsx` is what renders `tune: nano (auto)` on the status bar.

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

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



v1.28.0 ships an auto tune profile that infers full/minimal/nano from the active model's size suffix. Small local models get the slim tool set and a 150-250 token prompt. Switch models mid-session and it re-resolves live. https://github.com/Nano-Collective/nanocoder #nanocoder



The reflex: durable OSS needs a backer. A corp, a foundation grant, something.

The Nano Collective has none of those. No investors. No equity. No profit-taking. Fiscally hosted by Open Source Collective. Books public, on the ledger, in real time.



Most tools treat a sitemap like an open tap. get-md ships --max-urls, --max-depth, and repeatable --include/--exclude globs by default, so the crawl has a kill switch before it starts.


The reflex is migrations in a separate CLI or service, far from the code that reads the data. json-up keeps them in the consuming repo as a Zod-typed chain, so schema, migration, and reader age together instead of drifting apart.



You paste real code into a coding agent every day. You do not want it phoning home. Nanocoder ships zero telemetry, zero install ping, zero usage metrics, so the whole loop runs on a local model with no outbound traffic at all.



A fine-tune producing nonsense almost always traces back to silent data bugs. Run `nanotune data validate` before `nanotune train`: duplicates, broken role alternation in multi-turn JSONL, missing context messages. Seconds of work, hours of debugging later.


Your `ls` output is part of your prompt. So is `git log`, `cat`, and `grep`.

prompt-scrub runs on every message regardless of origin. Tool results get scrubbed before the next LLM turn, not just what you typed.

The leak surface is the whole conversation, not the user input.


A whitepaper the original author abandons usually dies. At the Nano Collective it doesn't. Add your name as proposer in the file, open an issue, carry on. 60 days idle and it goes to Paused, not to the bin. Someone else can pick it up.



Most HTML-to-markdown tools hand you the page chrome and let a regex clean it up after.

get-md runs Mozilla Readability first. The extraction layer throws the chrome out, then Turndown sees only the article. Clean at the content layer, not at the markdown layer.



0. That's the version json-up assigns your JSON when there's no `_version` field - and it runs every migration in your chain to catch it up. Legacy data stops falling through.



A 4B model carrying a 700-token system prompt has forgotten the question by the second tool call.

Nanocoder's /tune auto-resolves: 4B and below get nano, 15B and below get minimal, no config to set.



Hearing "fine-tune a model" and reaching for an A100 rental is the default. Nanotune runs LoRA on Apple Silicon via MLX, with a guided install that handles the setup. No remote runner, no spot instance, just your Mac.


The detector set shouldn't grow by patching the engine. prompt-scrub ships detectors as npm rule packs, so a domain-specific check is a package that exports a Detector array, not a fork. The principle: the core stays small, the rules travel.


Your first benchmark on a new Mac should not end in an OOM, and you should not need a cheat sheet for threads, GPU layers, and ctx-size. Nanotune ships presets. `nanotune benchmark --preset medium` sets sane defaults for a modern laptop, so it finishes.



Your terminal agent shouldn't phone home by default. Nanocoder ships Ollama, llama.cpp, MLX, llama-swap, vLLM, LM Studio, and LocalAI as first-class providers, so the local loop is the one you reach for, not the one you bolt on.


Merging a whitepaper used to read as a build promise from the Nano Collective. It wasn't, and we are calling that out. Stage 1 now publishes the thinking. Stage 3, after 30 days of public review, is the build call, recorded on the page with rationale.



`getmd notes.md` isn't a no-op. While `.pdf`, `.docx`, and `.html` route to their extractors by extension, `.md` skips HTML parsing and still runs frontmatter + structure normalisation. Same CLI, four formats, no flags to remember.


Most migration APIs force an all-or-nothing choice: sync or async, end to end.

json-up's createAsyncMigrations() does not. Each up() can be sync or async, freely mixed in one chain. Adopt async work one migration at a time, no global rewrite.


Most CLI coding tools need a bespoke editor extension to feel native. Nanocoder just speaks the Agent Client Protocol. Run `nanocoder --acp` and Zed drives the tools, diffs, and permission prompts as a native agent, no extension to maintain.


One JSONL row can be a full conversation. Nanotune keeps every turn in the same `messages` array, so the `/greet` example and the follow-up `/my name is` example train together. `data validate` catches a broken role alternation before you burn GPU on a run.



A VPN hides where the request came from, not what it says. Prompt privacy is a content problem.

prompt-scrub rewrites the prompt before it leaves, swapping emails, paths, and secrets for placeholders. Compose it with whatever network tool you trust; the layers are independent.



The whole NC financial model fits on a napkin. Two destinations for every dollar: running the collective, or the community fund paying OSS bounties via OSC. Split is published in the Economics Charter, with 30 days notice before any change. New terms apply to new work only.


A 1000-page crawl with `--cache` isn't a clever optimisation. It's the normal case.

`get-md` stores successful responses under `~/.get-md/cache`, so reruns hit disk instead of the network. `--cache-max-age` is the only knob that decides whether you re-fetch.


Versioning JSON without a migration path is debt you pay at 2am. The shape of v2 matters less than how data gets from v1 to v2, so json-up keeps the schema and the `up()` in the same object.


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

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

## What changed

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

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

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

## Preserved: Mermaid fences survive conversion

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

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

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

## Recovered: Mermaid source from rendered SVG

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

The recovery looks for these container shapes:

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

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

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

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

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

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

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

A few constraints worth stating up front:

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

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

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

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

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

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

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

## Bug fixes from the launch review

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

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

## Behaviour change: code-block language tags survive

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

## Installation

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

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

For the optional paths:

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

# Mermaid validation
npm install mermaid
```

## Usage

```bash
getmd
```

Or from a script:

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

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

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

## Documentation

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

## Tests

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

## Upgrading

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

Or:

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

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

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

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


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


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

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

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

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

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

634 tests passing, up from 592 at 1.6.0.

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

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

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



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

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

**What we shipped**

Four diagram behaviours, each independently switchable:

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

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

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

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

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

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

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

**Other fixes**

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

**Install footprint**

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

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

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

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

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



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

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



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


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


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


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



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


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

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

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

## Native VS Code GUI

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

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

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

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

Thanks to @akramcodez and @Dhirenderchoudhary for the build.

## Attach to a running subagent

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

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

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

## Privacy-aware prompt scrubbing

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

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

Thanks to @akramcodez.

## Mode-specific provider and model configuration

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

Closes #277. Thanks to @akramcodez.

## Interactive questions in plan mode

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

## TUI refinements

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

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

## Session resume, CLI flags

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

## New commands and flags

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

## Under the hood

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

## Providers

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

## Fixes

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

## Documentation

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

## Dependency updates

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

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

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

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


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

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

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

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

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

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


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

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

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

## TUI work

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

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

## Smaller but useful

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

## Under the hood

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

## Providers

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

## Fixes worth calling out

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

## Documentation

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

## Who this is for

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

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


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


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

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



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



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


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



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


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



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

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

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

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

## What Sentinel does

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

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

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

## The audit loop

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

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

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

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

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

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

## Filing on a fresh repo

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

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

## Auto-resolution

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

## Dry-run

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

## What Sentinel does not do

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

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

## Install

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

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

## What is coming

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

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

## Links

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

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

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


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


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

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

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

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

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

Install:

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

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

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



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



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


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



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



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


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



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


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



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



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



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



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

## The short version

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

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

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

## What was wrong with the old framing

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

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

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

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

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

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

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

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

## The honest position on local models today

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

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

## The differentiator that can't be copied

Features can be copied. The ownership model cannot.

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

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

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

---

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

Why we updated how we describe Nanocoder


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

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

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

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

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

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

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

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

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

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

→ https://nanocollective.org


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

July 2026

Wednesday, July 810 posts