Last updated 13 October 2026
Configure Claude Code for a monorepo
Monorepos create context challenges for agents
A large monorepo often confuses a coding agent because the root directory contains too many conflicting signals. You might have a React frontend in one folder and a Go backend in another. When you run Claude Code from the root, the agent sees every configuration file and every dependency list. It might try to run npm commands on your Go code or look for Python tests in your TypeScript package. This leads to wasted tokens and incorrect tool usage.
The main issue is the sheer volume of files. If the agent uses the Glob tool or Grep tool across the entire tree, it quickly hits context limits. You need a way to tell the agent where it is and what the local rules are. Without specific instructions, the agent defaults to generic assumptions that do not fit your specific architecture or build pipeline. This makes the agent less efficient and more likely to suggest code that does not follow your project standards.
Root instructions set the baseline for the whole repo
Every monorepo needs a CLAUDE.md file in the root directory. This file should define the high-level architecture and the locations of the main packages. You should explain that the repository is a monorepo and list the directories for the frontend, backend, and shared libraries. This helps the agent understand the relationship between different parts of the code when it first scans the project.
The root CLAUDE.md should also contain global style guides and naming conventions. If every package uses the same linting rules or the same branch naming strategy, put those rules here. The agent reads this file at the start of every session. Use this space to define how to run global tasks like an overall build or a full test suite using the Bash tool. Providing these high-level rules ensures consistency across every package in the repository.
Subdirectory instructions isolate package logic
Claude Code looks for a CLAUDE.md file in the current directory and any parent directories. By placing a separate CLAUDE.md inside a specific package folder, you provide localized context. If you are working in a package folder, the agent reads the instructions in that folder first. This is where you specify the exact build commands, test runners, and framework-specific patterns for that specific package.
Local instructions prevent the agent from getting distracted by the rest of the monorepo. You can define specific ways to run a local dev server or how to add a new endpoint in that specific service. When you are deep in a subdirectory, the agent uses these local rules to guide its Edit and Write operations. This hierarchy ensures the agent always uses the right tools for the right environment without you needing to explain the setup in every prompt.
Managing context and cost in large repositories
A large monorepo can quickly consume your token budget. Every time the agent reads a large file or performs a broad search, the context window fills up. You should use the /cost and /usage commands frequently to monitor your spend. If the session becomes too long and the agent starts to lose track of previous steps, use the /compact command. This summarizes the history and keeps the context focused on the current task without losing the essential progress.
If a session becomes cluttered with irrelevant files from different packages, use the /clear command. This resets the conversation while keeping you in the same folder. You can then start a fresh task with a clean slate. This is better than struggling with a bloated context that contains conflicting information from three different packages you were working on earlier. Keeping your sessions short and focused is the best way to manage costs in a complex codebase.
Handling cross-package dependencies
Working in a monorepo often involves making changes that span multiple packages. If you update a shared library, you need the agent to verify that the dependent services still work. You can tell the agent to use the Read tool on the dependency graph or the package files in other folders. It can then use the Bash tool to run tests in those distant directories to ensure no regressions occurred.
You should explicitly document the relationship between packages in your root instructions. Explain how the shared library is linked to the apps. If you use a specific workspace manager, tell the agent how to refresh the links or update the lock files. This allows the agent to navigate the complex web of local dependencies without getting stuck in a loop of failed builds or missing module errors.
Using adhdTerminal for multi-package workflows
Managing a monorepo often requires you to work on several packages at the same time. Running a single session of Claude Code in the root can be overwhelming and messy. adhdTerminal is a native app for macOS and Windows, made by MINDBALANCER OU in Estonia, that runs many Claude Code sessions side by side. Each session appears as a tile on a wall. You can have one tile for your API, one for your frontend, and one for your shared library.
This approach keeps the context of each session narrow and relevant. You do not have to worry about the agent confusing backend logic with frontend styles because they are in separate tiles. Tiles reopen in the same place after a restart and resume the same session. If you need to step away, a free iPhone app mirrors the wall over an end to end encrypted link and can answer a prompt or send the next task. This is an honest way to handle the cognitive load of a large monorepo.
Optimizing permission modes for bulk edits
When you perform a refactor across many packages, the default permission mode might slow you down. The agent asks for approval for every single edit. You can use Shift+Tab to cycle through the different modes. If you trust the agent to handle a repetitive task across several files, you can switch to the acceptEdits mode. This allows the agent to write changes without stopping for a confirmation every time.
If you are unsure about a complex change, use the plan mode. In this mode, the agent describes what it intends to do without actually making any changes. This is useful for verifying that the agent understands the monorepo structure before it starts modifying files in multiple packages. You can review the plan and then switch back to the default mode or acceptEdits mode to execute the work. This flexibility helps you move faster through large-scale repository changes.
Automating tests across the repository structure
Testing in a monorepo is difficult because a change in one place might break a package far away in the tree. You should define a standard way for the agent to run tests in your instructions. Use the Bash tool to execute your test runner. If you have a global test script at the root, make sure the agent knows how to call it. This ensures the agent verifies its work before finishing a task.
You can also instruct the agent to use the TodoWrite tool to keep track of which packages it has already tested. This prevents the agent from repeating work or skipping a package by mistake. If a test fails, the agent can use the Grep tool to find the cause of the error across the repository. Having a clear testing protocol in your local and root CLAUDE.md files ensures the agent maintains the health of the entire codebase even during complex refactors.
Questions people ask
How can I prevent the agent from reading the whole repository every time I ask a question?
You should rely on the hierarchy of instructions and your .gitignore file. Claude Code respects .gitignore by default, which keeps it out of build artifacts and dependency folders. Adding a local CLAUDE.md file in your current package directory tells the agent to prioritize that context and reduces the need for broad searches.
Can I change the behavior of the agent for just one specific package in the monorepo?
Yes, you can place a CLAUDE.md file directly in that package folder. This file can contain specific build commands and style rules that differ from the rest of the repository. The agent reads the root instructions first and then applies the subdirectory instructions to override or add to them for that specific folder.
How do I manage multiple coding tasks in different packages without losing my place?
You can run multiple instances of Claude Code in different terminal tabs or use a tool like adhdTerminal to see them side by side. This keeps the context for each package separate and prevents the agent from getting confused by cross-package files. Each session will maintain its own history and respect the instructions specific to the directory it was started in.
Read next
- Add build instructions to your CLAUDE.md fileImprove project context by adding specific build commands and environment requirements to your CLAUDE.md file for the AI to follow.
- Add common error fixes to CLAUDE.mdImprove project memory by adding a section for common errors and their fixes to your CLAUDE.md configuration file.
- Add custom shell aliases for Claude CodeSpeed up your workflow by creating shell aliases for common Claude Code invocations and project-specific startup commands.
- Add test commands to a CLAUDE.md fileUnderstand how to define specific test runners and environment flags in your CLAUDE.md file so the tool runs the correct test suite.