See how your app actually fits together. An interactive, plain-English map of your codebase, drawn by Claude or Codex.
JavaScript ai-codingarchitecture-diagramclaudeclaude-codeclaude-code-plugincodebase-visualizationcodexcodex-plugindeveloper-toolsonboardingopenaivibe-coding
Docs: cover Claude Code and Codex throughout
Hayden Smithd1c9de18ba04
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 46edb40..190298f 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -5,8 +5,8 @@ Thanks for helping. Bug reports, ideas and pull requests are all welcome.## Reporting a bug[Open an issue](https://github.com/haydenschmitty/floorplan/issues/new/choose) and include:-- what you asked Claude, and what happened;-- the output Claude showed, especially lines starting with `✗` or `!`;+- what you asked Claude Code or Codex, and what happened;+- the output it showed, especially lines starting with `✗` or `!`;- your project's languages and frameworks, and whether it's one repo or several;- your OS and Node version.diff --git a/README.md b/README.mdindex 36faffa..59ab513 100644--- a/README.md+++ b/README.md@@ -33,11 +33,11 @@ Claude or Codex reads your codebase and draws an interactive map of it. Every paYou built an app, probably with a lot of help from AI, and it works. But ask "what happens when someone checks out?" or "what breaks if I change this?" and the honest answer is *no idea*.-Floorplan gives you the diagram nobody drew. Ask Claude for a floorplan and a few minutes later you have a map you can explore, ask questions on, and keep up to date as you work.+Floorplan gives you the diagram nobody drew. Ask Claude Code or Codex for a floorplan and a few minutes later you have a map you can explore, ask questions on, and keep up to date as you work.- **For builders:** understand the app you made, in your own words, without reading the code.- **For teams:** onboard someone in minutes, from the big picture down to the exact file.-- **For working with Claude:** after every change, see exactly which parts it touched and why.+- **For working with AI:** after every change Claude or Codex makes, see exactly which parts it touched and why.## Features@@ -88,7 +88,7 @@ Finds passwords in code, endpoints anyone can use without signing in, unused fil<td valign="top">**🟢 Recent work**<br>-The cards Claude just changed light up green, each with a note on how the change serves what you asked for.+The cards your AI just changed light up green, each with a note on how the change serves what you asked for.</td><td valign="top">@@ -104,7 +104,7 @@ Plus guided **flows** you can request in plain words, a one-minute **Start here*## See it in action-Want to click around yourself? Open the [live demo](https://haydenschmitty.github.io/floorplan-demo/): the real Brewline map beside a scripted Claude Code conversation.+Want to click around yourself? Open the [live demo](https://haydenschmitty.github.io/floorplan-demo/): the real Brewline map beside a scripted conversation, in Claude Code or Codex.<table><tr>@@ -123,7 +123,7 @@ Want to click around yourself? Open the [live demo](https://haydenschmitty.githu<p><b>Recent work.</b> What you asked for, what changed, and why each change was needed, on one board.</p></td><td valign="top">-<img src="docs/images/health.png" alt="The Health panel listing a secret key written into the code and an endpoint anyone can use, each with Show on map and Fix with Claude">+<img src="docs/images/health.png" alt="The Health panel listing a secret key written into the code and an endpoint anyone can use, each with Show on map and a Fix button"><p><b>Health check.</b> A password left in the code and an endpoint anyone can call, each with a one-click fix prompt.</p></td></tr>@@ -134,16 +134,18 @@ Want to click around yourself? Open the [live demo](https://haydenschmitty.githu</td><td valign="top"><img src="docs/images/flow.png" alt="A guided flow, step 4 of 6, showing the main server emailing the gift code through SendGrid">-<p><b>Guided flows.</b> Watch a request travel through the app step by step, or ask Claude to trace a new one.</p>+<p><b>Guided flows.</b> Watch a request travel through the app step by step, or ask for a new one to be traced.</p></td></tr></table>## Install-You need [Node.js 18+](https://nodejs.org) and either Claude Code or Codex.+You need [Node.js 18+](https://nodejs.org) and either Claude Code or Codex. Floorplan runs on the plan you already have, with no API keys.-**Claude Code** (the desktop app's Code tab or the CLI):+### Claude Code++In the desktop app's Code tab or the CLI:```bashclaude plugin marketplace add haydenschmitty/floorplan@@ -152,7 +154,9 @@ claude plugin install floorplan@floorplanStart a new session and it's ready. Installing the Claude Code CLI is recommended even if you use the desktop app, because it lets the map's Ask bar read your real code. More in [Getting started](docs/getting-started.md).-**Codex** (signed in with ChatGPT). No terminal needed:+### Codex++Signed in with ChatGPT. No terminal needed:1. In the Codex app, open **Plugins** and choose **Add a marketplace**.2. For **Source**, enter `haydenschmitty/floorplan` and click **Add marketplace**.@@ -169,9 +173,11 @@ Start a new chat and ask for a floorplan, or type `$floorplan`. The map's Ask ba## Quick start-1. Open your project in Claude Code. For a frontend and backend in separate repos, open the folder that holds both.+1. Open your project in Claude Code or Codex. For a frontend and backend in separate repos, open the folder that holds both.2. Ask:> Make me a floorplan of this app.++ (In Codex you can also type `$floorplan`.)3. Explore. The map opens on its own, starting with a short tour.When you've done more work, ask:@@ -182,7 +188,7 @@ Only what changed is re-read, and what you just worked on lights up under **Rece### Things to try-| Ask Claude | Ask the map |+| Ask Claude Code or Codex | Ask the map ||---|---|| "Make me a floorplan of this app" | "What happens when someone places an order?" || "Update the floorplan" | "Where do we talk to Stripe?" |@@ -195,13 +201,13 @@ Only what changed is re-read, and what you just worked on lights up under **Rece```mermaidflowchart LRcode["Your codebase<br/>one repo or several"] --> scan["Scan<br/>files, imports, routes, requests"]- scan --> claude["Claude<br/>names the parts, describes every file"]- claude --> build["Build<br/>map, health, screens, recent work"]+ scan --> agent["Claude or Codex<br/>names the parts, describes every file"]+ agent --> build["Build<br/>map, health, screens, recent work"]build --> map["floorplan/index.html<br/>opens in your browser"]map -. "update the floorplan" .-> scan```-Scripts do the mechanical work: finding repos, parsing code in a dozen languages, matching web requests to endpoints, laying out the map. They're plain Node with no dependencies. Claude does the part only a reader can: deciding what the parts of your app *are*, and saying so plainly. Details in [How it works](docs/how-it-works.md).+Scripts do the mechanical work: finding repos, parsing code in a dozen languages, matching web requests to endpoints, laying out the map. They're plain Node with no dependencies. Claude or Codex does the part only a reader can: deciding what the parts of your app *are*, and saying so plainly. Details in [How it works](docs/how-it-works.md).**Languages:** TypeScript, JavaScript, Python, Go, Rust, Java, Kotlin, Scala, plus Vue, Svelte and Astro files, with lighter support for others.<br>**Endpoints:** Express, Koa, Hono, Next.js, Flask, FastAPI, Django, Go's net/http, Gin, Echo and chi, Actix, Axum, Spring.<br>@@ -209,7 +215,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, plus a short section in `CLAUDE.local.md` so future Claude 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. 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 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@@ -226,6 +232,7 @@ More in [Privacy and security](docs/privacy-and-security.md).| | ||---|---|| [Getting started](docs/getting-started.md) | Install, first map, updating, removing |+| [Floorplan in Codex](docs/codex.md) | Installing and using it in Codex || [Using the map](docs/using-the-map.md) | Every button, view, shortcut and menu || [How it works](docs/how-it-works.md) | The pipeline, connection matching, refreshes || [What's in your project](docs/project-files.md) | Every file Floorplan creates, and how to edit it |@@ -238,31 +245,37 @@ More in [Privacy and security](docs/privacy-and-security.md).<details><summary><b>Does my code leave my computer?</b></summary>-Only the way Claude Code always works: Claude reads the files it needs to describe your app, through your own account. The map itself is a local file and its server only listens on your machine. If you choose to open the map in the Claude app instead, Claude uploads the map (names, descriptions and structure, not your source code) to your private claude.ai account, and asks first. The one thing Floorplan itself ever sends is your email, and only if you sign up for the [Floorplan Cloud waitlist](docs/privacy-and-security.md#floorplan-cloud-waitlist).+Only the way Claude Code and Codex always work: the AI reads the files it needs to describe your app, through your own account. The map itself is a local file and its server only listens on your machine. If you choose to open the map in the Claude app instead, Claude uploads the map (names, descriptions and structure, not your source code) to your private claude.ai account, and asks first. The one thing Floorplan itself ever sends is your email, and only if you sign up for the [Floorplan Cloud waitlist](docs/privacy-and-security.md#floorplan-cloud-waitlist).</details><details><summary><b>How long does it take, and what does it cost?</b></summary>-A first map takes a few minutes for a small app and longer for a big one, because Claude describes every file and endpoint. It uses your Claude plan like any other task. Big projects are split across parallel helpers. Updates re-read only what changed, so they're quick and cheap.+A first map takes a few minutes for a small app and longer for a big one, because every file and endpoint gets described. It uses your Claude or ChatGPT plan like any other task. Big projects are split across parallel helpers. Updates re-read only what changed, so they're quick and cheap.</details><details>-<summary><b>Do I need the Claude Code CLI?</b></summary>+<summary><b>Do I need a CLI for the Ask bar?</b></summary>-No. The map works without it. With the CLI, the Ask bar can read your real code to answer questions. Without it, you can ask from the Claude app instead, using the map alone.+No. The map works without one. The Ask bar answers through the Claude Code CLI or Codex, which can read your real code. Codex's desktop app already includes what it needs. With Claude, without the CLI you can ask from the Claude app instead, using the map alone.</details><details><summary><b>Will it change or commit my files?</b></summary>-It only writes its own `floorplan/` folder and 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, a section in `CLAUDE.local.md`), and neither is committed. It never changes your code, your `.gitignore` or your `CLAUDE.md`.</details><details><summary><b>The names it picked aren't how we talk about it. Can I change them?</b></summary>-Yes. Ask Claude ("rename 'Main server' to 'Shop API' on the floorplan"), or edit `floorplan/architecture.json` and `floorplan/descriptions/` yourself. Your edits are kept on every update.+Yes. Just ask ("rename 'Main server' to 'Shop API' on the floorplan"), or edit `floorplan/architecture.json` and `floorplan/descriptions/` yourself. Your edits are kept on every update.+</details>++<details>+<summary><b>Does it work with Codex as well as Claude Code?</b></summary>++Yes. It's the same plugin, the same map and the same Health check. Each app runs it on your own plan: Claude Code on your Claude account, Codex on your ChatGPT sign-in. A map made in one opens fine with the other. See [Floorplan in Codex](docs/codex.md).</details><details>diff --git a/SECURITY.md b/SECURITY.mdindex abe11d5..436db95 100644--- a/SECURITY.md+++ b/SECURITY.md@@ -18,7 +18,7 @@ In scope:- anything that could leak secrets or source code;- anything that writes outside the project's `floorplan/` folder and `CLAUDE.local.md`.-Out of scope: issues in Claude Code itself, which go to [Anthropic](https://www.anthropic.com/responsible-disclosure-policy).+Out of scope: issues in Claude Code itself, which go to [Anthropic](https://www.anthropic.com/responsible-disclosure-policy), and in Codex itself, which go to [OpenAI](https://help.openai.com/en/articles/6653653-how-to-report-security-vulnerabilities-to-openai).## Supported versionsdiff --git a/docs/getting-started.md b/docs/getting-started.mdindex 73bc0e2..77dd33f 100644--- a/docs/getting-started.md+++ b/docs/getting-started.md@@ -2,17 +2,19 @@Prefer to watch? The [walkthrough video](https://youtu.be/NTUUzC7L_NQ) covers installing Floorplan and touring a finished map.-Using Codex? See [Floorplan in Codex](codex.md) for installing; the rest of this guide applies too.+Floorplan works in **Claude Code** and in **Codex**. Making and using a map is the same in both; only installing differs. This guide shows Claude Code, and [Floorplan in Codex](codex.md) has the Codex steps.## What you need-- **Claude Code**: the Code tab in the Claude desktop app, or the Claude Code CLI in a terminal.+- **Claude Code** (the Code tab in the Claude desktop app, or the Claude Code CLI in a terminal), or **Codex** (the app or the CLI, signed in with ChatGPT).- **[Node.js](https://nodejs.org) 18 or newer.** Floorplan's scripts run on it. Check with `node --version`.-- **Recommended: the [Claude Code CLI](https://code.claude.com/docs/en/overview)**, even if you mainly use the desktop app. With it, the map's Ask bar can read your actual code when answering questions.+- **With Claude Code, recommended: the [Claude Code CLI](https://code.claude.com/docs/en/overview)**, even if you mainly use the desktop app. With it, the map's Ask bar can read your actual code when answering questions. Codex needs nothing extra: its app includes what the Ask bar uses.## Install-Run these once, in any terminal:+**In Codex**, open **Plugins → Add a marketplace**, enter `haydenschmitty/floorplan`, and install Floorplan. Details in [Floorplan in Codex](codex.md#install).++**In Claude Code**, run these once, in any terminal:```bashclaude plugin marketplace add haydenschmitty/floorplan@@ -23,11 +25,11 @@ The first command adds this repository as a plugin source. The second installs F**Start a new session** afterwards. Plugins load when a session starts.-> In the desktop app you can also browse plugins with the **+** button next to the prompt box (**Add plugins**, or **Plugins → Browse plugins**). It lists plugins from marketplaces you've already added.+> In the Claude desktop app you can also browse plugins with the **+** button next to the prompt box (**Add plugins**, or **Plugins → Browse plugins**). It lists plugins from marketplaces you've already added.## Make your first map-1. **Open your project.** In the desktop app's Code tab, choose your project's folder in the row under the prompt box before sending your first message. In a terminal, run `claude` from the project folder.+1. **Open your project.** In the Claude desktop app's Code tab, choose your project's folder in the row under the prompt box before sending your first message. In the Codex app, open the project's folder. In a terminal, run `claude` or `codex` from the project folder.If your app is split across several repos (say `web/` and `api/` side by side), open the folder that contains them all. Floorplan maps them together and connects the requests between them.@@ -35,27 +37,27 @@ The first command adds this repository as a plugin source. The second installs F> Make me a floorplan of this app.- You can also pick **floorplan** from the **/** menu, or type `/floorplan:floorplan`.+ In Claude Code you can also pick **floorplan** from the **/** menu, or type `/floorplan:floorplan`. In Codex, type `$floorplan`.-3. **Let Claude work.** This is what happens:+3. **Let it work.** This is what happens:- A scan lists every file, import, endpoint and web request. This takes seconds and costs no tokens.- - Claude reads your READMEs, setup files and entry points, then decides the main parts of your app and what each one is for.- - Claude writes a plain-English name and a one-line description for every file and endpoint. Projects with more than about 150 files are split across parallel helpers.+ - Claude or Codex reads your READMEs, setup files and entry points, then decides the main parts of your app and what each one is for.+ - It writes a plain-English name and a one-line description for every file and endpoint. In Claude Code, projects with more than about 150 files are split across parallel helpers.- The map is built and checked: connections, Health issues and screens.- A small app takes a few minutes, a large one longer. You may be asked to let Claude run Floorplan's scripts (`node …`); allow them.+ A small app takes a few minutes, a large one longer. You may be asked to let it run Floorplan's scripts (`node …`); allow them. Codex also asks to start the map's server outside its sandbox, so the map keeps running and its Ask bar can reach Codex.-4. **Look around.** The map opens by itself, in the desktop app's browser pane or your web browser. A one-minute **Start here** tour runs the first time. Claude's message sums up how your app fits together and points out anything serious the Health check found.+4. **Look around.** The map opens by itself, in the app's browser pane or your web browser. A one-minute **Start here** tour runs the first time. The reply sums up how your app fits together and points out anything serious the Health check found.See [Using the map](using-the-map.md) for everything you can do on it.## Keep it up to date-After you, or Claude, have worked on the code:+After you, or your AI, have worked on the code:> Update the floorplan.-Floorplan re-scans and compares with the last map. Moved files keep their descriptions, deleted ones disappear, and Claude rewrites only what's new or what changed in purpose. A map already open in your browser reloads itself, and the cards that just changed light up green under **Recent work**.+Floorplan re-scans and compares with the last map. Moved files keep their descriptions, deleted ones disappear, and only what's new or what changed in purpose is rewritten. A map already open in your browser reloads itself, and the cards that just changed light up green under **Recent work**.## Open the map yourself@@ -67,7 +69,7 @@ node floorplan/serve.mjsserves it at http://127.0.0.1:4378 with a working Ask bar, or double-click `floorplan/index.html`, where everything works except asking questions.-When Claude opens the map for you, the server runs in the background and stops by itself two hours after you close the last tab. To stop it sooner:+When the map is opened for you, the server runs in the background and stops by itself two hours after you close the last tab. To stop it sooner:```bashnode floorplan/serve.mjs --stop@@ -75,7 +77,9 @@ node floorplan/serve.mjs --stop## Update the plugin-Plugins installed from GitHub don't update automatically unless you turn that on. To get the latest version:+For Codex, see [Update or remove it](codex.md#update-or-remove-it).++In Claude Code, plugins installed from GitHub don't update automatically unless you turn that on. To get the latest version:```bashclaude plugin update floorplan@floorplan@@ -89,4 +93,4 @@ Or turn on automatic updates: in a Claude Code session, run `/plugin`, open **Maclaude plugin uninstall floorplan@floorplan```-Then delete the `floorplan/` folder and the Floorplan section of `CLAUDE.local.md` from any project you used it in.+In Codex, see [Update or remove it](codex.md#update-or-remove-it). Then delete the `floorplan/` folder (and, if you used Claude Code, the Floorplan section of `CLAUDE.local.md`) from any project you used it in.diff --git a/docs/how-it-works.md b/docs/how-it-works.mdindex 4c4916d..210de6e 100644--- a/docs/how-it-works.md+++ b/docs/how-it-works.md@@ -1,15 +1,15 @@# How it works-Floorplan splits the work between scripts and Claude. The scripts do everything mechanical: finding files, parsing code, matching requests to endpoints, laying out the map. They're plain Node.js with no dependencies, and they cost no tokens. Claude does what only a reader of the code can: deciding what the parts of your app *are*, and explaining them plainly.+Floorplan splits the work between scripts and the AI you run it in, Claude Code or Codex. The scripts do everything mechanical: finding files, parsing code, matching requests to endpoints, laying out the map. They're plain Node.js with no dependencies, and they cost no tokens. The AI does what only a reader of the code can: deciding what the parts of your app *are*, and explaining them plainly.```mermaidflowchart TDstatus["status: is there a map already?"] -->|no| scanstatus -->|yes| refresh["refresh: re-scan, carry over what didn't change"]- scan["scan: repos, files, imports, endpoints, requests"] --> arch["Claude writes architecture.json<br/>the parts of the app, outside services, flows, tour"]+ scan["scan: repos, files, imports, endpoints, requests"] --> arch["The AI writes architecture.json<br/>the parts of the app, outside services, flows, tour"]arch --> build["build: assign files, connect everything,<br/>Health, screens, the map"]- build --> describe["Claude names and describes every file and endpoint"]- describe --> recent["Claude marks recent work"]+ build --> describe["The AI names and describes every file and endpoint"]+ describe --> recent["The AI marks recent work"]refresh --> describerecent --> open["open: serve the map and show it"]```@@ -38,11 +38,11 @@ The most useful lines on the map connect a screen's web requests to the server c- small helpers in the same file that add a prefix, like `call('/definitions')`.- **Matches** the two. When a request only spells out part of the address, because the base URL lives in settings, Floorplan learns each client's base path and prefers matches that fit it.-It's pattern matching, not a compiler, so it catches most connections but not all. If an important link is missing, ask Claude to add it to the floorplan, and it will record it as an explicit connection.+It's pattern matching, not a compiler, so it catches most connections but not all. If an important link is missing, ask for it to be added to the floorplan, and it will record it as an explicit connection.-## 3. Claude describes the system+## 3. The AI describes the system-Claude reads the scan summary, READMEs, setup files and entry points, then writes `architecture.json`:+Claude or Codex reads the scan summary, READMEs, setup files and entry points, then writes `architecture.json`:- the main parts of your app, each with a plain summary;- the outside services it really talks to (databases, payment providers, email);@@ -51,24 +51,24 @@ Claude reads the scan summary, READMEs, setup files and entry points, then writeThe build then assigns every file to the deepest part whose patterns match, and reports anything left over.-Next, `describe.mjs` writes a worksheet for each part. A worksheet is a digest of every file and endpoint: what it defines, its doc comments, what it uses and what uses it. Claude fills in a name and description for each. On large projects, the worksheets are split across parallel Claude helpers.+Next, `describe.mjs` writes a worksheet for each part. A worksheet is a digest of every file and endpoint: what it defines, its doc comments, what it uses and what uses it. The AI fills in a name and description for each. On large projects, Claude Code splits the worksheets across parallel helpers.By default everything is written for the app's owner, not an engineer: what each thing does for the business, in everyday words. Ask for a developer-facing map and it switches to technical style.## 4. Build-`build.mjs` validates everything Claude wrote and reports problems by name ("did you mean …"). It then:+`build.mjs` validates everything the AI wrote and reports problems by name ("did you mean …"). It then:-- connects the parts, using imports, matched requests and Claude's explicit connections;+- connects the parts, using imports, matched requests and the AI's explicit connections;- runs the **Health** check;- detects **screens**: Next.js, React Router, Vue, SvelteKit, Remix, Nuxt, Astro, Expo, Angular, TanStack;-- writes `graph.json` and the self-contained `index.html`.+- writes `graph.json` and the self-contained `index.html`, noting whether Claude Code or Codex made it, so the map's Ask bar and fix prompts name the right one.The map lays itself out in your browser with [ELK](https://eclipse.dev/elk/), so the build itself is fast.## 5. Recent work-After every make or update, Claude records what was just worked on in `recent-work.json`. `recent.mjs` lists the facts: what changed since the last map, uncommitted changes, and recent commits, each matched to its card. Claude adds the *why*: what you asked for, and how each change serves it. The previous highlights are replaced every time.+After every make or update, the AI records what was just worked on in `recent-work.json`. `recent.mjs` lists the facts: what changed since the last map, uncommitted changes, and recent commits, each matched to its card. The AI adds the *why*: what you asked for, and how each change serves it. The previous highlights are replaced every time.## 6. Showing it@@ -84,13 +84,18 @@ After every make or update, Claude records what was just worked on in `recent-woIt then:- carries descriptions over to moved and renamed files and endpoints;- drops entries for deleted files;-- flags entries whose signature changed for Claude to review.+- flags entries whose signature changed, for review.-Then it rebuilds. Claude only has to describe what's new or flagged, and check the structure if the change was large. That's why updates are quick.+Then it rebuilds. The AI only has to describe what's new or flagged, and check the structure if the change was large. That's why updates are quick.## Asking questions-With the Claude Code CLI, the map's server runs `claude -p` in your project for each question. That session gets read-only tools only: reading and searching files, and `floorplan/query.mjs`, which looks things up in the map. It answers with text plus the cards to show, so answers can cite real code.+The map's server answers each question with the AI on your computer, in your project:++- **Claude Code:** it runs `claude -p` with read-only tools only: reading and searching files, and `floorplan/query.mjs`, which looks things up in the map.+- **Codex:** it runs `codex exec` in Codex's read-only sandbox, with the same lookups. These runs aren't saved to your Codex history, so a follow-up brings the last few questions and answers along.++It uses whichever made the map, and the other one if that isn't installed. Either way it answers with text plus the cards to show, so answers can cite real code.In the Claude app, the map asks Claude through the app instead, with the same lookups but no access to your source.diff --git a/docs/project-files.md b/docs/project-files.mdindex 6503fd6..dd7e4dd 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 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) a short section in `CLAUDE.local.md`. Neither is committed to git, and nothing else in your project is touched.## The `floorplan/` folder@@ -10,12 +10,12 @@ Floorplan writes to exactly two places in your project: the `floorplan/` folder,| `graph.json` | Everything the map shows, as data | No. Rebuilt every time || `architecture.json` | The parts of your app, outside services, extra connections, flows and the tour | **Yes** || `descriptions/*.json` | The name and description of every file and endpoint, one file per part | **Yes** |-| `recent-work.json` | What was just worked on, and why. Replaced on every update | Rarely. Claude writes it |+| `recent-work.json` | What was just worked on, and why. Replaced on every update | Rarely. The AI writes it || `custom-flows.json` | Flows requested from the map | Only to delete one |-| `serve.mjs` | Serves the map locally and answers questions through the Claude Code CLI | No |-| `query.mjs` | Looks things up in the map from the command line; Claude uses it too | No |+| `serve.mjs` | Serves the map locally and answers questions through the Claude Code CLI or Codex | No |+| `query.mjs` | Looks things up in the map from the command line; Claude and Codex use it too | No || `artifact.html` | A copy for opening in the Claude app, only if you asked for one | No |-| `.cache/` | The scan, Claude's worksheets, the last update's changes, and the running server's address | No. Safe to delete |+| `.cache/` | The scan, the description worksheets, the last update's changes, and the running server's address | No. Safe to delete || `.gitignore` | Keeps this whole folder out of git | No |### Editing names and structure@@ -27,19 +27,21 @@ Your edits to `architecture.json` and `descriptions/` are kept on every update.- pin a note to a file;- add or change flows and the tour.-Or just ask Claude ("rename 'Main server' to 'Shop API' on the floorplan").+Or just ask Claude or Codex ("rename 'Main server' to 'Shop API' on the floorplan").The full format is in [`skills/floorplan/references/schema.md`](../skills/floorplan/references/schema.md), and the style guide for names and descriptions is in [`writing-descriptions.md`](../skills/floorplan/references/writing-descriptions.md).## `CLAUDE.local.md`-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, 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:- creates the file if you don't have one;- only ever rewrites its own section, between `<!-- floorplan:start -->` and `<!-- floorplan:end -->`;- 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`.+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.+## Staying out of git- **`floorplan/`** contains its own `.gitignore` that ignores everything in the folder, including itself. Your `.gitignore` isn't changed, and the folder never appears in `git status`.diff --git a/docs/troubleshooting.md b/docs/troubleshooting.mdindex 9ae5876..9896a68 100644--- a/docs/troubleshooting.md+++ b/docs/troubleshooting.md@@ -25,10 +25,10 @@ If it says Codex isn't signed in, open the Codex app (or run `codex login`) andCodex runs commands in a sandbox, and the map's server needs to keep running and reach the network. Allow the server to run outside the sandbox when Codex asks, or run `node floorplan/serve.mjs` yourself from the project folder.### `node` isn't recognized-Install [Node.js](https://nodejs.org) 18 or newer, then start a new session so Claude Code picks it up.+Install [Node.js](https://nodejs.org) 18 or newer, then start a new session so Claude Code or Codex picks it up.-### Claude keeps asking to run `node` scripts-Floorplan pre-approves its own scripts while it's running, but Claude Code may still ask in some setups. Choose the option to always allow them for this project.+### Claude or Codex keeps asking to run `node` scripts+In Claude Code, Floorplan pre-approves its own scripts while it's running, but it may still ask in some setups. Choose the option to always allow them for this project. Codex asks according to your approval settings; allowing Floorplan's `node` scripts for the project stops the prompts.### The skill doesn't show upPlugins load when a session starts, so start a new one after installing. Check that it's installed and enabled:@@ -39,8 +39,10 @@ claude plugin listPlain requests like "make me a floorplan" work without the slash command. If you do want it, it's `/floorplan:floorplan`.+In Codex, check **Plugins** in the app, or run `codex plugin list`, and start a new chat after installing. To call it by name, type `$floorplan`.+### The map looks out of date-Ask Claude to "update the floorplan". If a tab was already open, it reloads itself once the update finishes.+Ask Claude or Codex to "update the floorplan". If a tab was already open, it reloads itself once the update finishes.### The map is blank, or stuck on "Laying out"Maps made before version 0.1.3 load their layout engine from the internet, so check your connection or any content blocker, or ask Claude to "update the floorplan". Newer maps have everything built in and work offline.@@ -73,4 +75,4 @@ node floorplan/serve.mjs --stopIt also stops by itself two hours after the last tab closes.### Still stuck?-[Open an issue](https://github.com/haydenschmitty/floorplan/issues/new/choose) with what you asked, what happened, and the output Claude showed. Please leave out anything private from your code.+[Open an issue](https://github.com/haydenschmitty/floorplan/issues/new/choose) with what you asked, what happened, whether you used Claude Code or Codex, and the output it showed. Please leave out anything private from your code.diff --git a/docs/using-the-map.md b/docs/using-the-map.mdindex 7947ee6..2dacf25 100644--- a/docs/using-the-map.md+++ b/docs/using-the-map.md@@ -50,10 +50,10 @@ A count of important issues, and a plain-language list of problems the scan foun- files nothing uses;- files over about 1,000 lines, which AI struggles to edit safely.-Each issue has **Show on map**, which highlights the affected files and endpoints with notes, and **Fix with Claude**, which copies a ready-made prompt naming the exact files and lines and the safe fix. It's a quick automatic check, not a security audit.+Each issue has **Show on map**, which highlights the affected files and endpoints with notes, and **Fix with Claude** (or **Fix with Codex**, for a map made in Codex), which copies a ready-made prompt naming the exact files and lines and the safe fix. It's a quick automatic check, not a security audit.### Recent work-Appears when Claude has just changed things. It lays the changed cards out on one board, with what you asked for, a summary of what was done, and a note on every card. Elsewhere on the map, changed cards have a green ring and a **Changed** or **New** tag, and the parts that contain them show **N changed**, so you can follow the green down from the top level.+Appears when Claude or Codex has just changed things. It lays the changed cards out on one board, with what you asked for, a summary of what was done, and a note on every card. Elsewhere on the map, changed cards have a green ring and a **Changed** or **New** tag, and the parts that contain them show **N changed**, so you can follow the green down from the top level.### ScreensEvery page of your app that Floorplan detected. Pick one to see everything behind it: its components, the requests it makes, the server code that answers them, the data they touch, and outside services.@@ -64,7 +64,7 @@ Replays the one-minute tour that runs the first time you open a map.### FlowsGuided walkthroughs of the app's main jobs, like "Checkout" or "Sign up". A flow moves across the board step by step, with a narration at each stop. Use **←** / **→** or the flow bar's buttons to step through, and **Esc** to stop.-**Request a new flow** lets you describe one in plain words ("how does a refund get back to the customer's card?"), and Claude traces it through the code. Flows you request are saved with the map.+**Request a new flow** lets you describe one in plain words ("how does a refund get back to the customer's card?"), and Claude or Codex traces it through the code. Flows you request are saved with the map.### Filters- **Show connections:** turn kinds of lines on or off (Uses, Web requests, Background jobs and so on).@@ -75,10 +75,10 @@ Guided walkthroughs of the app's main jobs, like "Checkout" or "Sign up". A flow<img src="images/ask.png" alt="An answer board with numbered cards and a written walkthrough">-Type into the Ask bar at the bottom and press **Enter**. Claude answers in a few sentences and shows an **answer board**: just the cards involved, how they connect, a short note on each, and a numbered walkthrough when the answer is a sequence. Follow-up suggestions appear under the answer. **Back to map** returns to where you were.+Type into the Ask bar at the bottom and press **Enter**. Claude or Codex answers in a few sentences and shows an **answer board**: just the cards involved, how they connect, a short note on each, and a numbered walkthrough when the answer is a sequence. Follow-up suggestions appear under the answer. **Back to map** returns to where you were.- **Right-click → Ask about this** on any card or line adds it to your question as context.-- The label in the bar shows what's answering. **Claude Code** means the CLI, which can read your source code. **Claude app** means the map was opened in the Claude app, which answers from the map alone.+- The label in the bar shows what's answering. **Claude Code** means the Claude Code CLI and **Codex** means Codex, both running on your computer and able to read your source code. **Claude** means the map was opened in the Claude app, which answers from the map alone.- If neither is available, the bar explains what's needed. See [Troubleshooting](troubleshooting.md).## Right-click menus