clarity

Clarity

See the structure of a code change before you commit it.

Clarity builds dependency impact graphs from source code. It shows how files, modules, tests, and documentation connect so developers and coding agents can reason about design changes with evidence instead of intuition.

Use it when you want to know:

• What does this change touch?
• Who depends on this file?
• Why are these two areas connected?
• Did this refactor cross a boundary?
• Did we introduce a cycle?
• What does this branch look like structurally?

Clarity works at file granularity. It recovers coupling shape, not runtime behavior or full API contracts.

Quick Start

Install with npm:

npm install -g @legacycodehq/clarity

Or on macOS/Linux with Homebrew:

brew install LegacyCodeHQ/tap/clarity

Keep a live graph open while you code:

clarity watch

Show the structural impact of your uncommitted work:

clarity show

Find what depends on a file before changing it:

clarity show path/to/file.go --reach up

Review the structural footprint of a branch:

clarity show -c main...HEAD

The Model

Every graph answers four questions.

This makes Clarity useful for both quick local checks and repeatable agent workflows.

Core Use Cases

Review a Change Before Commit

clarity show

Shows the dependency graph around your uncommitted work.

Use it to check:

• whether the change stayed inside the intended area
• which neighboring files are affected
• whether tests are connected to the changed code
• whether new coupling appeared

Review a Commit, Branch, or PR

clarity show -c HEAD
clarity show -c main...HEAD

Use commit and range snapshots to review structural impact after the fact. This is useful for pull requests, regression windows, release reviews, and agent-generated changes.

Refactor Safely

clarity show path/to/file.go --reach up
clarity show path/to/file.go --reach both --depth 2

Use upstream reach to answer "who imports this?" before changing a file. Use bounded reach to estimate blast radius.

Understand a Codebase

clarity show src/auth
clarity show src/auth --reach both
clarity show --all --collapse

Use scoped graphs to explore unfamiliar code. Collapse configured modules when the file-level graph is too noisy.

Trace Unexpected Coupling

clarity show --between ui/login.ts,server/session.go

Shows the dependency paths connecting two files. Use this when you need to explain why two areas are coupled or decide where to cut a dependency.

Audit Module Boundaries

clarity modules
clarity show --module auth --reach both
clarity show --all --collapse

Declare modules in .clarity/modules.json, inspect a module in context, or collapse modules into architecture-level nodes.

Find Circular Dependencies

clarity cycles src
clarity cycles src --url

Lists circular dependencies within a scope and can produce focused visualizations for each cycle.

Keep Feedback Live While Coding

clarity watch
clarity watch src/auth --reach both

Runs a local live graph that updates as files change. Use it during refactors or large agent edits to keep structural feedback visible.

Support Coding Agents

clarity setup

Adds repository instructions so coding agents can use Clarity as part of their normal loop.

Good agent patterns:

• inspect dependents before refactoring with --reach up
• run clarity show -f mermaid after edits
• generate clarity show -u for a shareable review artifact
• use the graph to catch unexpected coupling before commit

Output

clarity show -f dot
clarity show -f mermaid
clarity show -u

DOT is the default. Mermaid works well in docs, IDEs, and agent UIs. -u creates a browser-friendly visualization URL.

Language Support

Clarity supports dependency extraction for:

• C, C++, C#
• Dart
• Go
• Java, Kotlin, Scala
• JavaScript, TypeScript, Svelte
• Markdown
• Python, Ruby
• Rust
• Swift
• Zig

Support quality varies by language. Run:

clarity languages

to see the current maturity and extension list.

Experimental Surfaces

clarity cycles
clarity workspace

cycles reports circular file dependencies.

workspace builds Go module and Rust crate relationship graphs.

These surfaces are useful, but their output may change.

What Clarity Is Not

Clarity is not a replacement for tests, type checks, linters, or code review.

It does not provide:

• full symbol-level call graphs
• runtime behavior analysis
• API contract verification
• semantic correctness guarantees

It is a structural verification tool: it shows coupling, impact, boundaries, cycles, and change shape.

License

This project is licensed under the Apache License, Version 2.0.

Copyright (c) 2026-present, Legacy Code Headquarters (OPC) Private Limited. All rights reserved.