Orbit Code Explainer Agent

Inspiration

Every developer knows the pain: joining a new project, staring at unfamiliar code, having no idea what it does or why it exists. Reading line-by-line takes hours. Documentation is outdated or missing. We built Orbit Code Explainer to eliminate that friction—turning onboarding from days into minutes.

What it does

Orbit Code Explainer is a CLI agent that integrates GitLab Orbit's knowledge graph with AI to instantly explain any file, directory, or codebase change. Four core modes:

File Explainer — Plain-language breakdown: what the file does, what definitions it contains, what it depends on, what calls it.
Component Blueprint — Auto-generated Mermaid dependency graphs for entire directories.
Impact Analyzer — Hybrid upstream dependency tracing with risk assessment (LOW/MEDIUM/HIGH/CRITICAL).
Interactive Q&A — Persistent conversation mode with full code context maintained.

How we built it

We combined three core architectural technologies:

GitLab Orbit — A local knowledge graph that indexes repositories and surfaces definitions + dependencies via SQL queries.
Hybrid Upstream Tracing — Flat SQL dependency joins combined with an automated repository-wide keyword fallback scanner to capture missing structural links.
Adaptive Multi-Provider AI Layer — A robust normalization layer that routing-switches across Google (Gemini 2.5 Flash), OpenAI (DeepSeek/OpenRouter), and Anthropic (Claude) natively by translating payloads on the fly.

Core workflow:

Index repository with orbit index
Query gl_definition and gl_edge tables for structural relationships
Extract source code with smart truncation (100 KB threshold + structural slicing)
Normalize payloads and route context to the chosen AI provider for explanation

Challenges we ran into

Knowledge Graph Complexity — Learning Orbit's schema and SQL patterns took time; we had to reverse-engineer query patterns for different use cases.
Dependency Mapping Fallbacks — Strictly relying on strict database language links sometimes caused missed relationships; we built an integrated os.walk fallback parser to crawl textual references globally when DB edges miss.
Context Window Management — Balancing code extraction size with API token limits; implemented structural definition slicing for large files.
Multi-Provider Payload Matching — Normalizing Gemini-style histories into standard OpenAI messages and Claude syntax while preserving multi-turn state across different providers.
Error Handling — Graceful failures when Orbit index is missing or file paths contain invalid shell characters.

Accomplishments that we're proud of

✅ True Structural Understanding — Uses actual code intelligence, not just regex or basic heuristics.
✅ Hybrid Impact Analysis — Risk assessment that marries explicit schema tracing with comprehensive workspace string scanning.
✅ Multi-Mode Flexibility — Single agent handles 4 distinct use cases (explain, visualize, analyze, Q&A).
✅ Q&A Persistence — Full code context maintained perfectly across multi-turn conversations.
✅ Smart Optimization — 100 KB threshold + structural slicing keeps API costs low on large codebases.
✅ Mermaid Visualization — Auto-generated dependency graphs with robust hub/star topologic mapping fallbacks when files lack deep database linkages.
✅ Production-Ready CLI — Universal routing with error handling, help text, and clean progress indicators.

What we learned

Knowledge graphs are powerful — Orbit's ability to extract definitions and dependencies is game-changing; far better than single-regex approaches.
Hybrid tracking scales reliably — Combining targeted flat database queries with codebase-wide fallback matching yields higher reliability without massive recursive loop overhead.
AI synthesis beats raw data — Converting dependency data into narratives is what makes the tool useful; raw output alone is noisy.
Mode-specific prompting matters — Asking "explain this file" vs. "what breaks if I change this?" requires fundamentally different context payloads.
Adaptive layers create flexibility — Decoupling the client code from any single LLM API allows developers to use the exact open-source or proprietary models they prefer.