The worst week of any job is the first one on a codebase nobody has time to explain. There's a wiki, three years out of date. There's a README that stops at "run make dev." There's one engineer who knows the dangerous parts and is in back-to-back meetings until Thursday.

I've onboarded onto enough of these to have a routine now. Most of it runs through one tool: Octocode, driving an AI assistant over MCP. The trick isn't asking the AI to "explain the codebase." It can't — it's blind. The trick is giving it a map first, then asking sharp questions. Octocode is the map.

I use this afternoon workflow.

Why an AI Can't Just Read It

Drop a 200,000-line repo on any model and it falls over the same way a human does: it can't hold it all in its head, and it can't tell what's load-bearing from what's noise. Standard text search (grep and friends) makes it worse — search "user" and you get models, fixtures, CSS classes, and a migration from 2019.

Octocode understands structure. It parses your code with tree-sitter into real symbols, then builds a GraphRAG knowledge graph of how those symbols relate — imports, calls, sibling_module, parent_module, and child_module. Your AI assistant doesn't search flat text; it navigates an architecture.

Set it up first — install, set an embedding key, octocode index, connect your client — using the 5-minute setup guide. Then come back here.

Hour One: Find the Front Doors

Don't start by reading files. Start by finding the few that matter. Once Octocode is connected, your assistant has semantic_search, so ask it questions in plain language:

text 
You: "Where does an incoming HTTP request first get handled?"
You: "Where is authentication implemented?"
You: "Where do we talk to the database?"

semantic_search finds code by meaning, so "where do we validate tokens" lands on verify_jwt_token() even with zero keyword overlap. In an hour of asking these, you'll have the five or six entry points that define the system: the router, the auth boundary, the data layer, the job queue, the config. That's your skeleton.

You follow the structure the codebase actually has, not whatever order the file tree throws at you. That's why this beats reading top to bottom.

Hour Two: Read Shapes, Not Walls of Code

Now you know where the auth module is. You don't want to read all 1,400 lines of it. You want its shape.

That's view_signatures — function signatures, class definitions, interfaces, imports, without the bodies. Ask your assistant to outline a file and you get the contract: what's public, what it depends on, what it returns. Five files outlined this way tell you more about a system than one file read in full.

When something actually doesn't make sense, read the body — and Octocode's CLI has a sharp tool for it:

bash 
octocode explain src/middleware/auth.rs

explain gives you a structured breakdown of a file, symbol, or concept. I use it the moment a function's name and its job stop agreeing.

Hour Three: Trace the Blast Radius

This is the part text search cannot do, and it's where the knowledge graph earns its keep. Before you change anything, you want to know what depends on it. graphrag answers exactly that:

text 
You: "What depends on the PaymentProcessor trait?"
AI: (queries the graph) "src/api/handlers/checkout.rs, src/workers/refund_worker.rs,
    and src/cron/billing.rs all depend on PaymentProcessor. It's defined in
    src/domain/payment.rs and implemented by stripe.rs and paypal.rs."

From the CLI the same query is explicit about direction — incoming versus outgoing edges:

bash 
octocode graphrag get-relationships --node-id src/middleware/auth.rs
# Outgoing:
#   imports → jwt (src/auth/jwt.rs): token validation logic
#   calls   → user_store (src/db/user_store.rs): user lookup by token
# Incoming:
#   imports ← router (src/router.rs): wires auth into the request pipeline

"What calls this?" and "what does this import?" are the two questions that turn a scary change into a bounded one. The graph answers both in milliseconds, and it answers them correctly — these are parsed relationships, not a model's guess.

Hour Four: Audit Before You Touch

By now you understand the system. Last move before you write anything: find the landmines. structural_search does AST pattern matching, so you can ask structural questions text search can't:

text 
You: "Show me all error handling in the API layer."
AI: (uses structural_search) "Found 23 patterns in src/api/:
    - 15 use Result<T, ApiError> with explicit error types
    - 8 use .unwrap() (potential panics in handlers/user.rs:42, handlers/auth.rs:87)
    - 3 use .expect() with custom messages"

Now you know where the panics hide before you trigger one. This is also the fastest way to pick up a team's conventions: search for how they handle errors, structure handlers, wire config — you absorb the house style without anyone having to write it down.

The Commit History Is a Map Too

One more angle people miss. The why behind code often lives in commits, not files. Octocode can search history semantically:

bash 
octocode search "authentication refactor" --mode commits

When you find a function that makes no sense, searching the commits around it for the feature name frequently surfaces the PR that explains it. Code tells you what; history tells you why.

Why This Works

A normal onboarding is linear: read, read, read, slowly build a model in your head, hope it's right. This one is structural: find the entry points, read their shapes, trace their dependencies, audit the risks. You're using the same map the codebase already has — its import graph, its call graph, its symbol structure — instead of reconstructing it by hand.

And the AI is finally useful here, because it's no longer guessing. Every answer it gives is grounded in a real search result or a real graph edge. Octocode ships a reproducible benchmark — 127 curated code-search queries against its own pinned source, run on a fully local no-API-key stack — and the README frames those numbers as a floor, not a ceiling. On that benchmark, the keyword-tuned hybrid config lands the right file in the top 10 about 83.5% of the time, so when your assistant says "auth is in src/middleware/auth.rs," it's reading that from the index, not hallucinating a plausible-sounding path.

That structural understanding stays useful long after onboarding — every refactor starts with "what depends on this," every bug starts with "where does this happen." Once your agent can navigate instead of grep, one tool call answers it. Not ten.

If you haven't wired Octocode in yet, start with the Claude Code / Cursor / Windsurf setup guide. Then go meet your new codebase — you'll know it better by dinner than most people do in a week.

Get Octocode — turn an unfamiliar repo into a map.