We've all been there. You clone a repo you're excited about, open it up, and you're greeted by a README, 40 top-level folders and absolutely no map.
You start clicking around, open a few files that look important, and 45 minutes later you're still not sure where anything actually starts 😅

I've been experimenting with Kiro Crew bots and wanted to take them for a run on a new codebase. For this post we're using the open source HyperFrames project by HeyGen.
It gives users and agents alike the ability to turn HTML, CSS and seekable animations into deterministic MP4s. It's interesting, it's active, and it's big enough to be a little intimidating (perfect test for our Crew bots).

In this post I'll walk you through how I went from a fresh clone to an architecture map and a list of good first issues to contribute in about 10 minutes end to end.

What is a bot?

For those who haven't tried Kiro Crew yet, it is a persistent, open source development workspace that remembers your context and learns how you work. It runs locally or remotely on your own hardware.

On Nov 5th Kiro introduced bots. They're named teammates with their own thread, own memory and their own dashboard that sticks around between sessions.

You can think of it as the difference between a front desk and a workshop. The bot sits at the front desk: it takes your request, plans the work and reviews what comes back. The actual deep reading happens in the workshop, where parallel worker sessions each take a slice of the problem.

Key characteristics:

  • Persistent memory: What the bot learns about the repo today is still there tomorrow.
  • Parallel workers: Instead of one session reading the whole repo top to bottom, several workers dive deep into different areas at once.
  • Tracked items: Each investigation is an item with an acceptance bar, so you're not stuck trusting a vague "done, looks good."

Setting up the bot 🔨

The setup is pretty straightforward. First we'll clone the repo we want the bot to help us understand, and then we can create the bot in the Crew desktop client to get started.

Step 1: Clone HyperFrames

git clone https://github.com/heygen-com/hyperframes.git 

Step 2: Create the bot

From the Kiro Crew desktop client click on Bots to start creation.

I named mine "HyperFrames Guide" and pointed its workspace at my local clone.

Step 3: Give it a one-sentence goal

Here's the exact goal I used:

"Help me understand this codebase well enough to make my first contribution."

One thing worth mentioning: I chose to keep this simple and avoid writing a paragraph here. A tight goal gives the bot a clear finish line, and it does a much better job of breaking work down when it's not guessing what you meant.

Rather than charging off and reading every file, the bot breaks the initial goal into separate tracked items, each with its own acceptance condition. It wasn't just splitting up the work, it was creating an understanding of what "done" would actually look like for each piece.

The Payoff

With my goal in mind, the bot went off and 3 minutes later returned with a detailed report of the HyperFrames repo that I could share with peers, and a plan for my first contribution.

What I liked most is that the bot's Dashboard tab turned into a living onboarding page. Instead of scrolling back through a long chat to find that one useful answer, I can open the dashboard and everything is right there. It maintains the running list of milestones for our shared goal and keeps me updated on what the agent is working on vs what I should be working on.

This process felt like a nice balance of having a teammate alongside you that can be given a direct task, while also maintaining a collaborative symbiosis and transparency into what the agent was actually doing.

Day two: Coming back to progress

Let's say I stopped there for day one. When I come back to my bot the following day I can pick up where we left off by continuing in the chat.

No re-scanning the repo, no re-explaining what HyperFrames is. It answered from what it already knew, the same way a teammate who onboarded with you would. In practice this is the thing that saves the most time working alongside an agent.

Rough edges 😵‍💫

It wasn't all smooth sailing, and I think it's worth calling out where I got tripped up.

The bot went idle after milestone approval. After I approved the bot's goal, it suggested a set of milestones, which I also approved. I expected it to start working right away, but instead it just sat idle waiting for me to prompt it to continue. As a user this was confusing, since the whole point of a bot is unattended work that follows a goal. A quick "go ahead and start" message got it moving again, so if you hit the same thing, give it a nudge.

I've shared this with the Kiro team as product feedback, so hopefully it's smoother by the time you try it.

Try it yourself

Here's a short checklist to try this on any repo:

  1. Clone the repo locally
  2. Create a Crew bot and point its workspace at the clone
  3. Give it a one-sentence goal

From my exploration of this workflow, here are some best practices:

  • Keep the goal small: "Make my first contribution" works better than "understand everything."
  • Let it track separate items: Separate items mean separate acceptance bars, which means fewer hand-wavy answers.
  • Read the dashboard, not the chat: The dashboard is your one stop shop.
  • Come back with follow-ups: The value shows up as you continue to use the bot over time, so use its memory!

Final Takeaway

What would normally take me the better part of an afternoon (and a lot of googling) came down to roughly 10 minutes and a report I can actually come back to. This same pattern works beyond open source onboarding. Think inheriting a service from another team, ramping up during an incident or reviewing a really large PR. All of these tasks can be done in collaboration with your Crew bot.

Don't forget to give me a 🦄 if you got this far and let me know what repo you're looking to dive deep on in the comments!

Additional Resources 📚