Extracting a Package From a Monorepo With an Agent

Extracting a package from a monorepo is a common architectural evolution for scaling engineering teams. As projects grow, the convenience of a unified repository often gives way to the need for independent versioning, deployment cycles, or open source distribution. This process, while conceptually simple, involves complex steps like preserving git history, remapping internal dependencies, and updating CI/CD pipelines. Using an AI agent for extracting a package from a monorepo can significantly reduce the manual overhead of moving files while ensuring that references remain intact across the new and old environments.

The Motivation for Extraction

Monorepos provide visibility and ease of cross-package refactoring during early development. However, several signals suggest it is time to extract a specific package into its own repository.

• Versioning overhead: when a utility library requires frequent updates that trigger unnecessary builds for the entire project.
• Access control: when you need to give outside contributors or contractors access to a specific module without exposing the entire proprietary codebase.
• Performance: when the size of the monorepo slows down git operations or IDE indexing to an intolerable level.
• Distribution: when a segment of the code is mature enough to be shared as a standalone library on npm or PyPI.

Technical Approaches to Extraction

There are two primary ways to move code while keeping history. The first is git filter-repo, which is a powerful tool for rewriting history. The second is git subtree, which is generally safer for users who want to split a folder into a new repository without deleting the original source immediately.

Manual Subtree Splitting

The manual process usually involves creating a new branch that only contains the history of the target subfolder. You then push that branch to a fresh repository. While this preserves the commit log, it does not handle systemic issues like imports that point to other packages within the original monorepo.

Agent-Assisted Extraction

An AI coding agent can transcend simple file moves. Traditional scripts cannot easily detect that a relative import like ../../shared/utils needs to become a package dependency like @org/utils. An agent can analyze the file tree, identify these broken links, and update package.json or requirements.txt files automatically.

Using Deska for Extraction Tasks

Deska presents a unique environment for this kind of refactor. Because it is a local-first application, the AI agents you run have direct access to your file system without your code ever leaving your machine. You can use the canvas to orchestrate the entire move.

1. Open the monorepo in a terminal panel on one side of the canvas.
2. Open a new, empty directory in a second terminal panel next to it.
3. Launch a coding agent panel, such as Claude Code or Codex CLI, to bridge the two.

By seeing both directories side by side, you can use Ask Deska to coordinate the move. You might ask the agent to scan the target folder for external dependencies and generate a report in a notes panel. This visibility ensures you do not miss hidden configuration files or hidden dotfiles during the migration.

Handling Dependency Mapping

The hardest part of extracting a package from a monorepo is managing the "ghost" dependencies. These are internal modules that the package relies on but which will no longer be available in a standalone context.

If the package you are extracting depends on a shared utility library that must remain in the monorepo, you have two choices. You can either extract the utility library first or duplicate the necessary logic. An agent can help you weigh these options by calculating the number of shared lines of code across the project.

Verification and Testing Strategy

Once the code is moved, you must verify the integrity of the new repository. This typically involves several stages.

First, run the build process in a clean environment. Since Deska runs agents locally, you can have the agent spin up a temporary container or a virtual environment to test the new package in isolation. This prevents the "it works on my machine" syndrome where the package still accidentally pulls from the monorepo parent directory.

Second, check the git history. Users often forget that a simple copy-paste loses all the context of why certain lines were written. Tools like git log should show the original authors and commit messages even in the new location.

Third, update the original monorepo. The extracted package should now be listed as an external dependency. The agent can help you update the workspace configuration of the monorepo to point to the new git URL or registry version.

The Role of Mobile Monitoring

Large refactors and extraction tasks can take time, especially when rebuilding large dependency trees. With the Deska mobile app, you can track the progress of these long-running tasks. If you initiate a large git filter-repo operation or a complex linting fix across thousands of files, you can step away from your desk. The secure relay allows you to see the terminal output on your phone, ensuring the process completes without errors.

Frequently Asked Questions

How to extract a git folder into a new repo with history?

The most reliable way is using git subtree split. You define the prefix of the folder and a new branch name. Once the branch is created, you add a new remote and push that specific branch to the new repository. This keeps all commit data associated with those specific files.

Does a monorepo extraction break existing pull requests?

Yes, any open PRs in the monorepo targeting the extracted folder will become stale. It is best to freeze development on that package, merge all outstanding PRs, and then perform the extraction. An agent can help by listing all open PRs that touch the target directory before you start.

Should I use git filter-repo or git subtree?

git filter-repo is generally recommended over the older git filter-branch for speed and safety. Use it if you need to deeply purge files or sensitive data from history. Use git subtree if you want a simpler workflow that is built into modern git versions and is less destructive to the original repository.

Get Started with Deska

If you are planning a major codebase migration, having the right workspace makes a difference. Deska provides the tools to run multiple coding agents side by side while maintaining privacy through local execution. You can organize your move, track your progress, and automate the tedious parts of the refactor.

Download the free desktop app for Mac, Windows and Linux at /download and start organizing your development workflow on an infinite canvas.