Codebase Cartography Support

It reads through a project folder on your computer (the collection of files that makes a piece of software work, also called a codebase) and turns what it finds into three coordinated spreadsheets:

• Project Map: every file and folder, with its type, size, the other code it depends on, its functions, how information flows through it, how complex it is, and more.
• Feature Map: what the code can do, with entries the app fills in for you plus columns for your own notes.
• Content Map: the words people see on screen in your software, such as buttons, labels, headings, and tooltips, and where each one lives in the code.

All three share file paths, each file’s address inside the project, so you can trace a button to the file it comes from, then to the feature it supports. Everything runs on your own computer.

Yes. If you can choose a folder and open a spreadsheet, you can use Codebase Cartography. The default settings work well for most projects, so your first maps take just a few clicks, and the column guide explains every column in plain language.

Experienced developers get plenty of depth too: detailed code measurements for more than 20 programming languages, fine-tuned exclusions, secret detection and redaction, Prompt Tools for AI (Artificial Intelligence) assistants, and Automation for hands-off exports.

People use it in many roles and fields: developers and testers, designers and translators, project managers, teachers and students, agencies and freelancers, and companies in finance, healthcare, retail, and beyond.

1. In Projects, choose Select Folder and pick your project.
2. In Output, choose Export folder and pick where the spreadsheets should be saved.
3. In Generate Maps, choose Export Maps. The app scans, analyzes, and exports all three maps in one go.

Before any files are saved, the Review Before Exporting window sums up what’s about to happen, including whether possible passwords and keys will be hidden (redaction). Confirm to continue.

Tip: the default exclusions already skip clutter such as downloaded code libraries (dependency folders), build output, caches, and binary (non-text) files, so your first run is usually quick. For a large project, take a quick look at Exclusions before exporting.

The main window is a column of sections (sections you can open and close), arranged in the order you usually work:

Projects → Exclusions → Output → Summary → Generate Maps → Results

Select a section’s header to open or close it. Optional sections (Publish, Prompt Tools, and Automation) appear once you turn them on in Settings → Additional Features & Tools.

The title header across the top holds About, Settings, System, Themes, light and dark mode, and Collapse All, which closes every section at once.

Tip: keep only the section you’re using open. Collapse All is a quick way to tidy a busy window.

Deeper analysis covers more than 20 programming languages, including Python, JavaScript, Rust, and C#. For these, the app records function names, import chains (the other code each file brings in), what goes in and comes out, return values (what each function hands back), and state changes (where stored information is modified).

Files in any other format still appear in the Project Map with their type, size, and location, unless an exclusion skips them.

About in the title header explains the three maps and every Project Map column. Several sections, including Exclusions, Publish, Prompt Tools, and Automation, have their own About link with detailed guidance. About windows can be resized or shown full screen.

The EULA (End User License Agreement) and the privacy policy are also available in the app, and you can read the privacy policy online on our Privacy Policy page.

Every session starts here.

• Select Folder opens your computer’s folder picker so you can choose the project to scan.
• Saved projects remember a project’s setup, including its exclusions and output choices. Use Save, Load Project, Delete, and Refresh to manage them.
• Reopen recently used projects from the recent list with Load.

Tip: save a project once you’ve fine-tuned its exclusions and output. Next time, loading it restores the whole setup, and you can export again right away.

Exclusions keep clutter out of your maps. There are several independent controls:

• Ignore common unnecessary paths skips folders and file names such as dependency folders (downloaded code libraries), build output, caches, and generated or minified (compressed) files. Skipping a folder also skips everything inside it.
• Ignore common extensions skips a fixed list of file extensions, the ending after the dot in a file’s name. Important settings and package files, including general JSON (JavaScript Object Notation) files, are protected from this filter.
• Ignore binary files reads the first 1,024 bytes of each file and skips it if that sample contains a null byte, a sign of a non-text file such as an image or a compiled program. This works even if the extension is missing or misleading.
• Select Folders / Files excludes specific folders or files you choose. They’re listed under Excluded Paths, where you can remove them one at a time or with Clear all exclusions.
• File-Types lists every file type found. Select types to exclude them, then choose Update to apply. Select an excluded type to include it again.

Each checkbox has a Details view listing what it matched in the latest scan. Files larger than 20 MB (megabytes) are always skipped.

Tip: turning off a default exclusion requires a full rescan, which can take a while on large folders. Check Skipped / Excluded Files in Summary to confirm nothing important was left out.

Deep Scan (in Exclusions) looks for text that resembles secrets: API (Application Programming Interface) keys, which let a program use an online service, plus access tokens, passwords, database connection strings, private keys, cloud credentials, and similar sign-in details. Results appear in Sensitive Content Detected, grouped by type and rule.

• Redact All (the default) replaces every detected value with a safe placeholder in your exports.
• Include Selected leaves only the types or rules you check visible; everything else stays redacted (hidden).
• Redact None leaves detected values in the export. It’s marked “Not Recommended” and asks you to confirm.

Use Expand All and Collapse Groups to browse findings, and Copy Details or Save Log As to keep a record. If your project changes after a scan, the button changes to Update Sensitive Scan.

Tip: keep Redact All on unless you have a clear reason not to. Detection works by recognizing patterns, so always review exports before sharing them.

• Export folder sets where the spreadsheets are saved.
• Export formats: choose .csv (comma-separated values), .tsv (tab-separated values), or both.
• Project-Map: set the file name, use a suggestion (the project folder’s name or “Project Map”), and optionally add a timestamp, the date and time of the export. Columns explains each column.
• Feature-Map: optionally choose a template that holds your own notes. Auto Select looks for one in the export folder, and Create Template makes a starter file.
• Content-Map: sets the name and formats for the list of on-screen text.

You can also make maps one at a time: Analyze Files, then Generate Feature Map or Generate Content Map, and Export Results or Copy .tsv to clipboard.

Tip: turn on timestamps to keep a history of snapshots you can compare over time. If your export folder is inside the project, add it to Exclusions so earlier maps aren’t mapped in the next scan.

Summary shows totals for Files, Folders, size in MB (megabytes), and File Types, along with:

• File-Types: how many files of each type, sortable by count or A–Z.
• Leaderboard and Data Summary: a quick overview of what the project is made of.
• Skipped / Excluded Files: everything left out and why, with options to show full paths and sort.

Most lists offer Copy Details and Save Log As.

Tip: if the totals look much larger than expected, a dependency or build folder is probably being scanned. Exclude it and update.

Export Maps runs the whole sequence (first scan, deep scan, analysis, then the Project Map, Feature Map, and Content Map), with a progress bar for each stage. Cancel stops the run. When it finishes, Batch Export Results lists the files it saved.

Before saving, the app shows Review Before Exporting with the file count, estimated rows, formats, redaction status, and any secrets it detected. If files with the same names already exist, it asks before overwriting (replacing) them.

Tip: set up Exclusions and Output first. Generate Maps uses whatever those sections currently say.

• Project-Map-Spreadsheet, Feature-Map-Spreadsheet, and Content-Map-Spreadsheet show interactive previews. Select a column to highlight it, and drag its edge to resize it.
• Full-Screen gives wide spreadsheets more room.
• Load Project-Map, Load Feature-Map, and Load Content-Map open spreadsheets you exported earlier.

Turn it on in Settings → Additional Features & Tools → Publish Web Site. It builds a self-contained website from HTML (HyperText Markup Language) pages: one formatted page per source file, plus a clickable index. The site opens in any browser, with no web server needed.

• Choose the Project folder and Export folder.
• Pick a Style preset (including Match Current Theme), then adjust Max line width, Code size, Comment size, bold and italics, and syntax colors (the colors that tell different kinds of code apart).
• Save your settings as a preset with Save New Preset, and manage presets with Update Selected, Rename, and Delete.
• Generate Web Page creates a Codebase-Cartography-html-pages folder. The app asks before replacing an existing one.
• Afterward, use Reveal Output or Copy Index Path.

Tip: for printing or saving a PDF (Portable Document Format) file, set a line width that fits your page. Wrapped lines keep their indentation, so nested code stays readable. Use your browser’s print command to save the PDF.

Turn it on in Settings → Additional Features & Tools. Prompt Tools packages your maps and project knowledge into well-organized prompts, the requests you give an AI assistant, ready to copy into the AI chat in your code editor. It doesn’t contact any AI service itself.

1. Create / Load Profile: copy the Full or Compact profiling prompt, run it in your assistant to create a project profile (a .json file describing your project), then Load profile.
2. Attach Basemaps: load your Project, Feature, and Content Maps. Without maps, prompts switch to discovery mode, where the assistant explores the code first.
3. Prepare Documentation: enter a title and description, choose which sections to include, preview, and copy a prompt that produces a feature document.
4. Develop: load that document as a reference, choose a Prompt Role (Implementation, Strategy / Planning, Documentation, or Verification / QA, short for Quality Assurance), review the safeguards, and copy the prompt.

Tip: use the words a developer would search for in the code as the title, keep your maps up to date when breaking something would be costly, and ask the assistant to report which commands it ran and what it didn’t test.

This optional add-on is an early preview of a repeating prompt workflow. It needs a project that’s a Git checkout (a copy of a project tracked by the Git version-control system) on a named branch, with all changes committed (saved to Git’s history). Several of its stages are placeholders and don’t work yet.

For everyday work, use the standard Prompt Tools section.

Turn it on in Settings → Additional Features & Tools → Automation. Automation lets another program on your computer, running under your own user account, ask Codebase Cartography to run a preset (a saved setup) that you approved. It works through five areas:

1. Preset editor: save the current project and output folder with a label, format (.csv, .tsv, or both), and optional timestamp. Presets export all three maps.
2. Authorization: review the security boundaries and grant the master permission. Revoking it blocks future runs and clears the allowlist, the list of approved presets.
3. Validate: confirm each preset passes the checks, then select Allow this preset. Outside programs use only its fixed ID (identifier) and can’t change its folders or options.
4. Launcher: copy the launch details or download the integration kit, which includes examples and a readiness check that doesn’t export anything.
5. Activity: review recent runs, their results, the files saved, redactions, and how long each took.

Tip: grant authorization only while you need it, and revoke it when you’re done. The Activity list is a best-effort history; the result the calling program receives is the final word.

• Themes (title header) offers 15 preset themes in light and dark modes. Some presets, such as Compass, Mountain Topography, and the Graph Paper variations, have extra Adjustments. Reset returns a preset to its original look.
• Create Custom Theme lets you set a name, text and background colors, a background image (a PNG, JPG, or WEBP file under 5 MB), text size, and panel transparency.
• Settings (title header) controls opening and closing animation speed, click effects, sound effects, and dynamic backgrounds, and contains Additional Features & Tools.

Tip: for long reading sessions, try a dark theme with slower or no animations.

Open System in the title header.

• Display Current Settings shows your settings, with a Copy button.
• Open Console shows the app’s activity log, which is useful when reporting a problem.
• Open Local Data Folder opens the folder where the app keeps its own data on your computer.
• Resets: Clear Project Cache…, Reset Themes & Styles…, Reset Warning Popups, and Reset Intro, plus the consent agreement where it applies.
• Restore Factory Defaults returns the app to how it was when you first opened it. It can’t be undone.

The columns fall into four groups:

• Code logic & structure: features, summary, functions, order of operations, and cyclomatic complexity, a score for how many different paths the code can take.
• Data & state: data flow and state management, state mutation, input sources, output destinations, and return values, which together show how information moves through a file and where it changes.
• Dependencies & environment: imports (other code the file brings in), API usage, and execution context (where the code runs).
• Quality & reliability: side effects, error handling coverage, test coverage, and behaviors.

See Learn about each column for a full, plain-language reference, or open Output → Project-Map → Columns in the app.

The Feature Map combines entries the app generates with columns you fill in yourself, such as Name, Is working?, Needs development?, Description, Category, Context, QA (Quality Assurance) checks, Observations, and Additional notes.

When you generate the Feature Map, the app merges the notes from your template, or from an existing Feature Map you select, with the freshly generated rows. Your notes carry forward, while the generated columns reflect the current code.

Tip: even a quick pass, such as naming your 20 most important features and marking whether they work, makes the map much more useful.

The Content Map lists the text people see on screen (buttons, labels, headings, form fields, dropdown menus, paragraphs, and tooltips), along with the file it comes from, its element type, and its context. Use it to keep wording consistent, plan translations (localization), and check that labels work for everyone, including people who use screen readers and other assistive technology.

Tip: projects with little on-screen text, such as code libraries or back-end services (code that runs out of sight, on a server), naturally produce short Content Maps.

• From a button: find the file it comes from in the Content Map, look that file up in the Project Map for its dependencies and complexity, then find the feature it belongs to.
• From a file: find everything it puts on screen and every feature it helps power.
• From a feature: find the files that build it and the parts of the screen people use to reach it.

Tip: before changing a file, use all three maps together to see what else it touches. It’s a quick way to check the impact of a change.

Export with timestamps turned on so each run is kept as a snapshot. Compare snapshots in your spreadsheet app to spot growing files, rising complexity, new dependencies, changed on-screen text, and features whose status changed.

Tip: export at regular milestones, such as each release, so comparisons stay meaningful.

Both contain the same information. .csv (comma-separated values) is the most widely supported format. .tsv (tab-separated values) separates columns with tabs, which avoids problems when cells contain commas (common in code) and pastes cleanly into Google Sheets, Excel, and Numbers.

Tip: the Copy .tsv buttons put a map on your clipboard, ready to paste straight into an empty spreadsheet.

Give the assistant targeted rows from each map instead of pasting large amounts of raw code. Project Map rows describe structure, Feature Map rows describe behavior, and Content Map rows describe what appears on screen. The assistant gets the context it needs while using fewer tokens, the small chunks of text AI tools read and often charge by. Prompt Tools can package all of this for you.

Tip: treat map rows as leads, not proof. Ask the assistant to confirm files and names in the live code before it makes changes.

No. Scanning, analysis, and export all happen on your computer, and the app has no telemetry (automatic usage reporting), analytics, or cloud processing. See the Privacy Policy for details.

Secret detection works by recognizing known patterns. It’s a safety net, not a guarantee: it can miss custom or unusual secrets, and it can flag example values or test data (sometimes called test fixtures). It never contacts outside services to test whether a key works.

Keep Redact All on, and review the Summary section before exporting. If a common credential format isn’t detected, tell us its general shape, but never send the real value.

• Make sure you have permission to share information about the project.
• Check that redaction was turned on in the export review.
• Look for internal names, server addresses (hostnames), customer data in test files, and business-sensitive comments. Redaction targets passwords and keys, not everything confidential.
• Remember that file names and a project’s folder structure can be sensitive on their own.

In the export folder you chose in Output (or in Publish, for web pages). The app doesn’t upload them anywhere. After an export, use Show in Finder (Mac) or Show in Explorer (Windows) to open the folder.

• System → Resets → Clear Project Cache… removes saved presets, recent folders, exclusions, cached scan results, saved folder access, and Automation authorization. Themes and other preferences are kept.
• Reset Themes & Styles… deletes custom themes, interface styles, Publish presets, and syntax colors, then reloads the app.
• Restore Factory Defaults returns everything to how it was when you first opened the app.

None of these delete maps or web pages you exported.

On macOS, Codebase Cartography can open only the folders you choose with the system file picker. This is part of Apple’s App Sandbox, which keeps apps away from files you haven’t shared with them. The app remembers each choice, so recent projects, export folders, and templates reopen without asking again.

If a folder has been renamed, moved, or deleted, or is on a drive that isn’t connected, macOS may no longer allow access to it. Choose the folder again with Select Folder, and the app will remember the new location. Clearing the project cache also removes remembered folder access.

• Keep the three default exclusions (paths, extensions, and binary files) turned on.
• Exclude large generated folders, vendored code (copies of other people’s code stored inside your project), datasets, and media with Select Folders / Files.
• Check the totals in Summary. If they’re far larger than expected, something big is being scanned.
• You can always Cancel a run and adjust the exclusions.

Open Summary → Skipped / Excluded Files and turn on Show full path. Common reasons are:

• it’s inside a folder matched by Ignore common unnecessary paths, or listed in Excluded Paths;
• its file type is excluded in File-Types or by Ignore common extensions;
• it was detected as binary, meaning not text (it contains a null byte near the start);
• it’s larger than 20 MB;
• it has a sensitive file name, such as an environment or credentials file that often holds passwords, and was skipped automatically.

The Feature Map is built from analysis results. Run Analyze Files (or use Export Maps, which does it for you) before generating it.

A short Content Map is normal for projects with little on-screen text. Check that the folders holding your interface code aren’t excluded.

Exports need both a project and a destination. Choose Select Folder in Projects and Export folder in Output, and make sure at least one format (.csv or .tsv) is selected.

Publish has its own Project folder and Export folder settings.

An earlier export with the same name is already in that folder. Choose Overwrite Files to replace it, or choose Cancel and turn on the timestamp option in Output so each export gets its own name.

Some spreadsheet apps guess the wrong settings when you double-click a file. Instead, use the app’s import command (in Excel, Data → From Text/CSV), then choose UTF-8 encoding (the standard way of storing text characters) and the matching delimiter, the character that separates columns: a comma for .csv or a tab for .tsv. Or use a .tsv export, or paste from Copy .tsv.

Open System → Resets → Reset Warning Popups. All warnings will appear again.

Try another preset in Themes, or switch between light and dark mode. If a customized theme is the cause, Reset that preset, or use System → Resets → Reset Themes & Styles… to restore every appearance setting.

Email studio@codebasecartography.com with:

• the app version and where you got it (Mac App Store, Microsoft Store, or direct download);
• your operating system and its version, for example macOS 15 or Windows 11;
• what you did, what you expected, and what happened instead;
• any error message, copied exactly, or a screenshot.

System → Open Console and Display Current Settings can provide useful details. Review anything you copy first, because it may include folder paths. Please don’t send source code, passwords or keys, or exported maps unless we ask. If a sample would help, make a small test project that contains no secrets or private code.

• Mac: macOS 10.15 Catalina or later, on Apple silicon or Intel.
• Windows: available from the Microsoft Store.

For Mac App Store purchases, use Apple’s Report a Problem page. For Microsoft Store purchases, see your Microsoft account order history. We can’t issue refunds for store purchases ourselves.

Updates come from the store you installed from. Check for updates in the Mac App Store or the Microsoft Store.