Floorplan Explained: Map Your Codebase With Claude or Codex

Floorplan is a free, open source plugin for Claude Code and Codex that reads your codebase and draws an interactive, plain-English map of it. Every file, API route, and screen gets a one-line description in normal words instead of class names, and you can click through the map to see exactly how data moves between them. It shipped its first release on October 27, 2026, and as of this week it's already at version 0.6.1, with six releases in six days and a health check feature that flags exposed secrets and wide-open endpoints.

That's the short version. Here's what it actually does, how to install it in Claude Code or Codex, and whether it's worth the five minutes it takes to try.

What problem is Floorplan actually solving?

You inherit a repo, or you come back to your own project after three months, and you can't answer a simple question: what happens when a user clicks "place order"? Grepping for checkout gets you fifteen files and no story. Floorplan's whole pitch is that an AI agent that already has to read your code to work on it should also be able to narrate the architecture back to you, instead of making you reconstruct it file by file.

It's built by a developer going by Hayden Smith (GitHub handle haydenschmitty), it's MIT licensed, and it's had a genuinely fast start: it crossed 1,800 GitHub stars and well over 100 forks inside its first week, which is the kind of growth curve that gets a repo onto GitHub's trending page. I'm not going to pretend a star count proves quality, but it does mean a lot of people are finding the pitch believable enough to try it on their own code.

How do you install Floorplan in Claude Code?

Floorplan ships as a Claude Code plugin, so there's no npm install or config file to hand-edit. Two commands inside Claude Code:

claude plugin marketplace add haydenschmitty/floorplan
claude plugin install floorplan@floorplan

You'll need Node.js 18 or newer on your machine and an active Claude Code setup. No separate API key, and that part matters more than it sounds: Floorplan rides on your existing Claude subscription instead of billing you separately per token, which is worth knowing if you're already watching your usage limits closely.

How do you install it in Codex?

Same idea, different CLI:

codex plugin marketplace add haydenschmitty/floorplan
codex plugin add floorplan@floorplan

If you'd rather click than type, the Codex app has a Plugins screen too. Open it, choose "Add a Marketplace," and paste in haydenschmitty/floorplan as the source, then install from there.

How do you generate your first map?

Open your project in Claude Code or Codex and just ask for it in plain language:

• "Make me a floorplan of this app"

That's it. The agent scans your files, imports, routes, and requests, names and describes every part in plain English, builds the map data, and opens it in your browser. On a mid-sized app this takes a few minutes, not seconds, because the AI is actually reading and summarizing files rather than running a static regex pass.

Once you have a map, keep it current with:

• "Update the floorplan": this only rescans files that changed, so it's noticeably cheaper than the first run

And if you haven't written a line of code yet:

• "Here's my PRD. Make me a floorplan of what we'd need to build": this is blueprint mode, and it draws dashed cards for components that don't exist yet, which is a genuinely clever way to sanity-check a spec before anyone opens an editor

What does the map actually show you?

The output is a zoomable node graph, from the whole application down to a single file or endpoint. A few specifics worth knowing:

• Plain-English names and one-line descriptions for every subsystem, file, and HTTP route — no more guessing what utils/helpers2.ts does
• Real connections, not guesses — it matches frontend fetch calls to actual backend routes, and it resolves Express router prefixes and Flask blueprint mounts, including nested ones
• Multi-repo support — if your frontend and backend live in separate repos, or you're in a monorepo, it stitches the connections across the folder boundary
• Recent work tracking — after your agent makes a change, the map highlights exactly which parts were touched and why
• Query support — you can ask the map things like "what happens when someone places an order?" or "where do we talk to Stripe?" or "if I change the users table, what breaks?" and it traces the actual flow instead of giving you a generic answer

Supported languages and frameworks cover a lot of ground: TypeScript, JavaScript, Python, Go, Rust, and Java on the backend side, with first-class handling for Express, Flask, FastAPI, Django, Spring, and Firebase Functions, plus the major frontend frameworks.

What does the health check catch?

Version 0.6.0, shipped October 31, added a health check pass that's really just a security linter dressed up in map form. It looks for:

• Secret keys and passwords hardcoded or exposed to the browser
• Endpoints anyone can hit without authentication
• Insecure Supabase table permissions and loose Firebase rules
• Stripe webhooks that can be faked because signature verification is missing
• Overly permissive CORS configuration
• Unused files and files that have grown too large to reasonably maintain

Each flagged issue comes with a ready-made fix prompt, so you're not left guessing what to paste into your agent. The very next release, 0.6.1 on November 1, added the ability to mark a flagged issue "not a problem" with a reason, plus a one-click way to report false alarms back to the project on GitHub. That's a fast turnaround for a feature that's one day old, and it tells you the health check was flagging things that weren't actually broken often enough that people complained.

What's inside the floorplan/ folder?

Running Floorplan creates a floorplan/ directory holding the interactive HTML map, an architecture.json file, and the description text for each part. None of it gets committed to git by default, and your source code is never modified. If you say yes when asked, Claude Code will also add a short reference section to CLAUDE.local.md so future sessions know the map exists. That step used to happen automatically but became opt-in as of version 0.4.4, after people (reasonably) objected to an uninstalled tool silently editing their config files.

Is this safe to run on a codebase with real secrets in it?

This is the question I'd want answered before pointing any tool at a production repo. Here's what Floorplan actually does, based on the project's own documentation:

• All the mechanical parsing (finding imports, routes, file sizes) happens locally with zero dependencies — no network calls for that part
• The AI reading and describing your files goes through your own Claude or Codex account, the same way it would if you asked it to review a pull request
• The local map server was locked down in version 0.3.2 to only answer requests from your own machine, not your network
• Secret values themselves are never stored in the map or displayed — the health check flags that a key is exposed, not the key's contents

None of that makes it bulletproof, and I'd still avoid running any new plugin on a repo I didn't trust in the first place. But the design is sound: it doesn't introduce a new place for your secrets to leak, it just points a camera at the leaks you already have.

How has Floorplan changed since launch?

It's shipped something almost every day since the first release. Here's the shape of it:

That's a lot of shipping for five days. The upside is you can tell the maintainer is actually using feedback. The downside, and I'd flag this honestly, is that a tool moving this fast is also a tool where today's behavior might not match next week's. If you're the type who wants a plugin to sit still for a quarter before you trust it, give this one a little more runway.

How does Floorplan compare to other codebase-mapping tools?

It's not the only agent-assisted way to understand a codebase. If you've looked at REA or compared it against LeanREA, you already know this category is getting crowded fast. The rough distinction, per Floorplan's own docs: diagram-first tools like Archify give you a static architecture chart, and function-level tools like Understand Anything build a knowledge graph down to individual functions. Floorplan sits in between — it cares about application-level understanding ("this screen calls this endpoint which hits this table") more than either extreme, and it's explicitly built to answer plain-English questions rather than just render a pretty graph.

If you're already deep into the Claude Code skills ecosystem, this fits the same pattern Theo's T-Stack skills post covered: small, focused plugins that do one job well instead of one mega-tool trying to do everything.

Should you actually use it?

I'd say yes, with a caveat. On a small-to-medium app, "Make me a floorplan of this app" is genuinely one of the better five-minute investments you can make before handing a codebase to a new teammate, or before you yourself dive back into old code. The query feature, asking the map what breaks if you touch a table, is more useful in practice than it sounds on paper.

The caveat: it's six days old at the version I'm testing against, the health check is one day past its first false-alarm fix, and nobody's run this against a truly massive monorepo long enough to know where it falls over. Try it on a side project first. Don't make it your only source of truth for a system you're about to refactor in production.

FAQ

Does Floorplan cost anything on top of my Claude Code or Codex subscription?

No. Floorplan doesn't require its own API key: it uses your existing Claude Code or Codex account to do the reading and describing, so you're billed through your normal plan, not a second one. If you're tracking how close you are to your usage limits, updating the floorplan is cheaper than the first full scan since it only rereads changed files.

Does Floorplan send my source code anywhere?

No. The mechanical scanning runs locally with no dependencies, the map server only accepts connections from your own machine, and the only thing that reads your files is the AI model through your own Claude or Codex account, the same access it already has to work on your code.

What languages and frameworks does Floorplan support?

TypeScript, JavaScript, Python, Go, Rust, and Java, with specific framework handling for Express, Flask, FastAPI, Django, Spring, and Firebase Functions, plus the major frontend frameworks on the client side.

Can Floorplan map an app that doesn't exist yet?

Yes, that's blueprint mode. Give it a PRD or spec and ask "make me a floorplan of what we'd need to build," and it draws the planned architecture with dashed cards marking components that haven't been built yet, which is useful for catching scope gaps before anyone writes code.

Does the floorplan folder get committed to git?

No. It writes a local floorplan/ folder holding the HTML map and architecture data, and optionally a short note in CLAUDE.local.md if you approve it, but neither is committed and your actual source files are never touched.

How do I keep the map up to date as I keep coding?

Just ask "update the floorplan." It rescans only the files that changed since the last build instead of redoing the whole app, so updates are faster and cheaper than the initial scan.

What people are saying