I built a small CLI agent that reads dense source files and explains them like a patient senior engineer. It is for beginners who are tired of copying code they do not understand, and for anyone onboarding into an unfamiliar codebase. In this guide, I will walk you through shipping your own version in under fifty lines of Python.
What you'll need
- Python 3.10 or newer
- The OpenAI SDK:
pip install openai - An Oxlo.ai API key from https://portal.oxlo.ai. The free tier includes 60 requests per day, which is plenty for testing and iterating.
Step 1: Connect to Oxlo.ai and test the endpoint
Create a file named code_tutor.py and initialize the client. Oxlo.ai exposes a fully OpenAI-compatible endpoint at https://api.oxlo.ai/v1, so the only changes needed are the base_url and the model name. I am using deepseek-v3.2 because Oxlo.ai offers it on the free tier and it handles code reasoning well. There are no cold starts, so the first request feels as fast as any other.
Because Oxlo.ai uses flat per-request pricing, you can paste large files into the context window without watching metered tokens burn away. That matters when you are pointing this tool at real modules instead of toy examples.
from openai import OpenAI
client = OpenAI(base_url="https://api.oxlo.ai/v1", api_key="YOUR_OXLO_API_KEY")
response = client.chat.completions.create(
model="deepseek-v3.2",
messages=[
{"role": "user", "content": "Confirm you are ready to explain code."},
],
)
print(response.choices[0].message.content)
Run this once to verify your key and network path. If you see a response, you are connected.
Step 2: Design the system prompt
The system prompt is the only real logic in this agent. I iterated on this until the output stopped sounding like auto-generated documentation and started sounding like a mentor sitting next to you. It forces the model to surface prerequisites first, then group related lines into logical blocks, then flag a common trap.
I keep the output as markdown prose rather than JSON. Beginners need readable explanations, not structured fields they have to parse. You could add JSON mode later if you want to feed this into a UI, but for a CLI tutor, plain text is king.
SYSTEM_PROMPT = """You are a patient senior engineer teaching a junior developer.
When given code, do the following:
1. Identify the language and the overall goal in one sentence.
2. List any prerequisites (libraries, language features, or patterns) the reader must know.
3. Explain the code line by line, but group related lines into logical blocks.
4. Highlight one 'complexity trap', a common mistake beginners make with this pattern.
5. Suggest one concrete exercise to solidify understanding.
Use plain language. Avoid jargon unless you define it immediately."""
Structuring the prompt as a checklist gives you consistent formatting across runs. That predictability makes the output safe to pipe into other tools or save to a file.
Step 3: Build the explainer function
Next, wrap the API call in a function that accepts a raw code string. I set the temperature to 0.3 because explanations should be stable, not creative. I wrap the user payload in markdown fences so the model knows exactly where the code ends and the instruction begins.
The f-string that injects the code is deliberately simple. I do not use a template engine because the agent is stateless and has no memory. Each invocation is independent, which makes debugging easy. If the explanation looks wrong, you tweak the prompt and rerun without worrying about stale conversation history.
In a token-based pricing world, I would worry about sending the same long file multiple times. Here, each call is one flat request. If you want to experiment with different prompts or models, you can rerun without recalculating token budgets. For exact plan details, see https://oxlo.ai/pricing.
def explain_code(code_snippet: str) -> str:
response = client.chat.completions.create(
model="deepseek-v3.2",
messages=[
{"role": "system", "content": SYSTEM_PROMPT},
{"role": "user", "content": f"Explain this code:\n\n```\n{code_snippet}\n```"},
],
temperature=0.3,
)
return response.choices[0].message.content
I skip retry logic here to keep the code short, but in production you should wrap this in a basic try block or a retry library. Because Oxlo.ai serves popular models with no cold starts, failures are usually transient network blips rather than model loading timeouts.
Step 4: Add a complexity preview
Before dumping a full explanation, I give the reader a preview of the concepts they are about to encounter. It works like a table of contents. When I onboard juniors onto a legacy codebase, the biggest friction is not the code itself. It is the fear that they are missing hidden context. A preview that names the top three concepts acts as a psychological anchor. It tells the reader that they only need to understand closures, decorators, and recursion, and nothing else is hiding in the snippet.
I split this into a second call because it keeps each response focused. On a token-based provider, sending the same long input twice would double your context cost. With Oxlo.ai's request-based pricing, you pay for two requests, and the math shifts in your favor when the input file is long.
def analyze_complexity(code_snippet: str) -> str:
response = client.chat.completions.create(
model="deepseek-v3.2",
messages=[
{"role": "system", "content": "List the top 3 programming concepts used in this code. Return as a bulleted list. Be concise."},
{"role": "user", "content": code_snippet},
],
temperature=0.2,
)
return response.choices[0].message.content
Step 5: Wire up the CLI
Finally, combine everything into a script that reads a file path from sys.argv. I use a file argument instead of stdin because pasting multi-line Python into a terminal is painful, and you will likely want to point this at real modules on disk. You could also read from a git diff or accept a GitHub URL, but a local file keeps the tutorial self-contained. If you work with codebases that use aggressive unicode, add encoding="utf-8" to the open call.
import sys
if __name__ == "__main__":
if len(sys.argv) < 2:
print("Usage: python code_tutor.py ")
sys.exit(1)
with open(sys.argv[1], "r") as f:
code = f.read()
print("=== Complexity Preview ===")
print(analyze_complexity(code))
print("\n=== Detailed Explanation ===")
print(explain_code(code))
Run it
Create a file named sample.py with a pattern that confuses most beginners, like a closure-based memoization decorator.
def memoize(func):
cache = {}
def wrapper(*args):
if args not in cache:
cache[args] = func(*args)
return cache[args]
return wrapper
@memoize
def fib(n):
if n < 2:
return n
return fib(n - 1) + fib(n - 2)
Run the tutor:
python code_tutor.py sample.py
You should see output similar to this:
=== Complexity Preview ===
- Closures and nested functions
- Decorators and the @ syntactic sugar
- Recursion with memoization
=== Detailed Explanation ===
Language: Python. Goal: speed up a recursive Fibonacci calculator by caching previous results.
Prerequisites:
- Functions are first-class objects in Python.
- A closure lets an inner function remember variables from the outer scope even after the outer function finishes.
Line-by-line explanation:
Lines 1-2: We define a decorator factory named memoize and initialize an empty dict called cache. This dict survives after memoize returns because the wrapper closure holds a reference to it.
Lines 3-6: The wrapper checks the cache before calling the original function. If the arguments tuple is new, it computes the result, stores it, and returns it. If the arguments are already cached, it skips the computation and returns the stored value immediately.
Lines 8-9: We apply the decorator to fib using the @ symbol. This replaces the name fib with the wrapper function returned by memoize. The wrapper has the same signature as the original, so calling code does not know caching is happening.
Lines 10-13: The recursive Fibonacci logic. The base case stops the recursion when n is 0 or 1.
Complexity trap:
Beginners often forget that the cache dictionary lives inside the closure. If you decorated multiple functions with the same memoize call, they would share the same cache. In production you should use functools.lru_cache instead.
Exercise:
Rewrite this without the decorator syntax. Manually pass fib into memoize and assign the result back to fib. This lets you see exactly what the @ symbol does under the hood.
Next steps
Two concrete ways to extend this tool.
First, add a --model argument so you can compare how different Oxlo.ai models explain the same snippet. Try qwen-3-32b if you want multilingual comments, or kimi-k2.6 if you want advanced reasoning traces. Because every model on Oxlo.ai shares the same flat per-request pricing, you can swap them in for an A/B test without recalculating token costs.
Second, add a "simplify" pass. After the explanation, send a second request asking the model to rewrite the code using only basic constructs that a first-year programmer understands. Beginners learn faster when they can compare the production-grade version against a flat, explicit version that uses no decorators or closures. That second pass is just another request, so you can iterate on the prompt until the output feels right. If you build it, consider writing the results to a markdown file so you can keep a running study guide of every complex pattern you have conquered.
