Briefd

an AI-powered repository onboarding tool

Comment

Inspiration

The idea came from a universal developer pain point: joining a new project and facing thousands of files with no clear starting point. The README is sparse. The architecture is undocumented. Senior engineers spend hours answering the same onboarding questions for every new hire. Open source contributors give up before submitting their first PR because they can't figure out where to start.

We wanted to build a tool where you paste a repo URL and an AI agent — not a chatbot, but a coordinated system of specialized agents — reads the entire codebase and delivers a complete onboarding briefing. Not a summary. A full, structured, voice-enabled experience that gets you from "what is this?" to "I'm ready to contribute" in minutes.

What It Does

briefd is an AI-powered repository onboarding tool. You paste a public GitHub repository URL, and an AI agent named Max orchestrates four specialized sub-agents to analyze the entire codebase and produce a rich onboarding snapshot.

Key capabilities:

  • Multi-agent analysis pipeline: Five AI agents work in parallel — a Code Analysis Agent maps the structure, a Documentation Agent generates guides, a Voice Agent creates audio walkthroughs, an Automation Agent scans the repo's web presence, and a Main Agent orchestrates everything and handles user interaction.

  • Voice-first experience: Every section has a voice brief button. Max can narrate the architecture, walk you through setup step-by-step, or have a live voice conversation about the codebase — all powered by Nova 2 Sonic's bidirectional speech-to-speech streaming. Three voice personas (Alex Carter, Jordan Taylor, Morgan Lee) adapt tone per page.

  • Semantic search: Ask "how does authentication work?" and find relevant code, docs, and architecture sections simultaneously. Nova Multimodal Embeddings indexes everything into a unified 1024-dimension vector space.

  • Interactive architecture diagrams: Clickable node diagrams with AI-powered explanations. A guided tour walks through the system step-by-step with voice narration. Toggle between interactive view and Mermaid source.

  • Browser automation: Nova Act scans the repo's GitHub Discussions, "Used by" dependents, package ecosystem stats on npm/PyPI/crates.io, and recent PR review context — data that only exists in rendered browser pages.

  • RAG-powered chat: Ask Max questions grounded in the actual codebase via retrieval-augmented generation. Chat history persists across sessions.

  • Progressive 8-page experience: Each page has one cognitive goal — from curiosity (Arrival) through orientation (Overview) to contribution readiness (Setup & Readiness). Every page includes AI guide banners, confidence badges, and voice interaction.

  • Readiness scoring: An AI-calculated score (0-100%) based on available documentation — setup guide completeness, gotchas coverage, key file identification, architecture documentation.

How We Built It

Architecture

briefd has three standalone components:

briefd_v2/
├── backend/     ← Agent system (Python, standalone)
├── webapp/      ← Web API layer (FastAPI → Lambda handler)
└── frontend/    ← React UI (TypeScript + Vite → S3 + CloudFront)

The agent system runs independently and can be invoked via CLI, Lambda, or any entry point. The web app provides 17 REST endpoints on top of it. The frontend is a static React SPA that talks to the API.

Amazon Nova Models — The Core Intelligence

We use four Amazon Nova foundation models through Amazon Bedrock, each handling a distinct capability:

Model Role What It Does in briefd
Nova 2 Lite Reasoning Code structure analysis, tech stack detection, architecture description + Mermaid diagram generation, documentation synthesis (summary, setup guide, gotchas), RAG-powered chat, repo signal extraction, narration script generation, readiness scoring
Nova 2 Sonic Voice Audio brief generation per section, live speech-to-speech conversation, guided tour narration, "Talk to Max" voice interaction. Uses bidirectional streaming via the Bedrock SDK with three voice personas (matthew, ruth, tiffany)
Nova Multimodal Embeddings Search 1024-dimension text embeddings for all snapshot sections, semantic search across code/docs/architecture, RAG context retrieval for grounded chat answers, browser insight indexing
Nova Act Automation GitHub Discussions extraction, "Used by" dependents scanning, package ecosystem stats from npm/PyPI/crates.io, PR review context extraction. Graceful fallback if unavailable

Agent Pipeline

Repo URL → Git Clone → Code Analysis Agent (Nova 2 Lite)
                      → Documentation Agent (Nova 2 Lite)
                      → Automation Agent (Nova Act + Nova 2 Lite)
                      → Embeddings Service (Nova Multimodal Embeddings)
                      → Voice Agent (Nova 2 Sonic)
                      → Store to DynamoDB + S3
                      → Snapshot Ready

Built With

Share this project:

Updates