Skip to content

See how your app actually fits together. An interactive, plain-English map of your codebase, drawn by Claude or Codex.

Floorplan 0.4.4: the CLAUDE.local.md note only when the user says yes, and each pre-approved script named

Hayden Smith3756808a120c
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 666ad99..d8b5d66 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "floorplan",
- "version": "0.4.3",
+ "version": "0.4.4",
"description": "See how your app actually fits together: an interactive map of your codebase where every part, file and web request has a plain-English name and description, with a health check, screens, guided flows, questions answered on the map, and highlights of what was just worked on.",
"author": {
"name": "Hayden Smith",
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
index 74ad921..84f9178 100644
--- a/.codex-plugin/plugin.json
+++ b/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "floorplan",
- "version": "0.4.3",
+ "version": "0.4.4",
"description": "See how your app actually fits together: an interactive map of your codebase where every part, file and web request has a plain-English name and description, with a health check, screens, guided flows, questions answered on the map, and highlights of what was just worked on.",
"author": {
"name": "Hayden Smith",
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6fd1272..dd245b7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,10 @@
# Changelog
+## 0.4.4 (2026-10-31)
+
+- **The note for future sessions is now your choice:** in Claude Code, Floorplan no longer adds its section to `CLAUDE.local.md` on its own. After your first map, Claude asks whether future sessions in the project should use it, and adds the note only if you say yes. A note you already have is kept up to date; delete it to remove it.
+- **Pre-approved commands named one by one:** the skill now lists each of its eight scripts by name, instead of approving anything in its scripts folder.
+
## 0.4.3 (2026-10-31)
- **Links for the Claude plugin directory:** the Claude Code manifest now points to the documentation, the privacy and security page, and GitHub issues for support, so a directory listing shows the right links. Nothing else changed.
diff --git a/CHECKSUMS.txt b/CHECKSUMS.txt
index 65592c8..05982f5 100644
--- a/CHECKSUMS.txt
+++ b/CHECKSUMS.txt
@@ -1,13 +1,13 @@
-# Floorplan 0.4.3: SHA-256 of every file the plugin runs from.
+# Floorplan 0.4.4: SHA-256 of every file the plugin runs from.
# Check an installed copy: clone this release, then run node tools/checksums.mjs --check <installed folder>.
43adc6c187150c4b0a4841f0e7448381401be93ee65e2d212be4e7eeb67bb3e4 .agents/plugins/marketplace.json
fdce61be9c420fd16b8cbbff629baa37e8d1096094b3e90bc5ecc0fe1ffc3a78 .claude-plugin/icon.png
98cd297588a52fc7715d29ad10636f3224ee7a99bfbb94230315493dabc7147c .claude-plugin/marketplace.json
-14688306dab400f091771fb90cbcbe4db067421f2e7aec584efa653e1208fa37 .claude-plugin/plugin.json
+fc2280e75b4f8024b7e329c476bf043c1bb0ee930070c90bcc03e2d472cfdcd4 .claude-plugin/plugin.json
7bdb74d57875b25ca9dcd367f79f92b9089f5f4b873bffec898cc6c3f0a84a68 .codex-plugin/icon.png
-ad4e805a75e94b1416654f7789a7d5069ff403a1c452eb1e054f4eadcbcc7036 .codex-plugin/plugin.json
+dac3735bc4e34f6e4509829078ce170e6ff4439cadc209358675d62976ff1905 .codex-plugin/plugin.json
e1cdfc2a2f1ae41796c8eae54eed099f95d09d25f2ec521742d3ab7a8aba1337 package.json
-3e6508e7708904757024b8bebef744d53e96cc37e62c86c6793ab2b44436198a skills/floorplan/SKILL.md
+b37400a753271adeca4127bf596b3c001702b362f2b5782b3db713c650afad16 skills/floorplan/SKILL.md
4dde86cace299094c246604badb73b605a10f47e01a72cc6746680788a7e20f9 skills/floorplan/agents/openai.yaml
91485d6e067e25f742939ee7903d97096e560bfebdb32b71b428294ef2c781d9 skills/floorplan/assets/favicon.png
60c5ef78ab48cb60fed2a3d712dc8b48c017245042bf7139d242844790f77f3c skills/floorplan/assets/graph-query.js
@@ -36,11 +36,11 @@ fd4db7bf1ed9e5437cdb36ac092c37f56cf0e336d525b25a06897a35b4a4d52c skills/floorpl
ac2460a6613956209895d970213630d9d99475745ba761fd842982e2f5ccec13 skills/floorplan/references/choosing-boundaries.md
83db6fbd2e117ebcb2a21b115ccd38125a1d977a79fc19050dd0ca2f67a25730 skills/floorplan/references/schema.md
9805cbe487912b2995594fa3bd4fa7650fa963aee622558097d80b772965588a skills/floorplan/references/writing-descriptions.md
-e0eef6b78b2bbec7576760eb64d12db341b579305cc7e8ead0258f81a54cee94 skills/floorplan/scripts/build.mjs
+10272adc387a5ac9afc2515feb3c4109a03db36c81752d533f5c790b5273c124 skills/floorplan/scripts/build.mjs
bb02ef4b60dafb05a74eb2561f22a530b5b17935783bd88731c5bea5b6d57609 skills/floorplan/scripts/describe.mjs
3f1ed916b8e3e7fb240e3db04be86a5a3d57e2cb78fe5fd6100fcedc4edf2206 skills/floorplan/scripts/lib/agent.mjs
0cd705247440591764a3387cd9ec0ddb80fe72887728dd4e4b92b6ef6077dc7e skills/floorplan/scripts/lib/blueprint.mjs
-24f7805618225f401af350d8b1e960720ce3c569c07891839aa3bee66e1d898c skills/floorplan/scripts/lib/claudemd.mjs
+2db69e2bc682c69ea2e1e760bb35badeb7fc035d3d788ee174d183e3128a2056 skills/floorplan/scripts/lib/claudemd.mjs
2baec756cdc47fffa34d945eae7c5027c1c5b9d4cb300d38970f0247ebc4800b skills/floorplan/scripts/lib/common.mjs
47e7db0180395a95e2ec9a075d970f0e03c6210b0bd88b76ae067c9ccfcec7c9 skills/floorplan/scripts/lib/extract.mjs
ec4a537b17f1b64968e914c5305302501387dcba7ae84011aa7b8c4f602c597b skills/floorplan/scripts/lib/health.mjs
diff --git a/README.md b/README.md
index dd28a10..c98beee 100644
--- a/README.md
+++ b/README.md
@@ -14,7 +14,7 @@ Claude or Codex reads your codebase and draws an interactive map of it. Every pa
[![Claude Code plugin](https://img.shields.io/badge/Claude%20Code-plugin-D97757?style=flat-square)](https://code.claude.com/docs/en/overview)
[![Codex plugin](https://img.shields.io/badge/Codex-plugin-111?style=flat-square)](docs/codex.md)
[![Tests](https://img.shields.io/github/actions/workflow/status/haydenschmitty/floorplan/test.yml?branch=main&style=flat-square&label=tests)](https://github.com/haydenschmitty/floorplan/actions/workflows/test.yml)
-[![Version](https://img.shields.io/badge/version-0.4.3-111?style=flat-square)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-0.4.4-111?style=flat-square)](CHANGELOG.md)
[![License: MIT](https://img.shields.io/badge/license-MIT-111?style=flat-square)](LICENSE)
[![Node 18+](https://img.shields.io/badge/node-%E2%89%A518-111?style=flat-square)](https://nodejs.org)
[![Zero dependencies](https://img.shields.io/badge/dependencies-0-111?style=flat-square)](#how-it-works)
@@ -226,7 +226,7 @@ Scripts do the mechanical work: finding repos, parsing code in a dozen languages
## What it adds to your project
-A `floorplan/` folder holding the map. In Claude Code it also adds a short section to `CLAUDE.local.md` so future sessions know the map is there. **Neither is committed:** the folder ignores itself in git, and `CLAUDE.local.md` goes in your clone's private ignore list. In Codex, only the `floorplan/` folder is added. Your `.gitignore` and other tracked files are never touched. See [What's in your project](docs/project-files.md).
+A `floorplan/` folder holding the map. In Claude Code, if you say yes, it also adds a short section to `CLAUDE.local.md` so future sessions know the map is there. **Neither is committed:** the folder ignores itself in git, and `CLAUDE.local.md` goes in your clone's private ignore list. In Codex, only the `floorplan/` folder is added. Your `.gitignore` and other tracked files are never touched. See [What's in your project](docs/project-files.md).
## Privacy
@@ -281,7 +281,7 @@ No. The map works without one. The Ask bar answers through the Claude Code CLI o
<details>
<summary><b>Will it change or commit my files?</b></summary>
-It only writes its own `floorplan/` folder (and, in Claude Code, a section in `CLAUDE.local.md`), and neither is committed. It never changes your code, your `.gitignore` or your `CLAUDE.md`.
+It only writes its own `floorplan/` folder (and, in Claude Code if you say yes, a section in `CLAUDE.local.md`), and neither is committed. It never changes your code, your `.gitignore` or your `CLAUDE.md`.
</details>
<details>
diff --git a/docs/codex.md b/docs/codex.md
index 3fde619..16b9d89 100644
--- a/docs/codex.md
+++ b/docs/codex.md
@@ -53,7 +53,7 @@ It finds `codex` on your PATH, and on Windows the CLI that comes with the Codex
## What's different from Claude Code
-- **No notes file.** In Claude Code, Floorplan keeps a short note in `CLAUDE.local.md` (personal and never committed) that points future sessions at the map. Codex has no personal, uncommitted equivalent (`AGENTS.md` is shared with your team), so in Codex Floorplan leaves your project's notes alone.
+- **No notes file.** In Claude Code, Floorplan can keep a short note in `CLAUDE.local.md` (personal and never committed, and only if you say yes) that points future sessions at the map. Codex has no personal, uncommitted equivalent (`AGENTS.md` is shared with your team), so in Codex Floorplan leaves your project's notes alone.
- **No Claude app.** Publishing the map to the Claude app is a Claude feature. In Codex the map opens in your browser, served from your computer.
- **"Fix with Codex".** The Health panel's ready-made fix prompts are for pasting into Codex. On a [blueprint](getting-started.md#plan-something-you-havent-built-yet), the same goes for **Build this with Codex**, and the Ask bar's **Change** switch runs Codex in its read-only sandbox too: Codex replies with the updated plan, and the map's server saves it.
diff --git a/docs/how-it-works.md b/docs/how-it-works.md
index 15c11be..9c5ca02 100644
--- a/docs/how-it-works.md
+++ b/docs/how-it-works.md
@@ -114,4 +114,4 @@ It uses whichever made the map, and the other one if that isn't installed. Eithe
In the Claude app, the map asks Claude through the app instead, with the same lookups but no access to your source.
-The same lookups help ordinary Claude Code sessions. The short section Floorplan adds to `CLAUDE.local.md` tells them to check the map (`query.mjs find`, `show`, `path`, `overview`) before searching the code from scratch.
+The same lookups help ordinary Claude Code sessions. If you say yes after your first map, the short section Floorplan adds to `CLAUDE.local.md` tells them to check the map (`query.mjs find`, `show`, `path`, `overview`) before searching the code from scratch.
diff --git a/docs/is-it-safe.md b/docs/is-it-safe.md
index 7fc4684..9418834 100644
--- a/docs/is-it-safe.md
+++ b/docs/is-it-safe.md
@@ -8,7 +8,7 @@ Plugins for Claude Code and Codex can run code on your computer, so it's worth a
- **No MCP servers.** Floorplan has none, so it never starts a server that downloads its newest version with `npx`.
- **No dependencies, no install scripts.** Nothing comes from npm, at install time or ever. Its `package.json` exists only to run the tests.
- **Never downloads anything, and never runs code from the internet.** No `eval`, no loading code at run time, no encoded payloads.
-- **Never changes your code.** It writes only its own `floorplan/` folder and, in Claude Code, a marked section of `CLAUDE.local.md`. See [What's in your project](project-files.md).
+- **Never changes your code.** It writes only its own `floorplan/` folder and, in Claude Code and only if you say yes, a marked section of `CLAUDE.local.md`. See [What's in your project](project-files.md).
- **No analytics or tracking.**
## Everything it does
@@ -35,7 +35,7 @@ Each is started directly with its arguments, never as a command line for a shell
### What runs without asking
-In Claude Code, while the skill is in use, it pre-approves one kind of command: `node` running one of its own scripts (`scripts/build.mjs`, `describe.mjs`, `open.mjs`, `plan.mjs`, `recent.mjs`, `refresh.mjs`, `scan.mjs` and `status.mjs`). That list is fixed by the tests below. Anything else Claude does asks according to your permission settings, as usual. Codex asks according to your approval settings.
+In Claude Code, while the skill is in use, it pre-approves one kind of command: `node` running one of its own scripts, each named exactly (`scripts/build.mjs`, `describe.mjs`, `open.mjs`, `plan.mjs`, `recent.mjs`, `refresh.mjs`, `scan.mjs` and `status.mjs`). That list is fixed by the tests below. Anything else Claude does asks according to your permission settings, as usual. Codex asks according to your approval settings.
### Three things worth explaining
diff --git a/docs/project-files.md b/docs/project-files.md
index 388f352..9146f89 100644
--- a/docs/project-files.md
+++ b/docs/project-files.md
@@ -1,6 +1,6 @@
# What's in your project
-Floorplan writes to exactly two places in your project: the `floorplan/` folder, and (in Claude Code) a short section in `CLAUDE.local.md`. Neither is committed to git, and nothing else in your project is touched.
+Floorplan writes to exactly two places in your project: the `floorplan/` folder, and (in Claude Code, only if you say yes) a short section in `CLAUDE.local.md`. Neither is committed to git, and nothing else in your project is touched.
## The `floorplan/` folder
@@ -37,14 +37,14 @@ The full format is in [`skills/floorplan/references/schema.md`](../skills/floorp
## `CLAUDE.local.md`
-In Claude Code, Floorplan adds a short marked section here, telling future Claude Code sessions in your project that the map exists and how to look things up in it. `CLAUDE.local.md` is Claude Code's file for personal project notes, loaded at the start of every session like `CLAUDE.md`. Floorplan:
+In Claude Code, after the first map, Claude asks whether future sessions in your project should use it. Only if you say yes, Floorplan adds a short marked section here, telling future Claude Code sessions that the map exists and how to look things up in it. `CLAUDE.local.md` is Claude Code's file for personal project notes, loaded at the start of every session like `CLAUDE.md`. Floorplan:
- creates the file if you don't have one;
-- only ever rewrites its own section, between `<!-- floorplan:start -->` and `<!-- floorplan:end -->`;
+- only ever rewrites its own section, between `<!-- floorplan:start -->` and `<!-- floorplan:end -->`, and keeps it current on each update;
- adds the file to your clone's private ignore list, `.git/info/exclude`.
-To turn it off, put `<!-- floorplan:off -->` anywhere in `CLAUDE.local.md`.
+To remove it, delete the section. To keep it from coming back, put `<!-- floorplan:off -->` anywhere in `CLAUDE.local.md`. (Before 0.4.4, Floorplan added the section without asking; if you have it from then, it stays until you remove it.)
-A blueprint adds no section, since there's no code to look up yet. It's added once the map switches to the real code.
+A blueprint adds no section, since there's no code to look up yet. Claude offers it once the map switches to the real code.
In Codex this file isn't touched. Codex has no personal, uncommitted notes file (`AGENTS.md` is shared with your team), so Floorplan doesn't add a note there.
diff --git a/skills/floorplan/SKILL.md b/skills/floorplan/SKILL.md
index 2c8bbf8..46f0acc 100644
--- a/skills/floorplan/SKILL.md
+++ b/skills/floorplan/SKILL.md
@@ -2,7 +2,15 @@
name: floorplan
description: Draw a floorplan of an app's codebase (one repo or several side by side), an interactive node-graph map where every subsystem, module, file and HTTP route has a human-readable name and a one-line description, connected by the imports and HTTP calls between them, at several zoom levels. It is saved as a self-contained floorplan/index.html in the codebase. Use whenever the user wants to visualize, map, diagram, document or get an architectural overview of a codebase, repo or monorepo, understand how their app works or is connected under the hood, onboard onto unfamiliar code, see how the frontend talks to the backend, or update an existing floorplan, even if they don't say "visualize". Also use it before any code exists: when the user shares a PRD, a spec or a description of something they want to build and asks what pieces it needs or how they'd fit together, it draws a blueprint, the same map planned from the document.
argument-hint: "[path-to-codebase-root] [--refresh]"
-allowed-tools: Bash(node ${CLAUDE_SKILL_DIR}/scripts/*)
+allowed-tools:
+ - Bash(node ${CLAUDE_SKILL_DIR}/scripts/build.mjs *)
+ - Bash(node ${CLAUDE_SKILL_DIR}/scripts/describe.mjs *)
+ - Bash(node ${CLAUDE_SKILL_DIR}/scripts/open.mjs *)
+ - Bash(node ${CLAUDE_SKILL_DIR}/scripts/plan.mjs *)
+ - Bash(node ${CLAUDE_SKILL_DIR}/scripts/recent.mjs *)
+ - Bash(node ${CLAUDE_SKILL_DIR}/scripts/refresh.mjs *)
+ - Bash(node ${CLAUDE_SKILL_DIR}/scripts/scan.mjs *)
+ - Bash(node ${CLAUDE_SKILL_DIR}/scripts/status.mjs *)
---
# Floorplan
@@ -86,7 +94,7 @@ The codebase root is the argument if one was given, otherwise the current direct
**Nothing Floorplan makes is committed.** `floorplan/` holds its own `.gitignore` that ignores the whole folder, so the project's tracked files aren't touched. If git already tracks files there, the build prints the `git rm -r --cached` command to untrack them; pass it on to the user rather than running it.
- Each build also keeps a short marked block in the project's `CLAUDE.local.md`, Claude Code's personal, uncommitted project notes, which load at session start like CLAUDE.md. The block tells future Claude Code sessions here that the map exists and how to look things up in it with `floorplan/query.mjs`, so they start from the map instead of searching the code from scratch. The build adds `CLAUDE.local.md` to the repo's local ignore list (`.git/info/exclude`, not `.gitignore`). It rewrites only its own block, and moves the block out of `CLAUDE.md` if an older version put it there. To opt out, pass `--no-claude-md`, or put `<!-- floorplan:off -->` in CLAUDE.local.md. Under Codex the build skips this: Codex has no personal, uncommitted notes file (AGENTS.md is shared with the team), so don't add one there either.
+ **A note for future sessions, only if the user wants one.** In Claude Code, the build can keep a short marked block in the project's `CLAUDE.local.md`, Claude Code's personal, uncommitted project notes, which load at session start like CLAUDE.md. The block tells future Claude Code sessions here that the map exists and how to look things up in it with `floorplan/query.mjs`, so they start from the map instead of searching the code from scratch. Because it changes how later sessions work, the build never adds it on its own: it reports `CLAUDE.LOCAL.MD not added`, and you offer it in your report (step 8). Only when the user says yes, run `node ${CLAUDE_SKILL_DIR}/scripts/build.mjs <root> --claude-md`. Once the block exists, every build keeps it current. The build adds `CLAUDE.local.md` to the repo's local ignore list (`.git/info/exclude`, not `.gitignore`), rewrites only its own block, and moves the block out of `CLAUDE.md` if an older version put it there. To remove it, the user deletes the block, or puts `<!-- floorplan:off -->` in CLAUDE.local.md to keep it from coming back. Under Codex the build skips this: Codex has no personal, uncommitted notes file (AGENTS.md is shared with the team), so don't add one there either.
6. **Describe every file and route.**
`node ${CLAUDE_SKILL_DIR}/scripts/describe.mjs <root>`
@@ -116,7 +124,7 @@ The codebase root is the argument if one was given, otherwise the current direct
- If you have an in-app browser or preview tool, pass `--no-open` and open the printed URL there instead, so the map appears right beside the conversation.
- If this is a remote or headless machine where the user can't reach 127.0.0.1, skip open.mjs and tell them to run `node floorplan/serve.mjs` on their own machine, or offer the Claude app route (step 9).
- Then **report.** Give the URL, then describe the architecture you mapped in 3–5 lines, in the user's language, including anything surprising: cycles, god-files, dead areas, coupled subsystems. Always mention the **high-severity Health items** (`graph.health`; the build output and graph.json list them). Hard-coded passwords/keys and endpoints anyone can change data through are things the owner needs to hear about. Never repeat a secret's value. Say that `architecture.json` and `descriptions/` are theirs to edit, and that after more work they can just ask to "update the floorplan", which re-reads only what changed. Give them those plain words rather than a command: in Claude Code the plugin's command is `/floorplan:floorplan` (`/floorplan` as a personal skill), and in Codex it's `$floorplan`. On a first run, mention in one line that the map stays out of git, and in Claude Code that its notes for future sessions (in CLAUDE.local.md) do too. On an update, start with what changed for what they asked (it's highlighted under **Recent work**).
+ Then **report.** Give the URL, then describe the architecture you mapped in 3–5 lines, in the user's language, including anything surprising: cycles, god-files, dead areas, coupled subsystems. Always mention the **high-severity Health items** (`graph.health`; the build output and graph.json list them). Hard-coded passwords/keys and endpoints anyone can change data through are things the owner needs to hear about. Never repeat a secret's value. Say that `architecture.json` and `descriptions/` are theirs to edit, and that after more work they can just ask to "update the floorplan", which re-reads only what changed. Give them those plain words rather than a command: in Claude Code the plugin's command is `/floorplan:floorplan` (`/floorplan` as a personal skill), and in Codex it's `$floorplan`. On a first run, mention in one line that the map stays out of git. In Claude Code, when the build said `CLAUDE.LOCAL.MD not added`, end by asking once whether future Claude Code sessions in this project should use the map: you'd add a short note to their personal, uncommitted CLAUDE.local.md. Add it (`build.mjs <root> --claude-md`) only on a yes, and don't ask again on later updates if they said no. On an update, start with what changed for what they asked (it's highlighted under **Recent work**).
## 9. Opening the map and asking questions
diff --git a/skills/floorplan/scripts/build.mjs b/skills/floorplan/scripts/build.mjs
index d84c587..12fe0be 100644
--- a/skills/floorplan/scripts/build.mjs
+++ b/skills/floorplan/scripts/build.mjs
@@ -474,7 +474,7 @@ report.push(graph.recent
// equivalent (AGENTS.md is shared with the team), so a map built by Codex leaves the project's notes alone.
if (agent === 'codex') report.push('AGENT Codex: questions on the map run through Codex');
else if (scan.blueprint) report.push('BLUEPRINT planned, not built yet: drawn from floorplan/plan.json');
-else if (!args['no-claude-md']) report.push(`CLAUDE.LOCAL.MD ${writeClaudeMd(root, outDir)}`);
+else if (!args['no-claude-md']) report.push(`CLAUDE.LOCAL.MD ${writeClaudeMd(root, outDir, { add: !!args['claude-md'] })}`);
report.push(trackedWarning ? `GIT ! ${trackedWarning}` : 'GIT floorplan/ is kept out of git (it ignores itself)');
report.push('');
report.push(`✓ wrote ${path.relative(root, path.join(outDir, 'index.html'))} (${fmtNum(Math.round(html.length / 1024))} KB) and graph.json`);
diff --git a/skills/floorplan/scripts/lib/claudemd.mjs b/skills/floorplan/scripts/lib/claudemd.mjs
index 1636e79..54a54e8 100644
--- a/skills/floorplan/scripts/lib/claudemd.mjs
+++ b/skills/floorplan/scripts/lib/claudemd.mjs
@@ -4,7 +4,8 @@
// including from parent folders); the map itself isn't committed, so its pointer isn't either. The file
// is added to the repo's local ignore list (.git/info/exclude), which leaves tracked files untouched.
// The block sits between markers and is rewritten in place; the rest of the file is never touched.
-// Put <!-- floorplan:off --> in CLAUDE.local.md to opt out.
+// It's added only when the user asks for it (build.mjs --claude-md); a block that's already there is
+// kept current. Put <!-- floorplan:off --> in CLAUDE.local.md to opt out.
import fs from 'node:fs';
import path from 'node:path';
import { git } from './common.mjs';
@@ -54,10 +55,12 @@ function excludeLocally(root) {
return 'ignored locally via .git/info/exclude';
}
-/** Adds or refreshes the block, and moves it out of a committed CLAUDE.md written by older versions. */
-export function writeClaudeMd(root, outDir) {
+/** Refreshes the block, or adds it when `add` (the user asked for it); moves it out of a committed CLAUDE.md written by older versions. */
+export function writeClaudeMd(root, outDir, { add = false } = {}) {
const rel = path.relative(root, outDir).replace(/\\/g, '/');
if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return 'skipped (map is outside the codebase)';
+ const had = ['CLAUDE.local.md', 'CLAUDE.md', path.join('.claude', 'CLAUDE.md')].some((f) => stripBlock(read(path.join(root, f)) ?? '') != null);
+ if (!add && !had) return 'not added (offer it to the user; add it with --claude-md)';
const notes = [];
// older versions wrote the block into CLAUDE.md, which is usually committed: take it back out
diff --git a/tests/agents.test.mjs b/tests/agents.test.mjs
index a87e2bc..9eab9f6 100644
--- a/tests/agents.test.mjs
+++ b/tests/agents.test.mjs
@@ -34,13 +34,33 @@ test('a map built under Codex records it, and leaves the project notes alone', (
} finally { cleanup(root); }
});
-test('a map built under Claude Code records it, and keeps the CLAUDE.local.md note', () => {
+test('a map built under Claude Code records it, and adds the CLAUDE.local.md note only when asked', () => {
const root = shopApp();
+ const notes = path.join(root, 'CLAUDE.local.md');
try {
run('scan.mjs', root);
- run('build.mjs', root, '--agent', 'claude');
+ assert.match(run('build.mjs', root, '--agent', 'claude'), /CLAUDE\.LOCAL\.MD {2}not added/);
assert.equal(readGraph(root).meta.agent, 'claude');
- assert.match(fs.readFileSync(path.join(root, 'CLAUDE.local.md'), 'utf8'), /floorplan\/query\.mjs/);
+ assert.ok(!fs.existsSync(notes), 'no CLAUDE.local.md until the user says yes');
+ run('build.mjs', root, '--agent', 'claude', '--claude-md');
+ assert.match(fs.readFileSync(notes, 'utf8'), /floorplan\/query\.mjs/);
+ } finally { cleanup(root); }
+});
+
+test('a CLAUDE.local.md note that already exists is kept current, and the opt-out marker still wins', () => {
+ const root = shopApp();
+ const notes = path.join(root, 'CLAUDE.local.md');
+ try {
+ run('scan.mjs', root);
+ fs.writeFileSync(notes, 'my notes\n\n<!-- floorplan:start -->\nold\n<!-- floorplan:end -->\n');
+ run('build.mjs', root, '--agent', 'claude');
+ const text = fs.readFileSync(notes, 'utf8');
+ assert.match(text, /^my notes/);
+ assert.match(text, /floorplan\/query\.mjs/);
+ assert.doesNotMatch(text, /\nold\n/);
+ fs.writeFileSync(notes, 'my notes\n<!-- floorplan:off -->\n');
+ assert.match(run('build.mjs', root, '--agent', 'claude', '--claude-md'), /CLAUDE\.LOCAL\.MD {2}skipped \(opted out\)/);
+ assert.equal(fs.readFileSync(notes, 'utf8'), 'my notes\n<!-- floorplan:off -->\n');
} finally { cleanup(root); }
});
diff --git a/tests/supply-chain.test.mjs b/tests/supply-chain.test.mjs
index 3d790b2..bd8fb87 100644
--- a/tests/supply-chain.test.mjs
+++ b/tests/supply-chain.test.mjs
@@ -60,10 +60,12 @@ test('nothing to install: no dependencies and no install scripts', () => {
test('the only commands pre-approved are the skill’s own scripts, and that list is fixed', () => {
const front = /^---\n([\s\S]*?)\n---/.exec(read(path.join(SKILL, 'SKILL.md')).replace(/\r\n/g, '\n'))[1];
- assert.equal(/^allowed-tools:\s*(.*)$/m.exec(front)?.[1].trim(), 'Bash(node ${CLAUDE_SKILL_DIR}/scripts/*)', `SKILL.md allowed-tools. ${UPDATE}`);
- // every script there runs without a prompt while the skill is in use, so adding one is a deliberate change
+ // each script runs without a prompt while the skill is in use, so adding one is a deliberate change
+ const SCRIPTS = ['build.mjs', 'describe.mjs', 'open.mjs', 'plan.mjs', 'recent.mjs', 'refresh.mjs', 'scan.mjs', 'status.mjs'];
+ const granted = /^allowed-tools:\n((?: {2}- .*\n?)+)/m.exec(front + '\n')?.[1].trim().split('\n').map((l) => l.replace(/^\s*- /, '').trim());
+ assert.deepEqual(granted, SCRIPTS.map((s) => `Bash(node \${CLAUDE_SKILL_DIR}/scripts/${s} *)`), `SKILL.md allowed-tools: exactly the skill's own scripts. ${UPDATE}`);
const scripts = fs.readdirSync(path.join(SKILL, 'scripts')).filter((n) => !fs.statSync(path.join(SKILL, 'scripts', n)).isDirectory()).sort();
- assert.deepEqual(scripts, ['build.mjs', 'describe.mjs', 'open.mjs', 'plan.mjs', 'recent.mjs', 'refresh.mjs', 'scan.mjs', 'status.mjs'], `scripts/ list. ${UPDATE}`);
+ assert.deepEqual(scripts, SCRIPTS, `scripts/ list. ${UPDATE}`);
});
test('it reaches the internet in one place: the waitlist, only when someone signs up', () => {