# How do I keep a coding agent in the right app in a monorepo?

> Identify the owning package, shared dependencies, checkout, and run command before an agent edits one feature in a multi-app repository.

Canonical HTML: https://canopyide.dev/guides/coding-agent-in-monorepo-right-app-package
Article date: 2026-09-28

A monorepo can hold a marketing site, customer app, API, shared UI package, and worker under one Git history. If you ask an agent to fix the customer billing page without naming its owner, it may edit a similar page in another app or start the wrong server. Start by mapping the feature to its package, then keep the agent task, running URL, and final diff tied to that package and checkout.

## Find the package that owns the user journey

Read the root README, workspace configuration, and package manifests. Trace the actual URL or app route to its source package, then check which shared packages it imports. For a billing download, the visible page might live in apps/customer-web, its route call in apps/api, and its CSV formatter in packages/exports. A directory name alone does not prove ownership: inspect the imports, route registration, and tests. Record the checkout path and branch as well, especially when several agents have worktrees of the same monorepo.

- Identify one user-facing app and the dependent packages that may need a change.
- Note lookalike pages or old implementations that should not be edited.
- Read package scripts before guessing a development command.

## Give the agent a bounded search and edit area

Ask for a read-only inventory first: relevant paths, current behavior, shared dependency, and tests. Then assign the implementation with one observable outcome and permission to expand scope only when it explains a real dependency. A package boundary is a starting point, not a guarantee that all correct edits stay inside one folder. Avoid pasting the entire monorepo into the prompt; precise paths, the actual route, and a known failing check are more useful than a long dump of unrelated files. A small project note can preserve the package map for the next session, but verify it against the current checkout.

- Name the owning app, route, expected behavior, and likely shared package.
- Ask the agent to report any file outside that area before changing it.
- For independent changes, use separate worktrees; tabs alone still share files in one checkout.

## Run only the component that demonstrates the change

Use the repository's package manager and scripts. npm documents the --workspace option for running a script in one named workspace; pnpm documents --filter selectors for a package or its dependency graph. Those are alternatives, not interchangeable commands. If the repo is already configured with a root orchestrator, use its documented target instead of inventing a new one. In Canopy, save the verified frontend, API, or worker command with the right working directory and label. Check the process output and URL; a server can start successfully while serving another package or worktree.

*Example inventory for one billing-page change; replace paths and commands with the repository's real configuration.*

| Component | Evidence | Run or check |
| --- | --- | --- |
| Customer web | apps/customer-web route and package manifest | Open its reported local URL and billing page |
| API | apps/api export endpoint and access tests | Run its documented dev and focused test commands |
| Shared exports | packages/exports callers and CSV tests | Run package tests and one consuming-app check |

## Widen tests according to the dependency, then review the diff

Start with the package that changed. If a shared export contract changed, test the consumers that rely on it, including the original reports flow. npm workspaces and pnpm filters can target workspaces, but a filtered command only tests what it selects; it does not prove the entire repository is healthy. Compare the final changed-file list with the agreed package map and ask why any root config, lockfile, migration, or unrelated app changed. In the running product, verify the requested behavior and an existing behavior that could regress. Record the exact commit, command, and URL that were checked.

- Revisit package ownership when the diff crosses a shared boundary.
- Check the app served from the same worktree as the change.
- Use broader CI or integration checks before merge when shared packages or contracts changed.

## Keep the next agent oriented

Leave a concise handoff: user journey, owning package, shared dependencies, command, URL, tests, changed branch, and one unresolved decision. Do not turn a transient path list into a giant permanent instruction file. Claude Code's project memory documentation recommends concise, scoped instructions for facts needed across sessions; for any CLI, the current source remains the authority. Canopy's project and service views can keep the task and running components together, while each installed CLI still controls its own context and model use.

## Copyable resources

### Monorepo task card

Fill this from the actual repository before allowing edits.

````text
User journey and failing or missing behavior: [ ]
Current checkout path and branch: [ ]
Owning app/package and route: [ ]
Shared packages or services it calls: [ ]
Lookalike or legacy app to avoid: [ ]
Read-only inventory: cite relevant source files, callers, tests, and package scripts before editing.
Expected result and failure-path check: [ ]
Allowed initial edit area: [ ]; explain any necessary expansion first.
Frontend/API/worker commands and working directories: [ ]
Observed local URL and process output: [ ]
Focused tests, consuming-app checks, final diff, and exact commit: [ ]
````

## Frequently asked questions

### Should I open the agent at the monorepo root or the app folder?

Follow the CLI and repository's instruction-discovery rules, then verify the actual working directory and scope. An app-folder start can reduce noise, but the agent may need shared packages and root configuration to complete the task.

### Does a pnpm or npm workspace filter prove the whole app works?

No. It selects packages or commands. Run the relevant user journey and dependent-package checks as well; use the repository's broader CI gate when shared code changes.

### Will two agent tabs isolate two apps in the same monorepo?

No. Tabs distinguish sessions, not working files. Give independent code-changing agents separate worktrees and confirm each session's directory and branch.

## Sources and further reading

- [Public question: using Claude Code on a large project](https://www.reddit.com/r/ClaudeCode/comments/1u5jbu0/using_claudecode_on_large_project/)
- [Public question: best approach for agents in a large codebase](https://www.reddit.com/r/ClaudeCode/comments/1rwojpn/best_approach_to_use_ai_agents_claude_code_codex/)
- [npm workspaces and targeted scripts](https://docs.npmjs.com/misc/workspaces/)
- [pnpm filtering and dependency selectors](https://pnpm.io/filtering)
- [Claude Code project memory and scoped instructions](https://code.claude.com/docs/en/memory)
- [Canopy app README: projects and local services](https://github.com/FluidWorksApp/canopy-ide/blob/main/README.md)

## Related Canopy pages

- [How do I stop a coding agent rebuilding a feature that already exists?](https://canopyide.dev/guides/stop-coding-agent-rebuilding-existing-feature.md)
- [My coding agent edited the wrong branch or worktree. What now?](https://canopyide.dev/guides/coding-agent-edited-wrong-branch-or-worktree.md)
- [How do I find the command that runs an AI-built app?](https://canopyide.dev/guides/find-command-to-run-ai-built-app.md)
- [Run a website, API, and background worker in one workspace](https://canopyide.dev/guides/run-local-development-servers.md)
- [How to reduce coding-agent token usage without losing the result](https://canopyide.dev/guides/reduce-coding-agent-token-usage.md)

Canopy runs installed coding CLIs; CLI accounts, model selection, and provider billing remain separate. Check the installed release before relying on version-specific behavior.