--- title: "RepoSwarm: Give AI Agents Context Across All Your Repos" type: post url: "https://robotpaper.ai/reposwarm-give-ai-agents-context-across-all-your-repos/" canonical: "https://robotpaper.ai/reposwarm-give-ai-agents-context-across-all-your-repos/" markdown_url: "https://robotpaper.ai/reposwarm-give-ai-agents-context-across-all-your-repos.md" published: "2025-09-18T04:13:15.000+00:00" updated: "2026-10-22T12:31:48.000+00:00" tags: ["Tools"] author: "Roy Osherove" author_links: ["https://robotpaper.ai", "https://x.com/royosherove", "https://www.linkedin.com/in/osherove/", "https://forms.gle/jQSx5KoXvrVA1JCK7", "https://robotpaper.ai/about-roy.md"] description: "RepoSwarm is an open-source tool that uses Temporal workflows and Claude to analyze hundreds of repos and write architecture docs AI agents can use as context." usage: "Licensed under CC BY 4.0 — reuse, quote and adapt with attribution (Roy Osherove, link to the original post)." license: "https://creativecommons.org/licenses/by/4.0/" --- # RepoSwarm: Give AI Agents Context Across All Your Repos TLDR; [Go see it here](https://github.com/royosherove/repo-swarm). ## Intro Let's say you have 400+ repositories in your company. And you're: - A software architect that needs to understand what monitoring tools are used across all the repositories, **and you want to ask an AI chat to help you** - A Security researcher that needs to understand which 3rd party vendors we're working with for HIPAA compliance, **and you want to ask an AI agent to help you** - A developer working on a new feature that depends on multiple services across multiple repositories, and you want to understand if you're using them correctly, or their contracts, **and you want to ask an AI agent to help you.** - **An AI coding agent** trying to generate a new feature and needing as context multiple repositories and their structure, how they're built and contracts - **An AI agent** trying to reason about and generate a list of compliance or security or other reports that span multiple repositories Along with a [couple](https://github.com/mosher) of [friends](https://github.com/Idandos) from [work](https://verbit.ai/), we created [RepoSwarm](https://github.com/royosherove/repo-swarm). RepoSwarm is an AI powered multi-repo architecture discovery platform that generates its output in a specialized output repository that you can use for agent context. Its purpose is to create context for AI agents to better help with reasoning about very complex multi-repo organizations (hundreds of repositories) and describe dependencies, security issues, architecture, tooling, monitoring, AI and ML workloads, infrastructure and any other thing we can ask as a prompt. To accomplish this, RepoSwarm uses a series of workflows using the temporal workflow engine. ## The Problem with Architecture "Documentation" If you're like me and most companies I've ever worked with, your architecture documentation is either: - Six months out of date - Scattered across 17 different wiki pages - Living entirely in Bob's head (and Bob left the company) - All of the above Also, **it's not fit for AI agent consumption.** ## The Problem Nobody Has Time to Fix What if your repositories could document themselves, continuously, intelligently? Enter **RepoSwarm**. RepoSwarm is an open-source project that: 1. Crawls your GitHub (private and public) repositories daily in search of changes 2. Analyzes them using [Claude Code SDK](https://docs.anthropic.com/en/docs/claude-code/sdk/sdk-overview) (you can control which model) 3. Generates standardized architecture documentation in the form of a markdown file per repo. 4. Stores it all in a searchable format 5. Runs forever until you tell it to stop 6. You can configure it to run any series of investigations on repos you wish , and it will only run them when there are new commits, or a new investigation type is added or changed. That's it. No magic. No "revolutionary paradigm shifts." Just a practical solution to a real problem. ## How It Works The system is built on [**Temporal**](https://docs.temporal.io/) - if you haven't used Temporal yet, think of it as something like [N8N](https://n8n.io/) (but code-first) or [airflow](https://airflow.apache.org/), but usually used for production workflows. Temporal orchestrates workflows in a code-first manner (no visual designer). Workflows can run for hours, days, or indefinitely without losing state. Here's what it looks when you run it locally and go to the local temporal server on your machine: ![Temporal UI listing RepoSwarm workflows running: the main continuous workflow and single-repo investigations](https://robotpaper.ai/content/images/2025/09/image-35.png) *main workflow and related sub workflows running* ![Temporal event history for the main RepoSwarm investigate-repos workflow with its child workflows](https://robotpaper.ai/content/images/2025/09/image-38.png) *When you zoom into the main workflow, it looks like this* ![Temporal event history of a single RepoSwarm repo investigation running its analysis activities](https://robotpaper.ai/content/images/2025/09/image-37.png) *This is what a single repo investigation flow looks like* RepoSwarm flow is straightforward: - **Discovery Phase**: RepoSwarm looks at your **repos.json and also queries GitHub** for all the private and public github repos under your organization or account. It auto-selects only repos that have at least one commit in the past 12 months. ![RepoSwarm repos.json config listing repositories with URL, description and type](https://robotpaper.ai/content/images/2025/09/image-46.png) - **Skipping Phase**: Skipped repos are marked in skipped\_repos.json and will be comprised of: \- auto-skipped repos due to no activity in past 12 months) \- auto-skipped repos due to being archived \- repos you explicitly tell RepoSwarm to skip (you can put any comment you want): ![RepoSwarm skip_repos.json listing repos skipped as archived or with no commits in the past year](https://robotpaper.ai/content/images/2025/09/image-48.png) - **Smart Analysis**: in repos.json, you can set a "type" for a repo, so it gets extra investigations. for example, mobile repos will get more investigations relating to mobile specific architecture questions, and infrastructure as code repos will get infra related arch investigations. A React app doesn't need the same questions as a Kubernetes config repo. - **Prompt Result Caching**: Already analyzed this repo? Same commit? Same Prompts? Skip it. We're not wasting tokens. RepoSwarm keeps state snapshot pairs for each commit+(prompt+prompt-version) pairs, so if there is a new commit, all prompts will run against that repo, but if there's a new prompt, or a new prompt version, only that new prompt will execute against that repo, and all other investigations will be skipped , returning the cached result from previous run. Caching can use DynamoDB or (when running locally) local file system /temp directory. - **Prompt Versioning:** Prompt files contain the prompt version as the first line as a barbaric but effective mechanism to trigger new investigations for that prompt, and avoiding creating a dependency on specific tools like [LangFuse](https://langfuse.com/). ![RepoSwarm deployment.md prompt instructing the model to analyze CI/CD and deployment pipelines](https://robotpaper.ai/content/images/2025/09/image-49.png) - **Documentation Generation**: Creates `repo-name.arch.md` files and commits them to a \[target-repo\] that you specify. ![Generated is.arch.md architecture document in the RepoSwarm results hub repo on GitHub](https://robotpaper.ai/content/images/2025/09/image-47.png) ## Adding new prompts add a new prompt either under prompts/shared or prompts/specialized-folder-name, then add the new prompt to base\_prompts.json or the /prompts/specialize-folder-name/prompts.json ![RepoSwarm prompts folder tree with shared and specialized prompts for backend, frontend, mobile and infrastructure](https://robotpaper.ai/content/images/2025/09/image-43.png) All repos will be analyzed by all prompts in base\_prompts, followed by any specialized prompts if their repo\_type is named under one of the prompts/folder like "mobile" or "libraries". ### Example: base\_prompts ```json { "processing_order": [ { "name": "hl_overview", "file": "../shared/hl_overview.md", "description": "High level overview of the codebase" }, { "name": "module_deep_dive", "file": "../shared/module_deep_dive.md", "description": "Deep dive into modules", "context": [ {"type": "step", "val": "hl_overview"} ] }, { "name": "dependencies", "file": "../shared/dependencies.md", "description": "Analyze dependencies and external libraries", "context": [ {"type": "step", "val": "hl_overview"} ] }, { "name": "ml_services", "file": "../shared/ml_services.md", "description": "3rd party ML services and technologies analysis", "context": [ {"type": "step", "val": "hl_overview"} ] }, { "name": "feature_flags", "file": "../shared/feature_flags.md", "description": "Feature flag frameworks and usage patterns analysis", "context": [ {"type": "step", "val": "hl_overview"} ] }, { "name": "prompt_security_check", "file": "../shared/prompt_security_check.md", "description": "LLM and prompt injection vulnerability assessment", "context": [ {"type": "step", "val": "hl_overview"}, {"type": "step", "val": "ml_services"} ] } ] } ``` Notice how we can actually inject the output of other investigation prompt results into the context of other prompts (see prompt\_security\_check.context array). ### Example: mobile prompts And here's a mobile specific set of prompts, that will run for any repo in repos.json marked as "mobile" type, on top of everything in base\_prompts.json. ```json /prompts/mobile/prompts.json { "extends": "../base_prompts.json", "additional_prompts": [ { "name": "ui_and_navigation", "file": "ui_and_navigation.md", "description": "UI architecture and navigation patterns" }, { "name": "api_and_network", "file": "api_and_network.md", "description": "API integration and network communication" }, { "name": "device_features", "file": "device_features.md", "description": "Native device features and capabilities" }, { "name": "data_and_persistence", "file": "data_and_persistence.md", "description": "Data persistence and state management" } ] } ``` ## Output: The Architecture Hub Repo All the generated documentation goes to a central repository that you decide on. Think of it as your architecture wiki that updates itself. The companion project [repo-swarm-sample-results-hub](https://github.com/royosherove/repo-swarm-sample-results-hub) shows how this works. ![repo-swarm-sample-results-hub GitHub repository with generated .arch.md files for each analyzed repo](https://robotpaper.ai/content/images/2025/09/image-50.png) You can query it, search it, or just browse it like any other repository. Except this one is always up to date. ## Using RepoSwarm Output as Agent Context As a first step, I like to attach [the output repo](https://github.com/royosherove/repo-swarm-sample-results-hub) into my cursor workspace as an added project, and ask it questions or give it as context to the coding agent as I plan complicated features in the chat. ## Future plans include: - Adding a Repo-bot in slack with backing RAG based on the output repo - Add the context into Cursor, Claude and Codex agents automatically - Exposing an MCP to the Repo as a simple context scanning tool - Creating deeper investigations as RepoSwarm works so that it can "jump" and investigate related repos while investigating a specific repo, to get even more context. - more? ## Real-World Use Cases - Onboarding New Developers to all our repositories - Architecture Reviews - Compliance Audits - Knowledge Transfer - Providing extra context to coding agents or as an MCP server related to architecture ## What This Is NOT - It's not a code generator - It won't fix your architecture (just document it) - It's not a replacement for human insight ## Contributing The project is open-source (Apache-2). Contributions are welcome. ### Areas that need help: - Additional analysis prompts - Integration with other AI providers (right now using claude code SDK because the tooling flow just works) - Performance optimizations ## Outro: [Go see it here](https://github.com/royosherove/repo-swarm). --- ## About the author **Roy Osherove** - Senior Solutions Architect at AWS working on AI for production and AI-driven development; author of The Art of Unit Testing and Elastic Leadership, with about 20 years of consulting and training on unit testing, TDD, team leadership and continuous delivery. ### Sites - [RobotPaper](https://robotpaper.ai/): This blog: AI patterns and anti-patterns, AI and coding agents, and engineering leadership. - [osherove.com](https://osherove.com): Roy's personal site. Author of The Art of Unit Testing and Elastic Leadership; consulting and training on unit testing, TDD, team leadership and continuous delivery, plus about 20 years of blog posts. - [The Art of Unit Testing](https://www.artofunittesting.com): The Art of Unit Testing, 3rd Edition (Manning): readable, maintainable, trustworthy unit tests, plus TDD workshops in C#, JavaScript, Java and Kotlin. - [5whys.com](https://www.5whys.com): Roy's writing on software team leadership: self-organizing teams, surviving chaos, learning mode and the Elastic Leadership model. - [Pipeline Driven](https://pipelinedriven.org): Continuous delivery and DevOps practices: build patterns, pipeline-friendly testing, DevOps metrics and enterprise DevOps. - [Elastic Leadership](https://www.elasticleadership.com): Elastic Leadership, Roy's framework for software team leaders (survival, learning and self-organizing modes). ### Social - X: [https://x.com/royosherove](https://x.com/royosherove) - LinkedIn: [https://www.linkedin.com/in/osherove/](https://www.linkedin.com/in/osherove/) ### Contact - Contact form: [https://forms.gle/jQSx5KoXvrVA1JCK7](https://forms.gle/jQSx5KoXvrVA1JCK7) ### License Content on robotpaper.ai is licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/): reuse, quote and adapt with attribution (Roy Osherove, link to the original post). More about Roy and his other sites and projects: [https://robotpaper.ai/about-roy.md](https://robotpaper.ai/about-roy.md)