Skip to content

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

Server: keep the agents that answer in one table

Hayden Smith1fc867bffa69
diff --git a/docs/development.md b/docs/development.md
index ad09cc8..01ab752 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -104,6 +104,14 @@ Files in `skills/floorplan/assets/ui/` are inlined into every map, in name order
`20-health.js` and `25-recent.js` are good examples.
+## Adding an agent
+
+There are two lists, and an agent can be on one or both:
+- **The agent that built the map**, in `scripts/lib/agent.mjs`: an entry in `DETECT` that recognises it from the variables it sets for every command it runs. The map records it, so its prompts name the right agent.
+- **The agent that answers questions**, in `assets/serve.mjs`: an entry in `ENGINES` with its name, where to get it, `find` (where its CLI lives, plus a `--<name> <path>` override) and `run` (the arguments and how to read its output into progress and an answer).
+
+An engine must be read-only in a way its CLI enforces, not only because the prompt asks; if it can't be, say so plainly in the docs. Set `structured: true` only when the CLI holds answers to the schema, because changing a blueprint from the map relies on it; without it, the map doesn't offer Change. Never take the command to run from the page or from saved settings. Add a stand-in CLI to `tests/fixtures/fake-cli/` and tests like `ask.test.mjs`.
+
## Guidelines
- **No dependencies.** The scripts must run anywhere Node 18+ does, with nothing to install.
diff --git a/skills/floorplan/assets/serve.mjs b/skills/floorplan/assets/serve.mjs
index 741ff23..4738157 100644
--- a/skills/floorplan/assets/serve.mjs
+++ b/skills/floorplan/assets/serve.mjs
@@ -78,22 +78,34 @@ function codexApp() {
.sort((a, b) => fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs);
} catch { return []; }
}
+// The agents that can answer, one entry each: what it's called, where to get it, how to find its CLI, how to
+// run one request (run, below), and whether its answers are held to a schema (structured). Changing a
+// blueprint from the map needs that, so Change is offered only with a structured engine. schemaFile: the
+// CLI reads its schema from a file rather than the command line.
const ENGINES = {
- claude: () => resolveCli(given('claude') || [
- ...which('claude'),
- path.join(HOME, '.local', 'bin', process.platform === 'win32' ? 'claude.exe' : 'claude'),
- ...(process.platform === 'win32' ? [path.join(process.env.APPDATA || '', 'npm', 'claude.cmd')] : []),
- ], ['@anthropic-ai', 'claude-code', 'cli.js']),
- codex: () => resolveCli(given('codex') || [...which('codex'), ...codexApp()], ['@openai', 'codex', 'bin', 'codex.js']),
+ claude: {
+ name: 'Claude Code CLI', site: 'https://docs.claude.com/en/docs/claude-code', structured: true,
+ find: () => resolveCli(given('claude') || [
+ ...which('claude'),
+ path.join(HOME, '.local', 'bin', process.platform === 'win32' ? 'claude.exe' : 'claude'),
+ ...(process.platform === 'win32' ? [path.join(process.env.APPDATA || '', 'npm', 'claude.cmd')] : []),
+ ], ['@anthropic-ai', 'claude-code', 'cli.js']),
+ run: claudeRun,
+ },
+ codex: {
+ name: 'Codex', site: 'https://developers.openai.com/codex', structured: true, schemaFile: true,
+ find: () => resolveCli(given('codex') || [...which('codex'), ...codexApp()], ['@openai', 'codex', 'bin', 'codex.js']),
+ run: codexRun,
+ },
};
-// --engine (or FLOORPLAN_ENGINE) decides; otherwise the agent that built the map, then the other one
+// --engine (or FLOORPLAN_ENGINE) decides; otherwise the agent that built the map, then the others in order
const builtBy = (() => { try { return JSON.parse(fs.readFileSync(path.join(here, 'graph.json'), 'utf8')).meta?.agent; } catch { return null; } })();
const asked = opt('engine', process.env.FLOORPLAN_ENGINE);
const isEngine = (k) => typeof k === 'string' && Object.hasOwn(ENGINES, k);
const want = isEngine(asked) ? asked : isEngine(builtBy) ? builtBy : 'claude';
let engine = null, cli = null;
-for (const k of isEngine(asked) ? [asked] : [want, ...Object.keys(ENGINES).filter((k) => k !== want)]) { cli = ENGINES[k](); if (cli) { engine = k; break; } }
-const NAME = { claude: 'Claude Code CLI', codex: 'Codex' };
+for (const k of isEngine(asked) ? [asked] : [want, ...Object.keys(ENGINES).filter((k) => k !== want)]) { cli = ENGINES[k].find(); if (cli) { engine = k; break; } }
+const canChange = !engine || ENGINES[engine].structured;
// Started from inside a Claude Code or Codex session? Don't let the CLI think it's nested in it.
function cliEnv() {
const env = { ...process.env };
@@ -105,7 +117,7 @@ if (cli) { try { version = execFileSync(cli.cmd, [...cli.args, '--version'], { e
// The page, the graph, and the instructions and answer schema (from query.mjs's inlined graph-query
// code). Loaded at start and again whenever the map is rebuilt.
-const inject = `<script>window.FLOORPLAN_SERVER=${JSON.stringify({ token, cli: !!cli, engine, want, version, model: model || null })};</script>`;
+const inject = `<script>window.FLOORPLAN_SERVER=${JSON.stringify({ token, cli: !!cli, engine, want, version, model: model || null, change: canChange })};</script>`;
let page, G, core, MODES;
function load() {
const html = fs.readFileSync(path.join(here, 'index.html'), 'utf8');
@@ -120,9 +132,9 @@ function load() {
MODES = {
ask: { instructions: core.floorplanAskInstructions(G, 'cli'), schema: core.FLOORPLAN_ANSWER_SCHEMA, file: path.join(here, '.cache', 'answer-schema.json') },
flow: { instructions: core.floorplanFlowInstructions(G, 'cli'), schema: core.FLOORPLAN_FLOW_SCHEMA, file: path.join(here, '.cache', 'flow-schema.json') },
- ...(G.meta?.blueprint ? { change: { instructions: core.floorplanChangeInstructions(G), schema: core.FLOORPLAN_CHANGE_SCHEMA, file: path.join(here, '.cache', 'change-schema.json') } } : {}),
+ ...(G.meta?.blueprint && canChange ? { change: { instructions: core.floorplanChangeInstructions(G), schema: core.FLOORPLAN_CHANGE_SCHEMA, file: path.join(here, '.cache', 'change-schema.json') } } : {}),
};
- if (engine === 'codex') {
+ if (ENGINES[engine]?.schemaFile) {
fs.mkdirSync(path.join(here, '.cache'), { recursive: true });
for (const m of Object.values(MODES)) fs.writeFileSync(m.file, JSON.stringify(strict(m.schema)));
}
@@ -292,7 +304,7 @@ const CLOSED = Symbol('closed'); // the browser went away mid-request
/** Runs the agent once for a request and resolves with its answer, streaming progress through `send`. */
function runAgent(res, send, body) {
return new Promise((resolve, reject) => {
- const run = (engine === 'codex' ? codexRun : claudeRun)(body, MODES[body.mode] || MODES.ask);
+ const run = ENGINES[engine].run(body, MODES[body.mode] || MODES.ask);
const child = spawn(cli.cmd, run.args, { cwd: root, env: cliEnv(), stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true });
const id = crypto.randomBytes(6).toString('hex');
running.set(id, child);
@@ -333,7 +345,7 @@ function runAgent(res, send, body) {
function ask(req, res, body) {
res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-store', Connection: 'keep-alive' });
const send = (event, data) => { if (!res.writableEnded) res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`); };
- if (!cli) { send('failure', { code: 'cli_missing', message: `${NAME[want]} not found.` }); return res.end(); }
+ if (!cli) { send('failure', { code: 'cli_missing', message: `${ENGINES[want].name} not found.` }); return res.end(); }
if (body.mode === 'change') return changePlan(res, send, body);
runAgent(res, send, body)
.then((a) => send('answer', a), (e) => { if (e !== CLOSED) send('failure', { code: failCode(e.message), message: e.message }); })
@@ -406,7 +418,7 @@ function applyChange(data, request, lastTry) {
}
async function changePlan(res, send, body) {
const request = String(body.question || '').slice(0, 4000);
- if (!MODES.change) { send('failure', { code: 'cli_error', message: 'Only a blueprint can be changed from the map.' }); return res.end(); }
+ if (!MODES.change) { send('failure', { code: 'cli_error', message: G.meta?.blueprint ? `${ENGINES[engine].name} can't change a plan from the map.` : 'Only a blueprint can be changed from the map.' }); return res.end(); }
if (changing) { send('failure', { code: 'busy', message: 'Another change to this plan is still being made. Try again when it’s done.' }); return res.end(); }
changing = true;
let session, errors = null;
@@ -536,8 +548,8 @@ server.on('listening', () => {
for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.on(sig, () => process.exit(0));
console.log(`Floorplan: ${u}`);
console.log(cli
- ? `asking via ${NAME[engine]} ${version || ''} (${cli.path})${model ? `, model ${model}` : ''}`
- : `${NAME[want]} not found: the map works, but asking questions needs it (${want === 'codex' ? 'https://developers.openai.com/codex' : 'https://docs.claude.com/en/docs/claude-code'}). Pass --${want} <path> if it is installed somewhere unusual.`);
+ ? `asking via ${ENGINES[engine].name} ${version || ''} (${cli.path})${model ? `, model ${model}` : ''}`
+ : `${ENGINES[want].name} not found: the map works, but asking questions needs it (${ENGINES[want].site}). Pass --${want} <path> if it is installed somewhere unusual.`);
if (!has('no-open')) {
const opener = process.platform === 'win32' ? ['cmd', ['/c', 'start', '', u]] : process.platform === 'darwin' ? ['open', [u]] : ['xdg-open', [u]];
try { spawn(opener[0], opener[1], { stdio: 'ignore', detached: true }).unref(); } catch {}
diff --git a/skills/floorplan/assets/viewer.html b/skills/floorplan/assets/viewer.html
index 82fc819..0e56be4 100644
--- a/skills/floorplan/assets/viewer.html
+++ b/skills/floorplan/assets/viewer.html
@@ -1860,7 +1860,8 @@ function cancelAsk() {
// updated plan and redraws the map, every open tab reloads, and the new and changed cards are highlighted
// as recent work. What changed is kept across that reload in sessionStorage, with an Undo.
const CHANGE_KEY = 'floorplan-change';
-const canChange = () => PLAN && askState.engine === 'cli';
+// a server whose engine can't be held to the plan's format says change: false
+const canChange = () => PLAN && askState.engine === 'cli' && window.FLOORPLAN_SERVER?.change !== false;
function setAskMode(m) {
askState.mode = canChange() && m === 'change' ? 'change' : 'ask';
$('#ask-mode')?.querySelectorAll('button').forEach((b) => { b.classList.toggle('on', b.dataset.m === askState.mode); b.setAttribute('aria-pressed', String(b.dataset.m === askState.mode)); });
diff --git a/skills/floorplan/scripts/lib/agent.mjs b/skills/floorplan/scripts/lib/agent.mjs
index 404f0dc..6b0955b 100644
--- a/skills/floorplan/scripts/lib/agent.mjs
+++ b/skills/floorplan/scripts/lib/agent.mjs
@@ -1,11 +1,15 @@
// Which coding agent is running the skill: Claude Code or Codex. The map records it, so its Ask bar and
// "Fix with …" prompts name the right one, and serve.mjs answers through the same CLI.
-// --agent claude|codex (or FLOORPLAN_AGENT) decides; otherwise Codex is recognised by the variables it
-// sets for every command it runs, and anything else is taken to be Claude Code.
-export const AGENTS = ['claude', 'codex'];
+// --agent <name> (or FLOORPLAN_AGENT) decides; otherwise each agent is recognised by the variables it sets
+// for every command it runs, and anything else is taken to be Claude Code. Adding an agent is an entry here.
+const DETECT = {
+ claude: () => false, // the default
+ codex: (env) => !!(env.CODEX_THREAD_ID || env.CODEX_SESSION_ID),
+};
+export const AGENTS = Object.keys(DETECT);
export function detectAgent(args = {}, env = process.env) {
const v = String(args.agent || env.FLOORPLAN_AGENT || '').toLowerCase();
if (AGENTS.includes(v)) return v;
- return env.CODEX_THREAD_ID || env.CODEX_SESSION_ID ? 'codex' : 'claude';
+ return AGENTS.find((a) => DETECT[a](env)) || 'claude';
}
diff --git a/tests/blueprint-change.test.mjs b/tests/blueprint-change.test.mjs
index 9f1a6fe..df5ae86 100644
--- a/tests/blueprint-change.test.mjs
+++ b/tests/blueprint-change.test.mjs
@@ -39,7 +39,10 @@ async function served(replies, root) {
server.stdout.on('data', (d) => { out += d; const m = /Floorplan: (http:\/\/\S+)/.exec(out); if (m) { clearTimeout(timer); resolve(m[1]); } });
server.on('exit', (code) => reject(new Error(`server exited (${code}): ${out}`)));
});
- const token = JSON.parse(/window\.FLOORPLAN_SERVER=(\{.*?\});/.exec(await (await fetch(base + '/')).text())[1]).token;
+ const page = JSON.parse(/window\.FLOORPLAN_SERVER=(\{.*?\});/.exec(await (await fetch(base + '/')).text())[1]);
+ const token = page.token;
+ // the stand-in is Claude Code, which holds its answers to a schema, so the map offers Change
+ assert.equal(page.change, true);
const post = (p, body) => fetch(base + p, { method: 'POST', headers: { 'content-type': 'application/json', 'x-floorplan-token': token }, body: JSON.stringify(body || {}) });
return {
root,