Urmare

Urmare is a fast, deterministic impact-analysis tool for Python repositories. It answers one question:

Given a Python code change, what follows from it?

Urmare maps static imports, calculates affected modules and pytest files, and explains dependency paths. Analysis runs locally without a hosted service or a Python runtime.

The project is an early MVP. It intentionally focuses on file-level static imports and favors impact recall over aggressive test reduction.

What Urmare does

• finds direct and transitive dependents of one or more changed Python files;
• selects affected pytest files;
• produces structured validation plans for coding agents and CI;
• analyzes staged, unstaged, untracked, committed, deleted, and renamed Git changes;
• explains each result with a deterministic dependency path and import locations;
• supports flat, src/, and explicitly configured multi-root repositories;
• maintains a persistent local index with bounded updates for Git repositories;
• emits stable, versioned JSON for scripts, CI, and coding agents.

Install

Install Urmare as an isolated tool with uv or pipx:

uv tool install urmare
# or
pipx install urmare

You can also install it in a virtual environment:

python -m venv .venv
source .venv/bin/activate
pip install urmare

On Windows, activate with .venv\Scripts\activate.

PyPI wheels contain the standalone Rust CLI and do not compile code during installation. Prebuilt binaries support macOS ARM64 and x86-64, Linux glibc ARM64 and x86-64 with a manylinux_2_17 baseline, and Windows MSVC x86-64. Standalone archives for the same targets are available from GitHub Releases.

Quick start

Run Urmare from the repository you want to analyze:

# What should an agent validate after editing the working tree?
urmare plan --changed --json

# What depends on this file?
urmare impact src/payments/stripe.py

# Which tests are affected?
urmare tests --affected src/payments/stripe.py

# Why is this test affected?
urmare why src/payments/stripe.py tests/api/test_checkout.py

Analyze more than one explicit change at once:

urmare impact src/payments/models.py src/payments/stripe.py
urmare plan src/payments/models.py src/payments/stripe.py --json

Analyze the current Git working tree or all branch changes since a merge base:

urmare impact --changed
urmare tests --affected --changed
urmare plan --changed --json

urmare impact --git-diff origin/main
urmare tests --affected --git-diff origin/main
urmare plan --git-diff origin/main --json

Inspect the repository graph when a mapping or result is surprising:

urmare graph
urmare graph --debug --focus src/payments/service.py

Common options:

• --json returns complete, deterministic machine-readable output.
• --all disables truncation in supported human-readable output.
• --root PATH analyzes another repository instead of the current directory.
• urmare help COMMAND shows the complete grammar for a command.

Explicit files, --changed, and --git-diff are alternative change sources and cannot be combined. Invalid or unindexed paths fail with an actionable diagnostic instead of returning a partial result.

Agent validation workflow

plan is the recommended agent-facing entry point. It returns affected code, selected pytest files, attribution, and structured validation steps in one deterministic result:

agent edits Python code
    ↓
urmare plan --changed --json
    ↓
agent runs every validation step
    ↓
agent uses urmare why when an impact path needs investigation
    ↓
CI independently recomputes the plan

Copy this instruction into a terminal-capable coding agent:

After modifying Python code:

1. Run `urmare plan --changed --json`.
2. Execute every validation step using the repository’s established environment.
3. If the plan requires full validation, run the complete test suite.
4. Do not claim completion until the required validation succeeds.
5. Use `urmare why` when an affected relationship needs explanation.

For example, after an agent edits src/payments/service.py, Urmare may return:

{
  "schema_version": 1,
  "changed": ["src/payments/service.py"],
  "directly_affected": ["src/api/checkout.py"],
  "transitively_affected": ["tests/api/test_checkout.py"],
  "affected_tests": ["tests/api/test_checkout.py"],
  "validation": {
    "mode": "selective",
    "steps": [{
      "kind": "pytest",
      "program": "pytest",
      "args": ["tests/api/test_checkout.py"]
    }]
  },
  "attributions": [{
    "affected": "tests/api/test_checkout.py",
    "caused_by": ["src/payments/service.py"]
  }]
}

If that repository uses uv, the agent then runs its established environment with the supplied target:

uv run pytest tests/api/test_checkout.py

Urmare plans validation but does not execute pytest. This is a CLI and JSON contract, not a native Codex, Claude Code, Cursor, or MCP integration. Agents and CI remain responsible for invoking the repository's established test environment.

Configuration

Flat and conventional src/ layouts work without configuration. For monorepos or custom layouts, add [tool.urmare] to the repository's pyproject.toml:

[tool.urmare]
source-roots = ["packages/payments/src", "packages/api/src"]
test-roots = ["verification", "integration/checks"]
exclude = ["generated/**", "vendor", "**/snapshots/*.py"]

• Source roots define module identities.
• Test roots supplement test_*.py and *_test.py discovery.
• Exclusions are repository-relative /-separated globs.
• Result paths always remain canonical and repository-relative.

Configuration is validated strictly. Missing roots, escaping paths, invalid globs, unknown options, and ambiguous modules are rejected. A Git change to the root pyproject.toml requires full validation and conservatively selects every eligible test rather than claiming a selective result.

Incremental indexing

Urmare stores a versioned index in the operating system's per-user cache, isolated by canonical repository root. It never writes cache data into the analyzed repository and requires no daemon or remote service.

For a Git repository at its top level, Urmare uses Git changes and content hashes to update only relevant files and relationships. A clean reuse performs no Python parsing, import resolution, graph mutation, or index writes. A content-only one-file edit parses that file without re-resolving unchanged imports.

Unsafe or incompatible states fall back to a complete correct analysis. These include non-Git roots, configuration or source-root changes, corrupt indexes, tracked submodules, nested untracked repositories, and Git index flags that can hide content changes.

JSON and exit codes

Every command accepts --json. JSON is written to stdout, uses canonical repository-relative paths, and includes a schema_version. Failures leave stdout empty and write an actionable diagnostic to stderr.

An impact result has this concise shape:

{
  "schema_version": 1,
  "changed": ["src/payments/stripe.py"],
  "directly_affected": ["src/payments/service.py"],
  "transitively_affected": ["src/api/checkout.py"],
  "affected_tests": ["tests/api/test_checkout.py"],
  "attributions": [
    {
      "affected": "tests/api/test_checkout.py",
      "caused_by": ["src/payments/stripe.py"]
    }
  ]
}

plan --json has its own schema version 1. Its validation.mode is selective, none, or full; steps contain a program and argument array, not a shell command. In full mode the pytest step has no file arguments and the existing full_validation object explains why complete discovery is required.

Performance

A real-project reference run on 2026-09-03 used 15 independent paired samples per project on an Apple M5 Pro with 18 logical cores and 48 GiB of memory. These are median end-to-end CLI latencies for Urmare commit daaf7a592bb54ef0ee71b1ed3065caaf9187d67b:

All cold, warm, and incremental results matched fresh uncached analysis. Each content-only incremental run parsed and hashed one file, re-resolved no importers, changed no graph edges, and wrote two index records.

These are machine-specific observations, not portable guarantees. See the performance methodology and complete distributions, including corpus revisions, binary provenance, work counters, raw-data digest, limitations, and the separate synthetic scaling results.

cargo build --release --locked -p urmare-cli --bin urmare
cargo build --release --locked -p urmare-core --example profile_repository

python3 benchmarks/real_projects/benchmark.py prepare \
  --work-dir target/real-project-benchmark
python3 benchmarks/real_projects/benchmark.py dry-run \
  --work-dir target/real-project-benchmark \
  --binary target/release/urmare \
  --profile-helper target/release/examples/profile_repository
python3 benchmarks/real_projects/benchmark.py run \
  --work-dir target/real-project-benchmark \
  --binary target/release/urmare \
  --profile-helper target/release/examples/profile_repository \
  --samples 15 \
  --output target/real-project-benchmark/raw/official.jsonl
python3 benchmarks/real_projects/benchmark.py summarize \
  --input target/real-project-benchmark/raw/official.jsonl \
  --output target/real-project-benchmark/summary/official.md

Run the separate deterministic synthetic suite with:

cargo bench -p urmare-core --bench synthetic --locked

Set URMARE_BENCH_50000=1 to include the 50,000-file case.

Current limitations

• static import and from ... import ... relationships only;
• no dynamic-import, re-export, symbol, call, type, fixture, or framework graph;
• test selection is file-level, not individual test functions;
• unresolved imports mean no repository-local module matched; installed environments and package indexes are not inspected;
• non-Git repositories conservatively rebuild on every invocation;
• broad impact and complete graph/debug output remain proportional to their result size;
• no test execution, CI execution, MCP server, or hosted integration.

When Python semantics are ambiguous, Urmare conservatively includes certain local package and module loads. False positives are preferable to silently missing affected code or tests.

Development

Build from source with Rust 1.95 or newer:

git clone https://github.com/sorginte/urmare.git
cd urmare
cargo build --release

Run the required checks before submitting a change:

cargo fmt --all -- --check
cargo clippy --workspace --all-targets --locked -- -D warnings
cargo test --workspace --locked
cargo +1.95.0 check --workspace --all-targets --locked

The workspace separates the generic graph, Python analysis, application logic, and CLI into urmare-graph, urmare-python, urmare-core, and urmare-cli. Purpose-built fixture repositories live under fixtures/python-projects/.

Further reading:

• Product specification and design principles
• Roadmap and upcoming milestones
• Performance methodology and observations
• Release process

License

Urmare is available under the MIT License.