Skip to content

Explore Your Codebase

In this tutorial, you'll use the Ask agent to get cited answers grounded in your actual source code, with exact file paths and line numbers.

Prerequisites

  • Potpie CLI installed and set up (Quickstart)
  • A repository registered as a source (potpie source add repo .)

Steps

1. Confirm the graph is ready

Before asking questions, verify the active pot and graph are ready:

potpie status --host

✔ daemon        running
✔ pot           my-project (active)
✔ graph         ready
✔ skills        up to date

2. Ask your question

Type a natural language question about the codebase. Ask handles flow tracing and dependency mapping automatically.

potpie resolve "how does the authentication middleware work?"

A typical response cites exact file locations:

Authentication middleware is implemented in app/middleware/auth.py.

1. verify_token()  (app/middleware/auth.py:21)
   - Reads the Bearer token from the Authorization header
   - Decodes and validates the JWT via app/auth/jwt.py:decode_token (app/auth/jwt.py:44)

2. Applied to routes via the @requires_auth decorator
   (app/middleware/auth.py:58), used in app/routes/users.py and
   app/routes/orders.py.

Citations: app/middleware/auth.py, app/auth/jwt.py, app/routes/users.py

Note

When a question involves a third-party library, Potpie retrieves external documentation via web search automatically.

To look up a specific symbol, workflow, or convention rather than a broad explanation, use search:

potpie search "token expiry handling"

app/auth/jwt.py:71  decode_token() raises TokenExpiredError on exp claim
app/middleware/auth.py:33  catches TokenExpiredError → returns 401

4. Follow up

Follow-up questions within the same session retain full context. Start broad and narrow down:

> "What does the auth middleware do?"
> "Which routes use it?"
> "What happens if the token is expired?"

Example questions

  • "How does the payment processing flow work end-to-end?"
  • "Where is the user model defined and what are its relationships?"
  • "What would break if I changed the database schema for orders?"
  • "How is error handling done across the API layer?"

What's happening under the hood

Ask classifies your question by type (what, how, where, or why), then:

  1. Searches the knowledge graph via vector similarity
  2. Traverses structural relationships for connected context
  3. Reads source files directly when needed
  4. Assembles a cited answer grounded in real code

Next steps