Inspiration
Every codebase accumulates invisible problems over time. Functions that nothing calls anymore. Modules that silently grow to depend on fifteen other modules. Domain-layer code that one day starts importing the PostgreSQL driver directly because a developer took a shortcut during a deadline. Circular dependencies that make any change unpredictable because you can't reason about the impact.
Most teams know these problems exist. But finding them requires manual code review sessions, fragile grep-based shell scripts, or expensive commercial static analysis tools that take hours to configure. Meanwhile, GitLab Orbit indexes your entire repository into a property graph — every definition, every cross-file reference, every module relationship — and the result just sits there in a DuckDB file. It's an incredibly rich data source that's almost entirely unused beyond code navigation and AI context.
Orbit Recon was born from a simple observation: if Orbit already maps every reference in your codebase as a graph, why aren't we querying that graph for code health? The GitLab Transcend Hackathon was the perfect catalyst to turn that observation into a real tool — and building it as a Rust binary that naturally fits the Orbit ecosystem (which is itself a Rust project) made it feel like the right thing to do.
What it does
Orbit Recon reads the DuckDB property graph produced by orbit index and runs four automated health checks, then generates structured reports in Markdown, JSON, or YAML.
Dead Code Detection finds functions, classes, methods, structs, and enums that have zero incoming references anywhere in the codebase — definitions that exist but nothing uses. Public definitions with no references are flagged as critical since they represent dead API surface, while private helpers get a warning since they might be used via reflection or plugin systems.
Circular Dependency Detection builds a module-level dependency graph from the raw cross-file references and detects both simple bidirectional cycles (A depends on B and B depends on A) and longer multi-module cycles (A→B→C→A) using iterative DFS. Each cycle is scored by total cross-reference volume.
Module Coupling Analysis measures the fan-out metric for every module — how many other modules each module directly depends on. High fan-out is one of the most reliable predictors of change-prone code: when a module depends on 15 other modules, any change to any one of those 15 can break it.
Architectural Drift Detection lets teams define layer boundaries in a simple YAML config (e.g., domain can only import domain and types). Orbit Recon checks every cross-file reference against these rules and catches violations automatically — the kind of architectural erosion that happens gradually and goes unnoticed until it's structurally entrenched.
All findings are classified by severity (info, warning, critical) with specific remediation suggestions. In CI mode (--ci), the binary exits with code 1 if any critical findings exist, making it a merge request gate. The JSON output format is compatible with GitLab Code Quality reports.
How we built it Orbit Recon is written in Rust and built on three design pillars: direct DuckDB graph access, graph-query-based analysis, and the Agent Skills specification.
Architecture: The tool reads the DuckDB file that Orbit Local produces when you run orbit index . on a repository. We chose to read this file directly using the duckdb Rust crate with bundled features, which means Orbit Recon works completely offline with no network calls, no API keys, and no server to configure. The entire analysis runs locally against a local graph snapshot. Rust was chosen intentionally — Orbit itself is a Rust service, so using the same language means natural ecosystem alignment, and it compiles to a single static binary with zero runtime dependencies.
Query Engine: Each of the four analysis checks is implemented as a separate module under src/queries/. Each module prepares SQL queries against the DuckDB graph, executes them via the prepared statement API, and maps result rows into typed Finding structs. For dead code detection, we look for definition nodes with zero in-degree on the REFERENCES edge type. For circular dependencies, we build an adjacency list in Rust and run DFS to find cycles of any length. For coupling, we aggregate the adjacency list into fan-out counts per module. For architectural drift, we match file paths against user-defined boundary rules using glob patterns.
Configuration: The .orbit-recon.yml config file lets teams customize boundaries (with glob patterns for each layer), adjust severity thresholds, and set ignore patterns to suppress false positives from test code, generated files, or known entry points. The config module uses serde_yaml for parsing with sensible defaults that work out of the box for standard layered architectures.
Report Generation: The report module produces Markdown (for developer review with severity badges and recommendations), JSON (compatible with GitLab Code Quality), and YAML (for pipeline configuration).
Agent Platform Integration: The Duo Agent Platform skill is defined in .agents/skills/orbit-recon/SKILL.md following the Agent Skills specification. Any AI agent on the GitLab Duo platform can invoke Orbit Recon — a developer just says "run a health scan" and the agent reads the SKILL.md, verifies prerequisites, runs the binary, and presents the findings. The AGENTS.md file provides broader agent context including the graph query patterns, integration examples, and CI/CD configuration.
Challenges we ran into
Schema Discovery: The Orbit Knowledge Graph's DuckDB schema is not yet fully documented for third-party consumers. Table names, column names, and edge representations can vary between Orbit Local and Orbit Remote. We solved this by building a schema discovery module (src/queries/mod.rs) that queries information_schema.tables and information_schema.columns at runtime to adapt to whatever schema version the graph uses, with graceful fallback when tables or columns don't exist.
False Positives in Dead Code Detection: Not every unreferenced definition is actually dead code. Entry points like main(), test functions, reflection-based plugin registrations, and barrel files (index.ts, mod.rs) all appear unreferenced in the graph but are actually in use. We addressed this with a multi-layer filtering strategy: skip known entry-point filenames, check naming conventions (test prefixes, Spec suffixes), and allow users to add glob-based ignore patterns. Severity classification also helps — uncertain cases are downgraded to Info.
Module Extraction from File Paths: The Orbit graph stores file paths, not module names. Converting src/infrastructure/database/postgres_connection.rs into a meaningful module name like infrastructure requires assumptions about project structure. Our extract_module() function handles the common case (first directory under src/), but monorepos and non-standard layouts may need customization as a future enhancement.
Longer Cycle Detection Performance: Detecting cycles beyond simple A↔B pairs requires graph traversal that can be expensive on large monorepos with tens of thousands of nodes. Our DFS-based cycle finder includes cycle normalization (rotating to the lexicographically smallest element) and deduplication to avoid reporting the same cycle multiple times. The --only flag lets users run individual checks to keep analysis time reasonable on large codebases.
Accomplishments that we're proud of
Zero-config analysis — Orbit Recon works out of the box with sensible defaults for standard layered architectures. Just orbit index . then orbit-recon and you have a full health report. No server setup, no API keys, no configuration files required. Three output formats — Markdown for humans, JSON for machines and CI/CD (compatible with GitLab Code Quality), and YAML for pipeline configuration. The JSON schema is designed to plug directly into existing GitLab workflows. Agent Skills specification compliance — The SKILL.md follows the emerging standard, making Orbit Recon installable via glab skills install and invocable by any compatible AI agent including GitLab Duo, Claude Code, Codex, and Gemini CLI. CI/CD as a first-class use case — The --ci flag and .gitlab-ci.yml template make it trivial to add code health as a merge request gate. The JSON output feeds directly into GitLab Code Quality reports, so findings appear inline on merge request diffs. Single binary, zero dependencies — Rust + bundled DuckDB means users don't install DuckDB separately, don't configure a server, don't set API keys. cargo install orbit-recon and everything just works. What we learned The Orbit Knowledge Graph is a powerful but underexplored surface for developer tools. Most Orbit usage today focuses on code navigation and AI context, but the property graph structure is equally valuable for static analysis, architectural enforcement, and code health monitoring. We're convinced there are dozens more tools that could be built on top of this graph. The Agent Skills specification is still emerging, and there's a gap between what the spec defines and what agents can actually execute. Our SKILL.md bridges this by including explicit shell commands that the agent can run, not just natural-language descriptions of what to do. Rust's DuckDB ecosystem is mature enough for production tooling. The bundled feature means no system dependency on DuckDB, and the prepared statement API is fast enough for graphs with tens of thousands of nodes. The single-binary distribution model is a significant advantage for developer tools. Architecture boundaries are one of the most requested but least automated aspects of code review. Teams know their code is drifting but have no automated way to detect it at scale. Orbit Recon fills this gap by making boundary enforcement a simple graph query against the Orbit index. Building a demo video programmatically (Python frame generation + TTS narration + ffmpeg composition) is entirely feasible and produces reasonable results for hackathon submissions where production quality isn't the priority.
What's next for Orbit Recon
Orbit Remote adapter — Currently reads Orbit Local's DuckDB file. Next step is an adapter that queries Orbit Remote via gRPC/HTTP, enabling analysis of GitLab-hosted repositories without local clones. Historical tracking — Run Orbit Recon on each commit and track finding counts over time. Store results in SQLite alongside the DuckDB graph and plot trends in a dashboard to see if code health is improving or degrading. Diff mode — Compare two Orbit graph snapshots (before and after a merge request) and report only new findings. This makes MR reviews focused and actionable rather than overwhelming. VS Code extension — Inline annotations for drift violations and dead code, powered by the Orbit Recon binary running in the background on file save. AI Catalog publication — Submit to the GitLab AI Catalog so any Duo Agent Platform user can install it with one click from the catalog browser. Multi-language optimization — Tune module extraction, ignore patterns, and severity defaults for Python, Go, Java, and Ruby codebases, in addition to the current TypeScript/Rust defaults. Web dashboard — A simple HTML report with an interactive dependency graph visualization using D3.js or vis.js, so teams can visually explore cycles, coupling, and drift violations in their codebase.
Log in or sign up for Devpost to join the conversation.