Propose a mono-repository#811
Conversation
|
|
||
| - **Context switching**: devs and agents lose context every time they jump between repos. Setting up a new worktree means cloning N repositories and making sure they're all on the right branches — that's friction that scales with the number of repos involved. | ||
| - **Fragmented PRs**: one logical change becomes multiple PRs that have to be reviewed and merged in the right order. | ||
| - **Docs lag behind code**: docs live in a separate repo, so they end up being a follow-up step rather than part of the feature branch. We also can't always finish doc work until the code merges (or do complex branch pointing). |
There was a problem hiding this comment.
nit: even with docs in monorepo, i'd do my docs later :p
I don't want to keep rewriting and re-reviewing docs text while my feature is being reviewed
There was a problem hiding this comment.
or have an agent auto open a new pr for docs prs :) ideally we never have to write new docs prs
| - **Fragmented PRs**: one logical change becomes multiple PRs that have to be reviewed and merged in the right order. | ||
| - **Docs lag behind code**: docs live in a separate repo, so they end up being a follow-up step rather than part of the feature branch. We also can't always finish doc work until the code merges (or do complex branch pointing). | ||
| - **Duplicated CI/tooling**: shared workflows and configs get duplicated or need a separate `devtools` repo to coordinate. | ||
| - **Agent productivity**: agentic tools work best with the full project context in one checkout. Splitting the SDK across repos means the agent doesn't have the full picture out of the gate. |
There was a problem hiding this comment.
nit: just pull the repos in the agent workspace
|
|
||
| The candidates for consolidation are the repos tightly coupled to the SDK, the ones where we're doing a lot of overlapping work: | ||
| - `sdk-python`, `sdk-typescript`, `docs`: these are the core. Cross-repo work here is constant. | ||
| - `samples`, `mcp-server`, parts of `devtools`: probably move these too. They're closely tied to SDK development. |
There was a problem hiding this comment.
I'm okay with devtools, not sure about samples and mcp server. How do we set up permissions? I don't want to be the bottleneck for these components
| - **Fragmented PRs**: one logical change becomes multiple PRs that have to be reviewed and merged in the right order. | ||
| - **Docs lag behind code**: docs live in a separate repo, so they end up being a follow-up step rather than part of the feature branch. We also can't always finish doc work until the code merges (or do complex branch pointing). | ||
| - **Duplicated CI/tooling**: shared workflows and configs get duplicated or need a separate `devtools` repo to coordinate. | ||
| - **Agent productivity**: agentic tools work best with the full project context in one checkout. Splitting the SDK across repos means the agent doesn't have the full picture out of the gate. |
There was a problem hiding this comment.
Someone worked on a cool project internally called MetaRepo. Can possibly be helpful for this agent problem
|
|
||
| ### What becomes harder | ||
|
|
||
| **Overlap and confusion** is the main concern. No major SDK project puts multiple language implementations in a single cross-language monorepo (see [Appendix A](#appendix-a-how-do-other-sdk-projects-handle-this)), so there's inherent unfamiliarity here. |
There was a problem hiding this comment.
no other sdk uses wasm to serve multiple languages tho
|
|
||
| **Overlap and confusion** is the main concern. No major SDK project puts multiple language implementations in a single cross-language monorepo (see [Appendix A](#appendix-a-how-do-other-sdk-projects-handle-this)), so there's inherent unfamiliarity here. | ||
|
|
||
| Additional friction: |
There was a problem hiding this comment.
permissions and reviews for non-sdk repos/projects
| - `samples`, `mcp-server`, parts of `devtools`: probably move these too. They're closely tied to SDK development. | ||
|
|
||
| The repos that stay independent are the ones where there isn't a lot of overlap with day-to-day SDK work: | ||
| - `evals`, `agent-builder`, `agent-sop`, `tools`: these are more standalone projects. |
There was a problem hiding this comment.
evals sticks out as one which might be considered for the monorepo. For visibility, for docs, for future workflows using evals, etc
|
|
||
| The cons are real but manageable — CI complexity is solvable with path-based triggers, GitHub UX limitations can be mitigated with labels and naming conventions, and the migration is a one-time cost. The speed gains from co-location are ongoing: every feature, every port, every doc update benefits from having everything in one checkout. For a single team shipping across multiple languages with heavy agentic development, that daily velocity improvement outweighs the friction. | ||
|
|
||
| Additionally, **WASM is already pushing us here**. The TypeScript SDK has started moving towards a monorepo structure on its own because the WASM work requires co-locating TypeScript and Python code. `sdk-typescript` already has folders for the projected Python API from TS (`strands-ts`). Continue this pattern and go all in on a mono repository. |
There was a problem hiding this comment.
because of this, I'd focus more on how, rather than why. wasm with multiple repos would be terrible experience to develop/maintain
There was a problem hiding this comment.
I think the question still stands for other repositories, however - which is what I'd focus on for now.
I want to evaluate the downsides/repercussions than just focusing on WASM
| ### What becomes easier | ||
|
|
||
| - **Agentic development**: agents don't need multi-repo setups or special configuration to have full context. Porting code from Python to TypeScript (or vice versa) is much easier when the agent has both implementations open. Generating docs is more useful when the agent has the source code right there. | ||
| - **Unified PRs**: documentation lives in the feature branch alongside the code. Doc development can be done in tandem with implementation rather than being a separate step. |
There was a problem hiding this comment.
The doc is highlighting docs, but the WASM/wit work and future languages seems like one of the biggest sells to me
| - **Unified PRs**: documentation lives in the feature branch alongside the code. Doc development can be done in tandem with implementation rather than being a separate step. | ||
| - **Centralized information**: one place for skills, agents, patterns, etc. | ||
|
|
||
| ### What becomes harder |
There was a problem hiding this comment.
It may be more challenging/confusing for external contributors. tbd
|
|
||
| The cons are real but manageable — CI complexity is solvable with path-based triggers, GitHub UX limitations can be mitigated with labels and naming conventions, and the migration is a one-time cost. The speed gains from co-location are ongoing: every feature, every port, every doc update benefits from having everything in one checkout. For a single team shipping across multiple languages with heavy agentic development, that daily velocity improvement outweighs the friction. | ||
|
|
||
| Additionally, **WASM is already pushing us here**. The TypeScript SDK has started moving towards a monorepo structure on its own because the WASM work requires co-locating TypeScript and Python code. `sdk-typescript` already has folders for the projected Python API from TS (`strands-ts`). Continue this pattern and go all in on a mono repository. |
There was a problem hiding this comment.
WASM's current goal is to increase development velocity by decreasing the burden of maintaining separate repositories. What happens when we introduce new languages. Do we continue to follow this monorepo model and have the strands-java, strands-go, etc. as well?
| - **Fragmented PRs**: one logical change becomes multiple PRs that have to be reviewed and merged in the right order. | ||
| - **Docs lag behind code**: docs live in a separate repo, so they end up being a follow-up step rather than part of the feature branch. We also can't always finish doc work until the code merges (or do complex branch pointing). | ||
| - **Duplicated CI/tooling**: shared workflows and configs get duplicated or need a separate `devtools` repo to coordinate. | ||
| - **Agent productivity**: agentic tools work best with the full project context in one checkout. Splitting the SDK across repos means the agent doesn't have the full picture out of the gate. |
There was a problem hiding this comment.
Is it actually true? Given the prompt the agent could scan through the parent repo / org, then it might perform better?
|
|
||
| ### What do other SDK projects do? | ||
|
|
||
| No major SDK project puts multiple language implementations in a single cross-language monorepo. The industry standard is monorepo-per-language (Azure, Google Cloud, LangChain) or fully separate repos per language. See [Appendix A](#appendix-a-how-do-other-sdk-projects-handle-this) for the full survey. |
There was a problem hiding this comment.
I would make the argument we still are one language. TypeScript is the feature language and anything else is a build artifact.
| - `samples`, `mcp-server`, parts of `devtools`: probably move these too. They're closely tied to SDK development. | ||
|
|
||
| The repos that stay independent are the ones where there isn't a lot of overlap with day-to-day SDK work: | ||
| - `evals`, `agent-builder`, `agent-sop`, `tools`: these are more standalone projects. |
There was a problem hiding this comment.
I'd lean into independent as of now. If we decide to make strands-evals is only for strands then I'd be fine having it into strands mono-repo. Is the effort/cost high if we move the repo afterwards?
|
|
||
| ### Recommendation | ||
|
|
||
| The cons are real but manageable — CI complexity is solvable with path-based triggers, GitHub UX limitations can be mitigated with labels and naming conventions, and the migration is a one-time cost. The speed gains from co-location are ongoing: every feature, every port, every doc update benefits from having everything in one checkout. For a single team shipping across multiple languages with heavy agentic development, that daily velocity improvement outweighs the friction. |
There was a problem hiding this comment.
We are aiming for feature parity across languages (TS and Python). However, I am not sure that we will ALWAYS have feature parity. I see use-cases where certain features are only present/developed in a single sdk language (whether thats due to language constraint or somthing else). A monorepo with feature divergence makes it difficult to justify to customers why that is
| Additional friction: | ||
|
|
||
| - **File discovery noise**: searching for a single construct returns many results. Even navigating to a file will surface many of the same files across SDK implementations. This is probably the biggest day-to-day annoyance. | ||
| - **CI complexity**: multiple different things being built and tested in one repo. Pipelines require more custom code/configs to handle per-project builds, and this usually requires different tooling which can be more complex to set up and maintain. |
There was a problem hiding this comment.
what tooling do we have for this? can we mitigate it? we should be able to right? we won't be the first monorepo on github
Documentation Preview ReadyYour documentation preview has been successfully deployed! Preview URL: https://d3ehv1nix5p99z.cloudfront.net/pr-cms-811/docs/user-guide/quickstart/overview/ Updated at: 2026-05-05T17:14:02.316Z |
| - A [2026 analysis](https://tianpan.co/blog/2026-04-17-coding-agents-monorepo-context-window) of coding agents in monorepos found that the core failure mode is agents calling interfaces that were renamed in other parts of the codebase they can't see. Cross-repo splits make this worse because the agent literally cannot access the other repo's current state. | ||
| - Research on agent-assisted PRs ([arxiv](https://arxiv.org/abs/2509.14745)) shows 83.8% of agent-assisted PRs are accepted, with 54.9% merged without modification — but this works best when the agent has full context of the change surface. | ||
|
|
||
| **The counterargument:** Large monorepos can *hurt* agents too. Context windows have limits (100K–2M tokens), and a 50-service monorepo can exceed what an agent can effectively attend to. The "lost in the middle" problem means agents treat content near the middle of long contexts less reliably than content at the edges. For Strands specifically, the combined SDK + docs + samples is likely well within manageable context size, but it's worth monitoring. |
There was a problem hiding this comment.
This can be solved by well-constructed steering files, which can be cross-repo with a monorepo
|
|
||
| ### The Agentic Development Argument | ||
|
|
||
| This is where the standard industry wisdom may not apply to us. The strongest argument for consolidation isn't about CI or versioning — it's about agent context. |
There was a problem hiding this comment.
Do we think this is the strongest argument? Staging a monorepo in a workspace is pretty easy as is. I think the other arguments (single code change many projects) are more convincing to me
| - **Migration effort**: real work to get it all working. Changes the ground underneath existing PRs. Issues need to be bulk migrated. Versioning/history gets noisier since git log fills up with commits on unrelated trees. | ||
| - **GitHub is built around repos, not projects**: a monorepo flattens several repo-level abstractions that don't have good sub-repo equivalents. | ||
| - *Releases*: tags and GitHub Releases share one timeline, even when sub-projects release independently. | ||
| - *Issues*: users filing a Python SDK bug land in the same tracker as TypeScript and docs issues — no implicit scoping. |
There was a problem hiding this comment.
Given the feature parity, we'll have to check whether the bug exists in both repos, which waste a bit of effort.
| @@ -0,0 +1,302 @@ | |||
| # Consolidate Strands SDK Repos into a Mono Repository | |||
There was a problem hiding this comment.
Did we solve the "which repo turns into the monorepo in this doc"
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
|
|
||
| ### Which Repos Move | ||
|
|
||
| The candidates for consolidation are the repos tightly coupled to the SDK, the ones where we're doing a lot of overlapping work: |
There was a problem hiding this comment.
Issue: The "Which Repos Move" section uses vague language ("probably move these too", "parts of devtools") which makes it hard to evaluate the actual scope of the proposal.
Suggestion: Be explicit about which repos are in-scope vs. out-of-scope for the initial migration vs. future phases. A table with columns like Repo | Phase | Rationale would make this concrete and actionable. The ambiguity here is generating multiple review threads (evals, samples, mcp-server) that could be resolved with clearer scoping.
|
|
||
| ### Recommendation | ||
|
|
||
| The cons are real but manageable — CI complexity is solvable with path-based triggers, GitHub UX limitations can be mitigated with labels and naming conventions, and the migration is a one-time cost. The speed gains from co-location are ongoing: every feature, every port, every doc update benefits from having everything in one checkout. For a single team shipping across multiple languages with heavy agentic development, that daily velocity improvement outweighs the friction. |
There was a problem hiding this comment.
Issue: No success criteria or metrics are defined. Without these, it's hard to evaluate whether the migration achieved its goals or whether to revisit the decision later.
Suggestion: Add a "Success Metrics" section with measurable outcomes, e.g.:
- Reduction in time-to-merge for cross-cutting features
- Reduction in number of PRs needed for a single logical change
- Developer satisfaction / friction surveys
- CI pipeline reliability and speed
Also define a timeframe for reassessment (e.g., "revisit after 6 months if per-language teams form").
| - **Unified PRs**: documentation lives in the feature branch alongside the code. Doc development can be done in tandem with implementation rather than being a separate step. | ||
| - **Centralized information**: one place for skills, agents, patterns, etc. | ||
|
|
||
| ### What becomes harder |
There was a problem hiding this comment.
Issue: The document doesn't address the impact on the external open-source community. Strands is an OSS project — external contributors currently find their way to sdk-python or sdk-typescript naturally. A cross-language monorepo changes discoverability, issue filing, and contribution patterns.
Suggestion: Add a subsection under "What becomes harder" addressing:
- How external contributors discover and navigate the monorepo
- How issue triage works when all issues land in one tracker
- Whether the individual SDK repos will remain as read-only mirrors or archives (common pattern for discoverability)
- Impact on GitHub stars/community signal (briefly mentioned in L61 but not with mitigation)
| @@ -0,0 +1,302 @@ | |||
| # Consolidate Strands SDK Repos into a Mono Repository | |||
There was a problem hiding this comment.
Issue: The document deviates from the design document template defined in designs/README.md. Missing sections: Issue link in the header, explicit Alternatives Considered section, and Willingness to Implement.
Suggestion: While this is an infrastructure/process proposal rather than a feature, aligning with the template helps reviewers find information in expected places. At minimum, consider adding an explicit "Alternatives Considered" section that summarizes the options (monorepo-per-language à la Azure, status quo with better tooling, partial consolidation of just sdk-python + sdk-typescript) with brief tradeoff notes — the Appendix A material is thorough but buried in a collapsible block.
|
|
||
| But those projects have dedicated teams per language. Azure has a Python team and a separate JS team. Google Cloud has separate teams per language. Their reasons for staying separate — independent contributor pools, independent release cadences, independent backlogs — don't apply to us. We're a single team implementing the same features across multiple languages, shooting for feature parity. That's a fundamentally different workflow, and it's the reason co-location helps us where it wouldn't help them. | ||
|
|
||
| This whole argument falls apart if that stops being true. If we eventually have dedicated per-language teams, or want the SDKs to diverge, then co-location is just noise and we should revisit. |
There was a problem hiding this comment.
Issue: The document states the assumption "every member is expected to implement features in all SDKs" and "we release both SDKs in lockstep for feature parity" as current facts, then acknowledges "This whole argument falls apart if that stops being true" (L77). However, there's no discussion of how likely this is to change or what the exit strategy looks like.
Suggestion: Given that multiple reviewers have raised concerns about future language additions and feature divergence, consider adding a brief "Reversibility" section. How expensive is it to split the monorepo back out if the team structure changes? Is there a "point of no return" where shared tooling makes separation impractical?
|
|
||
| We have a single team working across both languages, where every member is expected to implement features in all SDKs. Docs are tightly coupled to those implementations, and both humans and agents benefit from co-location. | ||
|
|
||
| Given all of that, we should consolidate the core SDK repos into a single mono repository. |
There was a problem hiding this comment.
Issue: The document thoroughly covers why to consolidate but is thin on how. For a change of this magnitude, reviewers need to evaluate feasibility and risk alongside motivation.
Suggestion: Add a "Migration Plan" or "Implementation" section covering:
- Phasing strategy (e.g., start with sdk-python + sdk-typescript + docs, then expand)
- Directory layout in the target monorepo
- How existing open PRs/issues will be handled
- CI/CD setup approach (path-based triggers, separate workflows per project)
- Rollback plan if the migration creates unforeseen problems
- CODEOWNERS / permission model (multiple reviewers raised this concern)
|
Assessment: Comment (Request Revisions) The research and analysis are thorough — the industry survey and size benchmarks are genuinely useful reference material. The case for consolidation is well-argued. However, this document is heavy on motivation and light on execution, which makes it difficult for the team to approve with confidence. Review Themes
The appendices are excellent and will serve as valuable reference material regardless of the final decision. |
|
|
||
| The candidates for consolidation are the repos tightly coupled to the SDK, the ones where we're doing a lot of overlapping work: | ||
| - `sdk-python`, `sdk-typescript`, `docs`: these are the core. Cross-repo work here is constant. | ||
| - `samples`, `mcp-server`, parts of `devtools`: probably move these too. They're closely tied to SDK development. |
| - `samples`, `mcp-server`, parts of `devtools`: probably move these too. They're closely tied to SDK development. | ||
|
|
||
| The repos that stay independent are the ones where there isn't a lot of overlap with day-to-day SDK work: | ||
| - `evals`, `agent-builder`, `agent-sop`, `tools`: these are more standalone projects. |
There was a problem hiding this comment.
Team aligned include evals from the beginning - still want to know what the post-1.0 story is
8 participants
Description
Related Issues
Type of Change
Checklist
npm run devBy submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.