Pilot

AI codebase intelligence agent that generates comprehensive onboarding guides for any GitLab repository using Claude Sonnet as external reasoning engine, built on the GitLab Duo Agent Platform.

Comment

Inspiration

The biggest productivity tax in software development isn't writing code — it's understanding someone else's. New developers spend 3-6 months ramping up on unfamiliar codebases. Senior engineers lose 20% of their time to "context tours" for new teammates. Documentation is always outdated.

We asked: what if GitLab could do what a great senior engineer does during a new hire's first week — but in 5 minutes?

Beyond productivity, there's a sustainability angle: every onboarding meeting, every "can you walk me through the code?" session, every duplicated knowledge transfer consumes energy and human attention. Pilot automates away that overhead — reducing the carbon cost of collaboration and freeing senior engineers to do work only they can do.

What It Does

Pilot is a GitLab Duo custom agent AND flow that generates comprehensive onboarding guides for any GitLab repository. It operates in two modes:

Interactive Mode (Duo Chat): Developers can mention @pilot in any issue or MR and immediately get a deep codebase analysis and onboarding guide.

Automated Mode (Trigger-based Flow): A GitLab Duo Workflow is triggered automatically on issues containing specific labels or keywords. No human intervention required — open an issue, get a full guide.

Pilot uses 13 GitLab tools for deep codebase analysis and generates 10-section onboarding guides covering:

  1. Project overview and purpose
  2. Architecture overview with Mermaid.js diagrams
  3. Tech stack breakdown
  4. Key components and modules
  5. Data flow and API routes
  6. Development setup and prerequisites
  7. Contribution guidelines
  8. Testing strategy
  9. Deployment and CI/CD pipeline
  10. Common pitfalls and gotchas

Each section includes confidence scores so readers know how thoroughly Pilot analyzed each area.

How We Built It

Pilot uses a three-phase architecture:

Phase 1 — Explorer: Pilot reads the repository tree, configuration files, package manifests, CI/CD definitions, and README files to build a complete picture of the project structure.

Phase 2 — Analyzer: Pilot traces data flows, maps entry points, identifies API routes, analyzes architectural patterns, and cross-references dependencies to understand how the pieces fit together.

Phase 3 — Publisher: Pilot synthesizes the analysis into a structured Markdown guide with Mermaid.js diagrams, publishes it as an issue comment, creates an ONBOARDING.md file in the repository, and opens a merge request — all automatically.

Pilot is powered by Anthropic Claude via the GitLab Duo Agent Platform, using GitLab's native AI gateway for secure, scalable inference. The agent is defined using GitLab's agent YAML schema and can be customized per-project.

Challenges We Ran Into

  • Context window management: Large repositories can have hundreds of files. We built a smart file prioritization system that focuses on the most architecturally significant files first.
  • Mermaid diagram generation: Getting Claude to produce valid, renderable Mermaid syntax consistently required careful prompting and output validation.
  • Dual-mode architecture: Supporting both interactive (chat) and automated (workflow trigger) modes from the same agent definition required thoughtful separation of concerns.
  • Confidence scoring: Designing a meaningful confidence rubric that reflects genuine uncertainty vs. areas where the codebase is clearly documented.

Accomplishments That We're Proud Of

  • A fully functional dual-mode agent that works in both Duo Chat and as an automated workflow
  • 10-section guides with visual architecture diagrams generated in under 5 minutes
  • 13 GitLab tools integrated into a cohesive analysis pipeline
  • The agent runs entirely within GitLab's native AI infrastructure — no external dependencies

What We Learned

  • GitLab Duo Agent Platform is remarkably capable for building stateful, multi-step AI workflows
  • The separation between agent definition and workflow triggers enables powerful automation patterns
  • Confidence scores significantly improve trust in AI-generated documentation

What's Next for Pilot

  • Incremental updates: Re-run Pilot on PRs to keep onboarding guides current as the codebase evolves
  • Multi-repo analysis: Understand microservice architectures that span multiple repositories
  • Personalized guides: Tailor guides based on the new developer's background (frontend, backend, DevOps)
  • GitLab.com integration: Make Pilot available as a one-click install for any GitLab project

Built With

  • claude-(anthropic)
  • claude-code-cli
  • docker
  • gitlab-ai-gateway
  • gitlab-duo-agent-platform
  • glab-cli
  • mermaid.js
  • node.js
  • python
Share this project:

Updates