Keep spec-driven code easy to change.

A local search and complexity harness for coding agents. Connect specifications to declared features, code, tests and ownership. Give agents the context to understand the implementation and measure its complexity before the next change.

Available on npm. Run the CLI in your repository or connect it to your agent via MCP.

A deep green 3D ball of woven yarn releasing one copper thread.
Keep complexity small per feature.

Find the code. Read the responsibility. Choose a bounded change.

From a tangled repository to a bounded change.

Follow one feature through Untangle. Find its implementation, understand the whole responsibility and give your agent evidence for the next change.

A woven yarn ball with a free thread: an illustration of tracing a feature through code.

Start with the responsibility.

Illustrative relationships, not a measured repository graph. Your declarations define the real boundaries.
Explore the real Untangle map

Start with the responsibility.

Bring a Spec Kit or OpenSpec workspace, an existing feature manifest, or simply your code. Untangle helps connect declared intent to an implementation.

untangle product connect auto --dry-run

Imported boundaries are review drafts. Setup invents no owners or passing tests.

Start with or without a spec

Find the implementation.

Search symbols, names and intent. Follow callers, dependencies and tests. Each retrieval path keeps its provenance, freshness and failure state visible.

untangle query "account lookup" \
  --require-fresh --context --linked

Indexed search uses your configured local services. Direct code analysis can start without them.

Connect search and your agent

Read the whole feature.

Follow the declared feature into code, helpers, tests and ownership. Measure its complete scope. Shared files and missing evidence stay in view.

untangle product --feature=accounts.lookup \
  --format=json

A feature report keeps code metrics, test evidence and ownership separate.

See what a feature report contains

Make the next change smaller.

Use hotspots and feature budgets to choose one responsibility to simplify. Recheck behavior. Opt-in Search Journeys show where agents repeatedly lose the trail as the codebase changes.

untangle complexity --format=json

Untangle provides evidence and agent hints. Your agent owns the edit.

Analyze your first repository

Watch a real codebase untangle.

Open the actual feature map behind this tool: 25 declared features, 1,095 nodes and 1,109 relationships. Untangle the wool map by feature, code area, tests, ownership, Vision / Spec or unassigned files. Inspect the code, evidence and measured complexity.

Choose a category under Untangle by, then use the Untangle button in the map. Pause, resume or show the tangle again. Code and test areas follow directories; ownership and document context follow declared feature links. Shared and missing context stay visible. Open Groups for full names and counts. Code and measurements stay unchanged. Search untangle.embedding to inspect a feature, or use the accessible node list.

Frozen source snapshot at d11bdaf, generated with untangle graph features. The complete graph includes complexity violations, missing measurements and 101 unassigned code files. Ownership includes declared and missing roles; test-run evidence is not attached. Shared feature scopes can overlap.

Generate the same kind of map for your repository after local setup: untangle graph features --format=json. Its HTML and JSON stay in your project's .untangle/feature-map/ directory.

Run Untangle in your project.

Open a terminal in your repository. Your first complexity report needs no account, index or embedding service.

On Linux or macOS, use Node.js 22 (22.13+) or 24+. Install Untangle from npm as a development dependency if your project uses npm.

Install in an npm project
npm install --save-dev --save-exact @untangle-code/cli@next
npm exec -- untangle complexity --top=10

npm resolves next once and saves the exact version. Commit package.json and package-lock.json to share it with your team. For the examples below, run npm exec -- untangle in place of untangle.

Try it once in any repository

Run from the repository root. npm fetches the CLI into its cache.

npm exec --yes --package=@untangle-code/cli@next -- untangle complexity --top=10
Install globally for multiple repositories
npm install --global @untangle-code/cli@next
untangle --version

Run untangle complexity --top=10 from the repository you want to analyze.

See the scope behind the numbers.

The report lists complexity hotspots, source locations and analysis coverage. Give the structured output to an agent to choose a bounded responsibility to inspect.

npm exec -- untangle complexity --format=json
Set up project configuration

Preview the local setup from your repository root. Run the second command when you are ready to write untangle.toml.

npm exec -- untangle init --offline --dry-run
npm exec -- untangle init --offline

These commands use the project installation. With a global installation, run untangle directly.

Next, connect a file to its feature or add indexed search and your agent host. No service setup is needed for code or declared feature analysis.

Connect the requirement to the feature it serves.

Start with an existing specification and a declared feature map, or a file from a search result. See the full feature scope, tests, owners and missing evidence in one local report.

With a specification and feature map

Select a file with --path. Untangle returns every matching declaration and measures the whole feature, including its helpers and shared implementation.

untangle product --path=src/accounts/lookup.ts \
  --format=json

Without a specification

Choose a feature identifier and a real source file. Preview a minimal declaration, then review its boundaries and add the intent, tests and ownership you can establish.

untangle product --draft --feature=accounts.lookup \
  --path=src/accounts/lookup.ts --format=json

When no manifest exists, --draft prints a review draft to stdout. It writes no feature map and invents no owners, requirements or test coverage. After review, save the returned draft object as untangle.features.json; the full report is not the manifest.

Run these examples from your project after the local setup above. Replace src/accounts/lookup.ts with a real repository-relative file and choose your own feature identifier. An existing untangle.features.json is read by default; use --manifest=PATH for another file.

Attach a real test run to the feature report

If your project uses Vitest, explicitly run its tests and capture the original results against the before/after source inventory. Replace the test path with your own:

untangle product --path=src/accounts/lookup.ts \
  --run-tests -- pnpm exec vitest run src/accounts/lookup.test.ts

The command runs without a shell. Failures, skipped tests and sources changed during execution remain visible. Declared test files alone do not count as passed tests.

Initialize with an existing vision or specification

untangle init detects languages, workspaces, ignore rules and local context, then prepares a reviewable configuration. The document and map paths below must already exist in your project:

untangle init --offline --dry-run \
  --vision=docs/vision.md --spec=docs/spec.md \
  --feature-map=untangle.features.json

Preview with --dry-run, then omit it to write the configuration. --offline skips service probes. Initialization does not invent a spec, assign owners or start recording searches.

Three layers of complexity.

From individual functions to the features they support and the effort it takes an agent to find them.

  • Repository complexity

    Analyze cognitive and cyclomatic complexity, inspect dependencies and call paths, and find the hotspots behind a coding task.

    AST metrics, file and symbol graphs. Results state their scope and coverage.

  • Search-based monitoring

    Record real search journeys: queries, candidates, navigation and a confirmed target. Compare search effort alongside the complexity of the code found.

    Local lexical, symbol, semantic and hybrid search. Recording is opt-in.

Evidence for spec-driven agent work.

Use your existing specification and agent host. Untangle provides implementation context, feature reports and search evidence for a coding task. Missing links and unverified requirements remain visible.

Scroll the table horizontally to read each interface. With a keyboard, focus the table and use the arrow keys.

Task What Untangle provides Interface
Find the implementation Independent lexical, symbol, semantic and hybrid search across indexed code and documentation. Freshness checks, ranking explanations and linked graph context. query
untangle_search in MCP
Follow the change File and symbol dependencies, callers, call paths, cycles and the surrounding impact of a change. graph
flow
Measure the code Cognitive and cyclomatic complexity, function hotspots and scoped totals. Configurable thresholds make excessive complexity visible to agents and CI. complexity
Keep the view current Metric deltas as files change. Incremental indexing with watch --index; query --require-fresh rejects stale indexed state. watch
index
Assess the whole feature Declared code and test scope, complexity budgets, shared implementation, ownership links and missing evidence, selected directly from a search result's file path. Source-bound test runs and next actions for agents. product
untangle_product in MCP
Bring your analyzers Local complexity and enabled extension results in one report. Each measurement retains its provider, meaning and run status. scan
Learn from agent searches Opt-in, task-scoped Search Journeys with linked searches, reported navigation, confirmed targets, abandoned tasks and caller-declared model, harness and strategy context. Optional feature attribution connects the task to its scope. untangle_search_session in MCP

Analysis commands support structured output; available MCP tools expose the same local evidence to agent hosts. Language and parser coverage are reported explicitly. Lexical and symbol search do not require an embedding service.

Try the workflow on a coding task
untangle query "where is payment retried?" \
  --require-fresh --linked --context --explain
untangle complexity --max-cognitive=15 --format=json
untangle product --path=src/payments/retry.ts --format=json
untangle watch --index

Example task and source path. Replace them with your own; the source path must be covered by a feature declaration. Indexed search and watch need the services described in the optional search setup.

Connect the analyzers you use.

Add Sentrux, SonarQube or another analyzer through an explicit extension manifest. Untangle provides the common harness: invoke configured providers, collect their evidence and report what ran, failed or was not measured.

Install and configure each provider first. Extensions can use a binary, container or HTTP endpoint; they are enabled explicitly by the operator. Provider manifests are installed separately.

untangle extensions list --format=json
untangle scan --feature=accounts.lookup --format=json

Use your declared feature identifier. File-scoped findings can be related to its declared files; repository-wide values remain repository context.

Sentrux
Collect metrics from a configured binary provider.
SonarQube
Read existing project measures from a configured server. This does not trigger a new Sonar scan.
Your analyzer
Use SARIF, JUnit XML, generic findings or generic metrics through the extension runtime.

All providers support the same goal: reduce complexity. External measures retain their definitions alongside Untangle's own metrics. Provider failures and missing coverage stay visible; a collected report alone does not mean every analyzer passed.

Keep complexity visible for every feature.

A spec-driven task rarely fits in one function. Untangle follows your declared feature map across its code, tests and responsibilities, so an agent can assess the whole scope of a change.

  1. Vision & specWhat profile cards should do
  2. Featureprofile-cards
  3. CodeProfileCard.tsx
  4. TestsProfileCard.test.tsx
  5. OwnershipDeclared frontend maintainer

Illustrative mapping. Your manifest defines the feature boundaries and owners.

What the feature costs in code

  • Code and test metrics reported separately
  • Cognitive and cyclomatic complexity, with metric scope
  • Shared files, declared feature dependencies and unmapped code
  • Threshold violations and next actions for agents

What supports the feature

  • References to vision and specification
  • Selected code and test files
  • Supplied test results tied to the current source
  • Declared owners and missing or unverified links

Set complexity budgets per feature. As functionality grows, the report shows where its implementation exceeds those limits and needs attention.

The report checks the declared mapping and its evidence. It does not independently certify feature behavior or ownership.

Let real searches guide the next improvement.

Keep local journey records and revisit comparable tasks as the repository changes. Use recurring search difficulties to decide where code, documentation or feature boundaries need a closer look.

Repeated query reformulation
Investigate names that differ between the product, documentation and code.
Many plausible candidates
Investigate overlapping responsibilities or feature boundaries that are hard to distinguish.
Long navigation paths
Investigate scattered implementation, difficult dependencies or unclear ownership.
A direct route to the confirmed target
A useful signal of findable structure. Read it alongside complexity and feature evidence.

Start a session explicitly, link the agent's searches and confirm the target. These patterns are hypotheses to investigate, not automatic diagnoses. Index coverage, agent context and search strategy can also explain the effort. Recording begins when the host opts in, not when you run init.

Easy to find is a signal of clear structure.

When your agent finds the code it needs, that is a useful signal. Repeated, comparable searches show how consistently it can reach the right implementation.

Illustrative journey · not benchmark data

Direct hit

Clear route

A feature name leads directly to the relevant component.

  1. Intent

    Improve profile cards User request
  2. Search 01

    profile card component 6 candidates returned
  3. Confirmed target

    ProfileCard.tsx Returned at rank 1
Searches
1
Candidates
6
Observed hops
1
Target rank
#1

High search effort

Tangled route

The same feature has different names across several parts of the repository.

  1. Intent

    Improve profile cards User request
  2. Search 01

    profile display 42 candidates
  3. Search 02 · reformulated

    account card UI 31 candidates
  4. Navigate

    settings → shared → UI 2 reported navigation events
  5. Search 03

    UserCard container 23 candidates
  6. Confirmed target

    ProfileCard.tsx Returned at rank 7
Searches
3
Candidates
96
Observed hops
5
Target rank
#7

Explicitly confirmed targets close each search journey. Observed hops are counted searches plus explicitly reported navigation events. Compare journeys with the same task and measurement context.

Read search effort alongside code complexity.

A small function can be hard to find. A large function can be easy to find. The two measurements answer different questions.

Search effort and target-code complexity remain separate; they are never combined into one score. Embeddings help retrieve code. They do not measure its complexity.

What makes search journeys comparable?

Untangle records the ranking configuration, embedding profile, index generation and immutable corpus revision. The caller can declare its agent model, harness, strategy, task class, task mix and prior context; reports keep differing contexts in separate cohorts. This context is declared, not independently verified. Legacy journeys with incomplete context stay visible, but cannot establish a reliable comparison. Current reports summarize cohorts, including completed and abandoned tasks; built-in time-series and before/after trend views are not available yet.

What is available in this release?

Repository analysis, declared feature reports and explicitly recorded Search Journeys are available. Automatic feature detection, historical feature baselines and autonomous refactoring remain planned. Missing parser coverage and unresolved graph endpoints remain visible in reports.

The default path stays local.

In the standard setup, code is processed by local or self-operated services; remote endpoints are an explicit operator choice.

  1. Telemetry is off by default. A Search Journey starts explicitly. Searches count only when the host links them to that session; navigation counts only when the host or agent explicitly reports it.

  2. Journey free text is opt-in.
    Goals, queries and optional feature identifiers default to fingerprints generated with workspace-local, domain-separated HMAC-SHA-256. Failed-search and free abandonment details are omitted unless text retention was explicitly enabled. Source chunks are never journey data.

  3. Fingerprints are pseudonymous, not anonymous or encrypted. Metadata still remains: locators, ranks, scores, explicit tool names and an optional controlled abandonment reason code stay local even without text retention. The HMAC key is stored separately, and someone with the complete local state can test guesses. Journey files remain until the operator deliberately removes them.

Add search and your agent host when you need them.

The npm CLI includes an MCP server. Connect your host to direct code and feature analysis first. Add indexed search when it serves the task. Tools that are not available return FEATURE_UNAVAILABLE.

For an npm project installation, point your host at the installed CLI. Use absolute paths to Node.js, the CLI entry point and the target repository.

Local MCP command npm exec -- untangle mcp --stdio
Agent host

Use the configuration below to fix the workspace root for your agent.

Show a generic stdio configuration
{
  "mcpServers": {
    "untangle": {
      "command": "/absolute/path/to/node",
      "args": [
        "/absolute/path/to/project/node_modules/@untangle-code/cli/dist/index.js",
        "mcp",
        "--stdio",
        "--root=/absolute/path/to/project"
      ]
    }
  }
}
Enable local indexed search

Search uses embedded LanceDB by default, with Qdrant available as an option. Service embeddings need Ollama and the configured model. --embedder=offline avoids Ollama. It uses deterministic vectors, without language-model semantics; lexical and symbol search remain available. init checks services; it does not start them or download models.

untangle init
untangle doctor
untangle index
untangle query "your coding task" --require-fresh

Run from the target repository after providing the configured services. Inspect doctor before indexing. Queries read the index; rebuild it or use watch --index as sources change.

Agents can hand a search result's filePath to untangle_product as path. Start a Search Journey explicitly to record search effort; an MCP connection alone starts no monitoring.