CodeCompass

Given any GitLab issue or task, CodeCompass uses GitLab Orbit's knowledge graph to instantly tell contributors exactly which files to change - no more codebase spelunking.

Comment

CodeCompass 🧭 — Hackathon Submission

Track: Showcase Track
Project: gitlab-ai-hackathon/transcend/34607690
AI Catalog: CodeCompass (Public Agent)
License: MIT

Inspiration

Every new contributor faces the same wall: you find an issue you want to fix, but have no idea where to start in a massive codebase. You spend hours reading code before writing a single line. This is the contributor onboarding problem, and it affects every open source project, every new hire, every developer switching teams.

Existing tools tell you what changed. But no tool tells you what to change. We wanted to flip that around.

GitLab Orbit already understands the structure of your codebase — files, imports, calls, definitions, merge request history. All that context was sitting there, waiting to be used in the opposite direction: not "what did this change break?" but "what should I change to fix this?"

That's CodeCompass.

What It Does

CodeCompass is a GitLab Duo Agent that takes a task or issue description in plain English and returns a concrete, actionable contribution guide in seconds.

Give it a task like "Add rate limiting to the API gateway" and it will:

  1. Find the right files — Queries GitLab Orbit's knowledge graph to find File nodes whose paths match the task keywords, scoped to the correct project.
  2. Map the blast radius — Expands from those files via IMPORTS and CALLS edges in Orbit to find connected files that may also need changes or will be affected.
  3. Surface reference implementations — Searches Orbit for past merged MergeRequest nodes with similar titles, so contributors can see how similar work was done before.
  4. Confirm with code search — Uses Semantic Code Search and Grep to verify that the files found are genuinely relevant, not just path matches.
  5. Deliver a structured guide — Returns a contribution guide with:
    • 🗂 Files to Change — path, language, and why each file is relevant
    • 🔗 Connected Files — files linked via Orbit's IMPORTS/CALLS edges
    • 📋 Reference MRs — similar past merged MRs with links
    • 🚀 Where to Start — a concrete entry point: which file, which function, what to look for

The contributor can open their editor and start coding immediately. No more codebase spelunking.

How We Built It

CodeCompass is built entirely on the GitLab Duo Agent Platform with zero external infrastructure:

Orbit Integration (the core)

We use three distinct Orbit query patterns, each targeting a different part of the knowledge graph:

Query Type Orbit Entity What It Finds
Traversal File Files whose path matches task keywords
Neighbors File → IMPORTS/CALLS edges Connected files (blast radius)
Traversal MergeRequest (state=merged) Similar past MRs as reference
Path Finding File → File via edges Dependency chains between files
Aggregation Directory → File Hotspot directories with most matches

All queries are scoped to the target project_id so results never leak across repositories. The agent always calls Orbit: Get Graph Schema first to understand available entities and relationships before writing any query.

Delivery Modes

  • Agent (Duo Chat): Users describe their task in natural language. CodeCompass runs the full workflow and returns the guide inline. Best for exploratory work and ad-hoc questions.
  • Flow (Issue/MR Trigger): Triggered automatically when a user mentions the flow service account in an issue or MR comment, or when a reviewer is assigned. Posts the contribution guide as a comment. Best for team workflows and onboarding automation.
  • Skill (Reusable Component): The graph navigation logic is packaged as a reusable skill that other agents and flows can invoke.

Flow: Automated Contribution Guides on Issues and MRs

The CodeCompass Flow (codecompass.yaml in .gitlab/duo/flows/) brings the same Orbit-powered analysis to team workflows without anyone needing to open Duo Chat:

  • Trigger: Mention — Mention the CodeCompass service account in any issue or MR comment, and it automatically reads the context, runs the full Orbit workflow, and posts a contribution guide as a comment.
  • Trigger: Reviewer Assignment — When a reviewer is assigned to an MR, CodeCompass automatically analyzes the MR description and posts a guide showing which files are relevant and what connected files might be affected.

This turns CodeCompass from a tool you have to remember to use into one that's embedded in your team's workflow. Every new issue gets a contribution guide. Every MR gets context for the reviewer. No manual steps.

The flow uses the same Orbit queries as the agent but adds gitlab.create_issue_note and gitlab.create_merge_request_note tools to post results directly as comments.

Skill: Reusable Graph Navigation Component

The CodeCompass Graph Navigator skill (.gitlab/duo/skills/codecompass-graph-navigator/) packages the core Orbit graph navigation logic as a reusable component that other agents and flows can invoke:

  • Inputs: task description, project ID, max files, whether to expand relationships
  • Outputs: primary files, connected files, Orbit availability status, fallback status
  • Orbit queries used: traversal (file discovery), neighbors (relationship expansion), path finding (dependency chains)

This means other teams can build their own agents that leverage CodeCompass's graph navigation without reimplementing the Orbit query logic. For example, a code review agent could use the skill to understand the blast radius of a change, or an onboarding agent could use it to generate learning paths through a codebase.

Design Philosophy: Zero Infrastructure

CodeCompass is intentionally infrastructure-free. No Python backend, no database, no hosted service, no CI runners needed to operate. The intelligence lives in the system prompt engineering and Orbit query design, not in application code.

The GitLab Duo Agent Platform already provides LLM reasoning, tool orchestration, permission enforcement, and hosting. Adding a backend would add complexity without adding capability. The Orbit knowledge graph has the structure; the LLM has the reasoning. CodeCompass connects them.

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                     Entry Points                          │
│                                                           │
│   💬 Agent (Duo Chat)    🔔 Flow (Issue/MR)    🧩 Skill   │
│   User asks question    Auto-triggered       Invoked by   │
│   in natural language    on mention/assign    other agents │
└────────────────────────────┬────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│              Core Workflow (shared by all)                 │
│                                                           │
│  1. Extract keywords from task description                │
│  2. Query Orbit: File discovery (traversal)               │
│  3. Query Orbit: Relationship expansion (neighbors)       │
│  4. Query Orbit: MR history search (traversal)            │
│  5. Confirm via Semantic Code Search + Grep               │
│  6. Generate structured contribution guide                │
└────────────────────────────┬────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                  GitLab Orbit API                          │
│                                                           │
│  File nodes ── IMPORTS edges ── CALLS edges               │
│  MergeRequest nodes ── Definition nodes                    │
│  Directory nodes ── path_finding ── aggregation            │
└─────────────────────────────────────────────────────────────┘

How It Uses GitLab Orbit

CodeCompass is built around Orbit's knowledge graph. Here's exactly how:

File Discovery

{
  "query_type": "traversal",
  "node": {
    "id": "f",
    "entity": "File",
    "columns": ["id", "path", "name", "language"],
    "filters": {
      "project_id": {"op": "eq", "value": "<project_id>"},
      "path": {"op": "contains", "value": "<keyword>"}
    }
  },
  "limit": 10
}

Relationship Expansion

{
  "query_type": "neighbors",
  "node": {
    "id": "f",
    "entity": "File",
    "node_ids": ["<file_ids>"],
    "columns": ["id", "path", "name", "language"]
  },
  "neighbors": {
    "node": "f",
    "direction": "both",
    "rel_types": ["IMPORTS", "CALLS"]
  },
  "limit": 20
}

MR History Search

{
  "query_type": "traversal",
  "node": {
    "id": "mr",
    "entity": "MergeRequest",
    "columns": ["id", "iid", "title", "merged_at"],
    "filters": {
      "project_id": {"op": "eq", "value": "<project_id>"},
      "state": {"op": "eq", "value": "merged"},
      "title": {"op": "contains", "value": "<keyword>"}
    }
  },
  "order_by": {"node": "mr", "property": "merged_at", "direction": "DESC"},
  "limit": 5
}

Orbit Edges Used

Edge What It Tells CodeCompass
IMPORTS Static dependency between files
CALLS Runtime call relationship between files
DEFINES Functions/classes defined in a file
HAS_FILE Directory structure and MR diff files
IN_PROJECT Project scoping for all queries
HAS_DIFF MR change details for reference implementations

Challenges We Ran Into

Translating natural language to graph queries. The hardest part was designing a system prompt that reliably extracts the right keywords from a free-form task description and maps them to Orbit query filters. "Add rate limiting to the API gateway" needs to become path contains 'gateway' and path contains 'rate_limit', not a literal string search.

Balancing precision and recall. Orbit's contains filter on file paths can return too many results for generic keywords or too few for specific ones. We solved this by using multiple query rounds: broad keyword search first, then narrowing via relationship expansion and confirmation with Semantic Code Search.

Graceful degradation. Not every project is indexed in Orbit. The agent needs to detect this and fall back to search tools without pretending Orbit was used. Getting the failure behavior right was critical for trust.

Designing for zero infrastructure. Resisting the urge to build a Python backend was a challenge. Every time we wanted to add "just a small script" for preprocessing, we asked: can the LLM + Orbit handle this directly? The answer was always yes.

Accomplishments We're Proud Of

  • Turning hours into seconds. What used to be hours of codebase exploration becomes a 30-second answer with concrete file paths and entry points.

  • Novel use of Orbit. Most tools use code graphs to analyze what a change breaks. CodeCompass answers what a contributor should change — the inverse traversal problem. Same knowledge graph, opposite direction, different audience.

  • Zero infrastructure. No servers, no containers, no dependencies. Enable from the AI Catalog and start using immediately. This is how agents should work.

  • Honest failure behavior. CodeCompass never guesses and never pretends. If Orbit is unavailable, it says so and falls back gracefully. Trust is a feature.

What We Learned

  • GitLab Orbit's graph relationships (CALLS, IMPORTS, DEFINES) are incredibly powerful for understanding code impact without reading every file. The neighbors query alone can map the blast radius of a change in milliseconds.

  • The Duo Agent Platform is more capable than it looks. You don't need a backend to build a sophisticated agent. System prompt engineering + the right tool selection + Orbit's structured data is enough.

  • Contributor onboarding is an underserved problem. Every open source project, every company with a monorepo, every team with new hires faces this. The tools exist to solve it now.

What's Next for CodeCompass

  • Auto-generate contribution plans with suggested file diffs based on Orbit's understanding of code patterns.
  • Link directly to relevant code sections in past MRs, not just the MR itself, so contributors can see exactly what was changed and how.
  • Issue triage integration — automatically post a CodeCompass guide on every new issue labeled good first issue to lower the barrier for first-time contributors.
  • Cross-project navigation — use Orbit to find relevant files across related projects in a group, not just within a single repo.
  • Impact scoring — rank files by how many other files depend on them via Orbit edges, so contributors know which changes are high-risk.

Built With

  • GitLab Duo Agent Platform (Agent + Flow + Skill)
  • GitLab Orbit Knowledge Graph (traversal, neighbors, path finding, aggregation queries)
  • GitLab Semantic Code Search
  • GitLab Duo Chat
  • YAML (agent, flow, and skill definitions)
  • GitLab CI/CD (YAML and JSON validation pipeline)

Repository Structure

.gitlab/duo/
  agents/
    codecompass.yaml         ← Agent definition (Duo Chat)
  flows/
    codecompass.yaml         ← Flow definition (Issue/MR triggers)
  skills/
    codecompass-graph-navigator/
      SKILL.md               ← Reusable skill for other agents
.gitlab-ci.yml               ← CI pipeline for YAML/JSON validation
ARCHITECTURE.md              ← Technical architecture deep dive
README.md                    ← Project overview
SUBMISSION.md                ← This file
LICENSE                      ← MIT License
samples/orbit/
  01-file-discovery.json     ← Orbit traversal query example
  02-relationship-expansion.json  ← Orbit neighbors query example
  03-mr-history-search.json  ← Orbit MR search query example
  04-path-finding.json       ← Orbit path finding query example
  05-aggregation-hotspots.json    ← Orbit aggregation query example

Team

Built With

  • gitlab-ci/cd
  • gitlab-duo-agent-platform
  • gitlab-duo-chat
  • gitlab-orbit
  • gitlab-semantic-code-search
Share this project:

Updates