Brook

We are The Python's, and we built Brook, a PyCharm plugin designed to make developer onboarding seamless.

Starting a new job or jumping into an existing project usually involves a steep learning curve. You have to figure out how the codebase is structured, how the backend works, and how it communicates with the frontend. It is overwhelming and time-consuming. Brook solves this by acting as an interactive AI mentor right inside your IDE, guiding you through a new codebase so you can actually learn it by doing.

Inspiration

We have all experienced the daunting task of onboarding onto a massive, unfamiliar codebase. You stare at hundreds of files, completely unsure of where to begin.

While the current industry trend is focused on using AI to write code for developers, we realized that this actually hurts the onboarding process by removing the developer from the equation. We were inspired to build a tool that flips the script: instead of giving you the answers, the AI creates a safe environment for you to break things, fix them, and learn the architectural patterns yourself.

How we built it

We developed Brook as a PyCharm plugin that operates in three main phases:

Context & Personalization: We feed a target GitHub repository (like a FastAPI application) into the model to use as context. We then assign Brook a specific developer specialty (e.g., frontend, backend, authentication) to ensure the onboarding is highly relevant to the user's actual job role.

Generating the Exercise: Brook automatically modifies a file in the codebase to create a realistic issue and generates an HTML brief. This brief acts as the assignment, providing a realistic QA bug report, examples of broken output, a roadmap of which files to check, and a starting hint.

The Active Learning Loop: The user takes over, navigating the directories to solve the exercise. As the user writes code in PyCharm, the plugin tracks changes in the background. We built the system to seamlessly feed these changes back to the AI model using git diff.

Once the user submits their work, Brook internally checks the code against a hidden solution file it generated previously. If correct, the developer moves on to the next challenge!

Challenges we ran into

Tracking User Progress: We had to figure out how the AI could "watch" the user code without being intrusive or losing context. We experimented with different methods of reading file states but ultimately found that integrating git diff was the most reliable and successful solution for capturing precise user changes.

Restraining the AI: LLMs are naturally designed to be helpful by providing complete answers. A significant challenge was building strict guardrails around our core rule: At no point will Brook provide the code. We had to carefully prompt and constrain the built-in Chatbox and Hint buttons to ensure they only guided the user rather than solving the problem for them.

What we learned

We learned that the true power of AI in education and onboarding isn't in automation, but in active mentorship. By building Brook, we discovered how to effectively parse and utilize repository context to generate dynamic, solvable problems on the fly. More importantly, we proved that developers are still incentivized to learn by getting their hands dirty, all they need is the right guide to point them in the right direction.

Built With

• fastapi
• kotlin
• python