Code Quality Tool

Import Cycle Detector

Find circular dependencies between modules. Visualize dependency chains and get suggestions for breaking the cycles.

Install

Get the CLI Tool

Detect import cycles locally as an MCP server, or try it online below.

npx @clinetools/import-cycles
Requires Node.js 18+
  • Detects circular imports in JS, TS, Python, and Go codebases
  • Visualizes full dependency chains with cycle highlighting
  • Suggests optimal breaking points based on dependency weight
  • Distinguishes direct vs re-export cycles
  • Preference conversation on first run — set ignore patterns and severity thresholds
Tutorial

How to Use It

Find and break circular dependencies in your codebase.

1

Try Online

Define module imports below and the tool will detect cycles instantly.

↓ Jump to interactive demo
2

Use via CLI

Point it at your project root. It scans all source files for import statements.

npx @clinetools/import-cycles
3

Add to Cline / Claude Code

Your agent checks for cycles when restructuring modules or adding new imports.

"import-cycles": { "command": "npx", "args": ["@clinetools/import-cycles"] }

MCP Client Configuration

{
  "mcpServers": {
    "import-cycles": {
      "command": "npx",
      "args": ["@clinetools/import-cycles"]
    }
  }
}

Example: Detect and Break Cycles

// Prompt to your AI agent:
"Find all circular import chains in this
project and suggest how to break them"

// The agent calls:
detect_import_cycles({
  root: "./src",
  extensions: [".ts", ".tsx"]
})

// Output:
// Cycle 1: auth.ts → user.ts → auth.ts
//   Suggestion: Extract shared types to types.ts
// Cycle 2: api.ts → cache.ts → db.ts → api.ts
//   Suggestion: Break db.ts → api.ts with
//   dependency injection
Live Demo

Try It Online

Define module dependencies to detect circular imports. Use the format: module → dependency (one per line).

Define Module Imports

One import per line: source → target (use arrow or >)

Try a demo:

Define module imports and click Detect Cycles to find circular dependencies.

Cycles

Learn

Why Circular Dependencies Matter

Circular imports are a silent codebase killer. They cause mysterious bugs, bloated bundles, and architectural decay.

Undefined at Runtime

When A imports B and B imports A, one of them gets an incomplete module at import time. This causes mysterious "undefined is not a function" errors that only appear in specific import orders.

Bundle Bloat

Bundlers like webpack and Rollup can't tree-shake circular dependencies effectively. Cycles force the bundler to include entire modules even when only a single export is used.

Architecture Decay

Cycles indicate modules have unclear responsibilities. When everything depends on everything else, changes ripple unpredictably through the codebase. Breaking cycles forces cleaner boundaries.

Testing Difficulty

Circular dependencies make unit testing harder because you can't isolate modules. Mocking becomes a nightmare when the mock itself triggers the circular import chain.

Common Solutions

Extract shared types to a common file. Use dependency injection instead of direct imports. Create a barrel file (index.ts) to control the import order. Move tightly-coupled code into the same module.

Break the Cycle Before It Breaks Your Code

Add the Import Cycle Detector to your agent's toolkit and keep your architecture clean.

View Plans