Understand and onboard to a codebase

When you'd do this

• You've joined a team and been given a ticket in a part of the system nobody has walked you through.
• You're moving to a service or repository you've never touched, even though you know the rest of the organisation.
• You're onboarding a new hire and want them to answer most of their "where is…" questions themselves, with references a senior engineer can check quickly.
• Someone asks you to look at a feature whose code is spread across an API, a worker, a shared library and a frontend.
• You've found a line that makes no sense and need to know who wrote it, when and why before you touch it.
• You're the tech lead who keeps answering the same ownership and "what calls this" questions, and you want those answers to be self-service.

Before you start

• CodeZero is installed in VS Code and connected to your organisation, and your repositories are indexed. Check that the Files view lists the repositories you expect. The index covers committed code on the default branch. Where a repository is checked out locally, CodeZero uses your working tree.
• A coding agent that CodeZero works with: Claude Code, Codex, GitHub Copilot or Cursor.
• For runtime questions, Vörr is connected to Claude, ChatGPT or another MCP assistant. Your organisation's admin should have connected repositories, cloud accounts (AWS, Google Cloud or Azure, read-only), and the observability and CI/CD tools the team uses. Vörr answers from the organisation's connected sources, and workspaces label what comes back. ChatGPT needs a paid plan with Developer mode turned on.
• Feature names in Functions need to be generated once. Anyone with a coding agent set up in CodeZero can do it, and the names are shared with the organisation.
• You don't need write access to production or credentials for any cloud console. Everything on this page except the last operation is read-only.

If any of this isn't set up yet, start here:

• Install and connect CodeZero
• Set up a Vörr organisation
• Connect Vörr to your assistant

Operations

Onboarding isn't one task. These are the operations it breaks into, in roughly the order a new engineer needs them. Each one says which product or tool does each step.

1. See the repository landscape

1. CodeZero: open the Files view. It lists every repository indexed for the organisation. A repository that's checked out expands to its working tree. One that isn't still expands to its indexed file list, and you can open its files from the index.
2. CodeZero Chat: ask for an overview of each repository you're likely to touch. The overview covers languages, frameworks, entry points, the top-level tree and the dependencies declared in its manifests.
3. Your agent: for repositories that are already cloned, it can read the README, build files and tests directly for more detail.

A good result keeps the facts apart from the guesses. Languages, frameworks, entry points and dependencies come from the index. The repository's "purpose" is the agent's inference. Check a few entry points by opening the files.

2. Learn one feature end to end

1. CodeZero: open Functions. If the areas still show as paths such as src/checkout, select Name all features once.
2. CodeZero: choose the feature from your ticket and read its map from left to right. It runs from Entry (where requests or control come in) through Goes Through (the implementation files) and Reads / Writes (the data it touches) to any other repository it crosses into.
3. CodeZero: hover a sub-part to highlight its files, or click it to keep the highlight pinned while you read.
4. CodeZero Chat: take the feature into Chat and ask for the flow in plain terms. Then open the file references it returns and check them.

A good result is an ordered flow in which every step has a file reference. Read the entry file and one Reads / Writes file yourself. If Chat can't tell from the code which of two paths a request takes, it should ask you or say so, not pick one.

3. Explore the graph around it

1. CodeZero: open Graph and keep All repositories selected, so links that cross repositories stay visible.
2. Select the module or file you met in the feature map. The detail panel shows Depended on by (what points into it) and Depends on (what it points to).
3. Add third-party packages and the data layer when you need them. Data nodes show the tables and collections next to the code that reads or writes them.
4. Inferred links between repositories are HTTP calls matched to routes, services named in Kubernetes, Helm or Compose config, and queue producers and consumers. Each one shows the file and line it was inferred from, and HTTP and config links also show a confidence level. Verify HTTP links you plan to rely on, and the agent will check the call site; for config and queue links, open the cited line.

This is for your area only. For a map of the whole system, see Understand system architecture.

4. Find where a behaviour lives

1. CodeZero: start with the kind of search that fits what you know. Use text search for an error message or a log line, symbol search for a function or class name, and topic search when all you have is a description such as "how retries work".
2. CodeZero: search spans every indexed repository, cloned or not. Symbol definitions are parsed for TypeScript, JavaScript, Python, Go, Java, Ruby and C#. Other languages can be searched as text.
3. CodeZero: follow a match through its references and callers. These are matched by name and are heuristic, so a symbol with the same name in another package can turn up.
4. Your agent: once you know the repository, clone it, or open it from the index, and read the code locally.

A good result names the repository and file for each match and says when two matches might be different symbols with the same name. Ask it to confirm by reading the definition.

5. Read a service's routes and configuration

1. CodeZero: list the HTTP routes the repository declares. Route detection covers NestJS, Express and Fastify, Flask and FastAPI, Spring, Rails, .NET and Go routers, and gives the method, path, file and line for each route.
2. CodeZero: find the settings the code expects and where each one is set: the code default, .env.example, and the Helm values or manifests for each environment.
3. CodeZero: for any setting that names another service, find where it's set in Kubernetes, Helm or Compose config. That tells you what the service talks to in each environment.

Routes and settings are read from source, so a route registered dynamically or a setting read through an unusual wrapper can be missing. If the list looks short, check the router setup file.

For a whole-system interface inventory, see Understand system architecture.

6. Find owners and recent changes

1. CodeZero: ask who owns a path. Ownership is worked out from commit history: who has committed most to that path, based on the indexed (shallow) history. Full history needs a local checkout.
2. CodeZero: list recent commits for the repository or one directory to see what's actively changing and who's changing it.
3. Vörr: from Claude or ChatGPT you can ask the same owner and change questions through Vörr's code access. Vörr also shows which branch deploys to which environment.

Commit count shows who has been active, not who's accountable. Use it to find out who to ask, and confirm with the team.

7. Explain a surprising line

1. CodeZero Git Tree: turn on Blame from the toolbar, open the file and select the line. It shows who last changed it, when and in which commit. Hover for more detail about the commit.
2. CodeZero Git Tree: open file history to see every commit that touched the file, and read the diff where the behaviour changed.
3. Your agent: read the commit message, the linked pull request (with gh, if it's set up) and the surrounding code, then explain why the line is there.

A good answer names the commit and quotes its message. When the history doesn't give a reason, it says that instead of making one up.

8. Learn where it runs

1. Vörr: from Claude, ChatGPT or another MCP assistant, ask which environments the service runs in and which cloud resources make it up. Vörr resolves the name through the service map and confirmed aliases, and gives the match quality.
2. Vörr: ask what the service is exposed to. Vörr follows the path from the service to its host or network interface and its security groups, includes any load balancers in front, and classes the result as public, private, isolated or unknown.
3. Vörr: ask what it depends on and what depends on it, both one hop away and through the precomputed blast radius.
4. Vörr: ask for its recent errors and deploys, so you know whether it's stable before you change it.
5. Vörr web app: open Architecture to see the same dependencies laid out visually.

Check the match quality on each fact. Explicit means the service map links the name; identity and exact mean a confirmed alias or a catalogue name. Name means a raw-name hit, suggested means Vörr proposed the match, and unmapped means nothing matched. Confirm name, suggested and unmapped matches before relying on them. Also check scan coverage: an empty list from an account where access was denied is not "nothing there".

For the visual map and how to read it, see Explore your cloud architecture.

9. Build a personal onboarding plan

1. CodeZero Chat: tell it your ticket or the area you're joining, and ask for a reading list in a sensible order. Each item should be a file with a reference and a reason to read it.
2. CodeZero Chat: ask for the people to talk to, based on owners by commit history, and the open questions the code can't answer.
3. Vörr: add the runtime items, such as dashboards to look at, the noisiest error and the last few deploys.
4. You: keep the list in your notes or the team's onboarding doc. Every item has a reference, so a senior engineer can review it in minutes.

Check every reference by opening it. If an item has no reference, treat it as something to ask about, not a fact.

10. Make a first safe change

1. Pick something small and real, such as a log message, a missing test or a validation rule.
2. CodeZero: use Normal mode to confirm each change, or Auto mode, which asks before each small direct edit and plans bigger work; after approval, edits in the plan's repositories proceed. Planned mode makes no code changes until a plan is approved, which suits a change that crosses repositories.
3. CodeZero: if a plan is made, read it. It names the repositories, phases and verification commands, and the agent can't approve it itself. Edits in the plan's repositories go ahead, an edit in another checkout of an organisation repository asks first, and paths outside every checkout are refused.
4. CodeZero Git Tree: review the working tree, compare against the main branch, and commit or push yourself when you're happy.

This shows you how the team's tests, linters and review flow work without much risk. Execution modes compares the three modes, and a larger first change belongs in Build a feature.

Without CodeZero or Vörr

Claude Code is very good at explaining a repository you've cloned. It can read the whole tree, grep for symbols, run the tests, and use git log and git blame to explain history. If gh, cloud CLIs or vendor MCP servers are set up and have credentials on your machine, it can use those too. ChatGPT or Claude chat can reason well over code, logs and diagrams you paste in. The gaps are about what they can see, not how well they reason.

The cost alone is mostly setup and stitching. You have to clone the right repositories and know they exist, put cloud and observability credentials on a new hire's laptop, and check answers that come back empty without saying whether anything was searched.

With CodeZero and Vörr

CodeZero: the whole codebase, not just the folder

Search, read, overviews, routes, config, dependencies and owners cover every indexed repository, including ones nobody on the team has cloned.

CodeZero: links between services

Graph shows the HTTP, configuration and queue links between repositories, and the tables each one reads and writes. Each inferred link shows the line it came from, HTTP and config links also show how confident they are, and verdicts from Verify are kept for everyone.

CodeZero: features, not folders

Functions gives a newcomer a named starting point with Entry, Goes Through and Reads / Writes. The names are shared across the organisation.

CodeZero: a first change under review

Modes, plans the agent can't approve itself, and confirmation before any edit outside the plan's repositories let a new engineer learn the workflow without surprises.

Vörr: the running system, from chat

Environments, cloud resources, exposure, dependencies, recent errors and deploys, with no cloud or observability credentials on the new hire's machine.

Vörr: honest gaps

Every fact comes with its source and match quality. A question no connected tool can answer gets "no connector", and scan coverage shows where an empty result means "not scanned".

The two products work side by side. Learn the code path in CodeZero inside VS Code, then ask Vörr from Claude or ChatGPT where that code runs and how it's behaving. Vörr doesn't run inside CodeZero. You use them together.

Worked example: first week on refunds

A new engineer gets a ticket: "Partial refunds sometimes show the wrong amount in the customer email." They have only cloned the web frontend.

1. Files view: 14 indexed repositories. refunds-service, notifications-worker and shared-money are not cloned.
2. Functions: the Refunds feature starts in the frontend, goes through refunds-service and writes to the refunds table.
3. Graph shows refunds-service publishing to a queue that notifications-worker consumes.
4. Search for "Your refund of" finds the email template in notifications-worker.
5. Blame shows who wrote the template's amount formatting and the commit it came from.
6. Vörr provides the runtime facts.

Feature: Refunds
  Entry           web/src/pages/orders/[id]/refund.tsx
  Goes Through    refunds-service/src/refunds/refunds.controller.ts  POST /refunds
                  refunds-service/src/refunds/refund-calculator.ts
  Reads / Writes  refunds (table), orders (table, read)
  Other repo      notifications-worker  (queue: refund.created, refunds.events.ts:31)

Graph: refund.created
  producer  refunds-service/src/refunds/refunds.events.ts:31
  consumer  notifications-worker/src/handlers/refund-created.ts:12

Search "Your refund of"
  notifications-worker/templates/refund-email.hbs:4
  amount formatted by notifications-worker/src/format.ts:formatAmount (local helper)
  shared-money/src/format-money.ts:formatMoney exists and is used by refunds-service

Vörr: notifications-worker
  match          explicit (service map)
  environments   production, staging
  runs on        Kubernetes deployment notifications-worker, namespace comms
  exposure       private (no load balancer; security groups allow cluster traffic only)
  depends on     queue refund.created, email provider (external)
  errors (7d)    no matching issues in Sentry; Datadog logs show 0 errors
  deploys (7d)   2 via Argo CD
  coverage       all connected sources answered

What the engineer concludes

The worker formats amounts with its own helper, which rounds differently from formatMoney in shared-money, and refunds-service uses formatMoney. The bug lives in a repository the engineer hadn't cloned. It doesn't raise errors, because the output is wrong but valid, which explains why the error tracker is quiet.

Verification: they read both helpers from the index, open both ends of the queue link at the lines it cites (it holds), and ask the top committer on notifications-worker whether the local helper is deliberate.

Follow-ups: clone notifications-worker when CodeZero offers it for the plan, then plan a change in Planned mode that switches the worker to formatMoney and adds a test for partial amounts. After approval, the declared test command runs.

Verify and follow up

• Open the file references. Every claim about the code should point to a file and line you can read, with the indexed commit.
• Remember the index covers committed code on the default branch. If a teammate's branch changes the flow, check the branch locally.
• Verify HTTP links, and open the cited line for config and queue links. Treat low-confidence HTTP matches as leads until the call site is confirmed. Verdicts are kept, so the next newcomer benefits.
• Read the match quality and coverage on Vörr answers. A name, suggested or unmapped service match, or an account with access denied, means the answer may be incomplete.
• Check references to same-named symbols. They're matched by name, and callers are heuristic, so look at the definition before you rely on them.
• Have someone who knows the area review your reading list. Referenced items are quick to check.
• Next operations: build a feature, review a pull request in the area, or map the wider system.

Limits

• CodeZero only knows what's indexed. Repositories that aren't connected, and code outside the default branch that you haven't cloned, are invisible to it. An empty search result can mean the code isn't indexed.
• Links between repositories are inferred from evidence such as URL literals, config and queue names. They're not compiler-accurate. Dynamic URLs, service discovery and unusual client wrappers can be missed or mismatched.
• Symbols are parsed for TypeScript, JavaScript, Python, Go, Java, Ruby and C#. Other languages can only be searched as text. Topic search returns matches, but isn't guaranteed to find every relevant file.
• Owners come from commit history, not from an ownership policy or CODEOWNERS decisions.
• Feature names are generated once someone selects Name all features, so read them as a starting point, not as documentation of intent.
• Vörr only knows what has been connected and scanned. Answers depend on the service map being kept up to date. Vörr is read-only, and it can't change infrastructure from chat.
• Neither product replaces talking to the team about why things are the way they are, when the code and history don't say.

Related

• Understand system architecture
• Answer system questions without the IDE
• Build a feature
• Ship a cross-repository change
• Keep context across the team
• Where AI engineering gets stuck
• How CodeZero works
• Trace a product feature
• Explore the Code Graph
• Chat
• Work across repositories
• Git Tree
• Ask Vörr
• Explore your cloud architecture