What Does a Codebase Triage Actually Look Like? A Real Walkthrough

"Codebase triage" sounds like a process. A methodology. Something that takes weeks and produces a document nobody reads. That's not what Ghost Architect does. This post walks through exactly what happens when you run a scan — from the terminal command to the output you hand to a client or developer — so you know what you're getting before you try it yourself.

---

Step 1: Install and Point

Ghost Architect is a CLI tool. Installation is a single npm command. Once it's installed globally, you run it from your terminal and it walks you through a short setup — your Anthropic API key, what you want to scan, and a few configuration choices about depth and output format.

You select your source — local folder, remote repo, or ZIP. If it's a private repo, you enter a personal access token. Ghost clones it locally, runs the scan, and removes the clone when it's done. Your code never touches any external server.

Step 2: The Analysis Plan

Before the scan runs, Ghost prints an analysis plan. This shows you how many files it found, how it's grouping them for analysis, how many passes it will make, and the estimated time and API cost. You can review this before committing to the scan.

The cost estimate is real and specific to your codebase. Ghost calculates it based on file count, size distribution, and the number of passes required. You confirm before anything runs. There are no surprise charges.

Step 3: The Scan Runs

Once confirmed, Ghost begins the scan. It works through the codebase in passes — a prioritization pass first to identify the highest-risk files, then deeper analysis passes on those files, then a cross-reference pass that looks at how components relate to each other. You see real-time progress in the terminal.

Step 4: The Output — Three Files, Three Audiences

Every Ghost Architect scan produces three output files simultaneously. They contain the same findings, structured differently for different audiences. You don't pick one — you get all three.

// The PDF — For Stakeholders and Clients

The PDF is designed to be handed directly to a non-technical stakeholder or a client. It opens with an executive summary — total findings by severity, a plain-language summary of the highest-risk items, and a recommended prioritization. It's not a raw dump of technical findings. It's a structured document that explains what was found, why it matters in business terms, and what the general remediation path looks like.

The PDF is branded and clean. You can put your agency logo on it, hand it to a client in a meeting, and walk through it finding by finding. It's a deliverable, not a log file.

// The TXT — For Developers

The TXT file is optimized for developers. It's structured for readability in a terminal or text editor and includes the full technical detail for each finding — specific file paths, line references, code patterns that triggered the finding, and concrete remediation guidance. A developer can open this file, find their assigned findings, and start work immediately without needing to ask for clarification.

The TXT is also optimized for AI-assisted development. If you're using Claude Code, Cursor, or another coding agent to work on the findings, you can feed the TXT directly into the agent's context. The structured format gives the agent the specific information it needs to make targeted, accurate changes rather than operating on broad instructions.

// The MD — For the Team

The Markdown file is designed to be committed to a repository, dropped into a project wiki, or pasted into a project management system. It renders cleanly in GitHub, GitLab, Notion, and Linear. Each finding becomes a structured section that can be linked to a ticket, assigned to a developer, and marked complete as the work is done. The MD file is your living record of the triage pass — it's how the findings move from the scan into the team's workflow.

What a Critical Finding Actually Looks Like

People often ask what "Critical" means in practice. Here's a real example from the Meta extension scan to make it concrete.

That's the level of specificity you get for every Critical and High finding. Not "there may be a credential issue somewhere" — a specific file, a specific pattern, a specific business impact, and a specific remediation path with an effort estimate you can put in a proposal.

How an Agency Uses It the Same Day

The practical workflow for an agency that runs a Ghost Architect scan on a new client codebase looks like this:

Morning: Kickoff call with the client. You've already run the scan on the repo they shared access to. You open the PDF.

In the meeting: You walk through the executive summary. You show the client their Critical and High findings in plain language. You explain the business impact of the top three findings. You have an honest conversation about what needs to be addressed before any new development work begins, versus what can be addressed in a later phase. The client can see you've done real work on their codebase before the meeting started.

After the meeting: You send the PDF as the formal deliverable from the kickoff. The TXT file goes to the lead developer with the Critical findings highlighted. The MD file goes into the project wiki as the baseline triage record.

End of day: Development work starts with a clear, shared understanding of what's in the codebase. No surprises in week three. No "we found this integration we didn't know about" conversations mid-project. The map is already drawn.

Running It Yourself

The best way to understand what a triage pass produces is to run one on a codebase you know. Pick a project you've been working on, or use the Meta extension as a test case — the repository is public. Install Ghost Open, run the scan, and read the output. You'll know within 15 minutes whether this changes how you approach the work.

---