Making It Easier to Import Projects Into Your Monorepo

Importing an existing project into a monorepo is not always as trivial as it might sound. There are conventions to align: project structure, build configs, package boundaries. There's the question of git history (you usually want to keep it for blame and debugging).

We shipped nx import last year to take care of the deterministic part of this. It clones a project, detects its tech stack, applies the right Nx plugin to wire it up, and preserves git history while it moves files around. That covers the common path well, but every workspace has its own edge cases (workspace-specific quirks, missing tools) that no generic tool can predict.

This is exactly where an AI agent comes in. So we made nx import agentic.

Deterministic CLI, controlled by an agent

The interesting part is not that an agent is involved, it's how the work is split.

The Nx CLI does the heavy lifting: cloning, file moves, history preservation through subtree merges, plugin detection and setup. That part is deterministic and the agent doesn't reimplement it. It just invokes the CLI.

This split has two practical consequences:

1. Token efficiency. Because nx import does the heavy lifting underneath, the agent doesn't need to scrape every file in the source repos to figure out what to do. It just invokes the CLI and reacts to its output.
2. Correctness on the long tail. The deterministic part stays deterministic. The agent only steps in where the CLI can't predict your specific workspace, like missing runtimes, follow-up file moves, or build failures that surface after the import.

You get the predictability of a real tool with the flexibility of an agent filling in workspace-specific gaps.

How it works

First, make sure your agent has the Nx skills loaded:

nx configure-ai-agents

This scans your system, detects which agent harnesses you use (Claude Code, Codex, Cursor, etc.), and installs the Nx skills (including the nx import skill) for each one.

With that in place, prompt the agent to import your projects and explicitly call out the nx import skill so it gets loaded. Something like:

The agent then runs nx import for each source project and follows up with verification steps based on the targets defined in your workspace: building the project graph to confirm projects were detected and dependencies wired up, running builds, running tests. When something fails, it reacts. In the video walkthrough at the top, the agent notices missing Java runtimes during a build, sees that I use Mise for runtime management, and adds the right entries to mise.toml on its own. That's not something nx import knows about, it falls out of giving the agent room to react to real failures.

What's next: agentic nx migrate

nx migrate has a similar shape to nx import: a deterministic upgrade process that handles the common path well but can't anticipate every workspace-specific quirk. We're working on making that agentic too, so the agent can fill in the gaps when an upgrade step doesn't quite fit your setup.

Learn More

• nx import docs
• Enhance Nx with AI agents
• Nx Docs
• Nx Community Discord
• X / Twitter
• Nx GitHub
• Nx YouTube Channel