Inspiration
Understanding a real-world codebase is one of the hardest parts of software engineering. Documentation is often outdated, architectural decisions are implicit, and new contributors are left to reverse-engineer intent from code alone. With the launch of Gemini 3 and its ability to reason over large codebases, we were inspired to rethink how developers learn from existing repositories - not through static docs or chatbots, but through structured, context-aware understanding. We wanted to build a system that doesn’t just explain code, but teaches why it was built that way.
What it does
Rikai turns any GitHub repository into an interactive learning experience. A user pastes a GitHub repo link, and Rikai: Builds a structural and semantic understanding of the repository Infers the system architecture, execution flows, and engineering principles Identifies design decisions, tradeoffs, and extension opportunities Generates a guided learning module grounded entirely in the actual codebase Instead of generic best practices, rikai produces a real-world walkthrough that helps intermediate developers understand how production systems are designed, structured, and evolved.
How we built it
Rikai is built as a multi-phase, agent-orchestrated system using Python, Streamlit, and the Gemini API. Phase 0 – Repository Indexing Clone the repository Index files, structure, and metadata Apply ignore rules to focus on meaningful code Phase 1 – Static Understanding Parse dependencies Detect entry points and execution signals Analyze code complexity and test coverage Classify the project type Phase 1.5 – Semantic Context Reasoning (Gemini) A dedicated Gemini reasoner builds a high-level semantic understanding of the repository. Purpose, audience, system type Key learning components Notable engineering patterns Phase 2 – Deep Reasoning Orchestration (Gemini) Multiple specialized Gemini reasoners run in sequence: Architecture analysis Execution flow reasoning Engineering principles detection Extension and evolution suggestions Learning module generation Each reasoner performs a distinct cognitive task, and outputs are persisted as structured artifacts for reuse.
Challenges we ran into
Avoiding generic outputs: Early prompts produced vague explanations. We solved this by introducing a dedicated semantic context reasoner that grounds all downstream reasoning. Orchestration design: Ensuring Gemini was used as a reasoning engine—not a prompt wrapper—required clear phase separation and artifact-driven workflows.
Accomplishments that we're proud of
Designed a true multi-agent reasoning pipeline, not a single-prompt app Turned real repositories into production-grade learning modules Built reusable artifacts (repo_index, repo_analysis, repo_context, reasoning) instead of transient chat outputs Created a system that scales from architecture analysis to PR feedback and contributor onboarding
What we learned
Gemini is most powerful when used as an orchestrated reasoning system, not a chatbot Separating semantic understanding from structural analysis dramatically improves output quality Education-focused AI needs grounding, constraints, and explicit intent—otherwise it becomes generic Building explainability into developer tools is just as important as correctness
What's next for rikai
PR-aware reasoning: feedback aligned with the repository’s existing design principles Interactive architecture walkthroughs and visual flow maps Contributor learning paths and “good first issue” generation Long-running agents that track repository evolution over time Live learning experiences using Gemini’s multimodal capabilities
Log in or sign up for Devpost to join the conversation.