Solvix

Solvix is a command-line tool for understanding a codebase and deciding where attention is useful.

It scans a repository, identifies important files and functions, explains why they matter, and keeps a traceable record so the same findings can be followed across future runs.

Solvix is built for developers and maintainers who want more than a list of warnings. It is meant to help answer:

• What kind of project is this?
• Which files are central to the way it works?
• Which function should I inspect first?
• Is this worth a benchmark, a source review, or no action?
• Why did Solvix reach that conclusion?
• Did this finding appear before, change, or disappear?

Solvix works without an API key. The core analysis is deterministic. The optional AI overlay is post-processing only.

When To Use Solvix

Use Solvix when you want to understand a project before changing it.

Good moments to run it:

• Before starting work in an unfamiliar repository.
• Before opening a pull request that touches important code.
• When a project feels slow, risky, or hard to reason about.
• During a weekly or release-readiness review.
• After a refactor, to see whether the same findings remain.
• Before writing an issue or outreach note, to make sure the claim is bounded and traceable.

Solvix is not a replacement for tests, benchmarks, profiling, or maintainer judgment. It helps you decide where those efforts should go.

What Solvix Produces

A project analysis gives you:

• Project identity: application, CLI, framework, database engine, schema tool, rendering library, system software, and related objectives.
• Repository inventory: what was scanned, skipped, parsed, and treated as source or peripheral code.
• Dependency and structural signals: central files, graph confidence, unresolved imports, and runtime/core weighting.
• Repo-aware hotspots: functions ranked by cost, relevance, project type, and source context.
• Multi-lens views: maintainability, performance, startup, API stability, reliability, cloud cost, and battery where relevant.
• Deterministic judgment: sendable, needs benchmark, or no-send.
• Trace ledger: stable finding IDs and evidence steps showing why a target was selected.
• Run history: optional comparison against the previous saved run.

Quick Start

Check your install and parser health:

solvix doctor

Analyze one file:

solvix analyze path/to/file.py

Analyze a whole project:

solvix analyze path/to/project --project

Save a JSON report:

solvix analyze path/to/project --project --json --output report.json

Track the same repository over time:

solvix analyze path/to/project --project --history
solvix analyze path/to/project --project --history

The first history run creates a baseline. The next run marks findings as new, repeated, changed, or resolved.

Reading The Terminal Output

Project mode starts with a Solvix Maintainer Brief.

Read this first. It tells you:

• the project identity Solvix inferred
• the default lens selected for the repo
• the current judgment status
• the primary target, if one is ready
• the confidence level
• the trace ID
• the history status
• the next verification step

Example history line:

History        : compared with previous run; new=0, repeated=5, changed=0, resolved=0

What it means:

• new: Solvix did not see this finding in the previous saved run.
• repeated: the same finding is still present.
• changed: the finding is still present but its status changed.
• resolved: a previous finding is absent from the current run.

Judgment Status

Solvix does not treat every finding as something to send or fix.

It uses three practical statuses:

sendable

There is a bounded action packet. The target is specific enough to inspect, benchmark, or discuss.

This does not mean "open an issue immediately." It means the finding is strong enough to review seriously.

needs_benchmark

There is a plausible target, but the safest next step is measurement or source review.

Use this when a claim might be real but needs proof before anyone should act on it.

no_send

Solvix found signals, but they are too weak, intentional, low-impact, already benchmarked healthy, or not in the right code path.

No-send is important. It protects maintainer attention and helps prevent noisy reports.

Trace Ledger

Every project report includes a trace ledger.

The trace ledger gives findings stable IDs such as:

svx-52422549735e

Use the trace ID when you want to know:

• why Solvix selected a target
• which stage produced the evidence
• whether the same finding appears in a later run
• whether the finding changed or was resolved

Trace steps connect the final judgment back to inventory, identity, graph confidence, lens selection, patterns, and verification guidance.

Run History

Run history is opt-in.

solvix analyze . --project --history

By default, Solvix stores history under:

.solvix/history/

You can choose another location:

solvix analyze . --project --history --history-dir .cache/solvix-history

Use history when you want Solvix to live with a project over time:

• first run: create a baseline
• later run: compare against the previous trace ledger
• review repeated findings
• confirm resolved findings
• decide whether new findings need tests or benchmarks

Common Commands

solvix --help
solvix doctor
solvix bootstrap-parsers --all
solvix analyze path/to/file.py
solvix analyze path/to/file.py --function my_function
solvix analyze path/to/project --project
solvix analyze path/to/project --project --history
solvix analyze path/to/project --project --json --output report.json
solvix analyze path/to/project --project --ai-mode assist
solvix --version

Install

Python

pip install solvix

For local development:

pip install -e .

Windows

winget install Solvix.Solvix

macOS

brew tap celpha2svx/solvix
brew install solvix

npm

npm install -g @celpha2svx/solvix

Linux or Generic Unix

curl -fsSL https://github.com/celpha2svx/solvix/releases/latest/download/install.sh | sh

Parser Setup

Solvix uses built-in and native parsers where available.

For offline or restricted environments, prepare parsers ahead of time:

solvix bootstrap-parsers --all

Check parser health:

solvix doctor

Optional AI Overlay

Solvix does not require AI.

The deterministic engine runs first and remains the source of truth. If enabled, the AI overlay receives compressed structured output and adds explanation after the core analysis.

export OPENAI_API_KEY="sk-..."
solvix analyze . --project --ai-mode assist

On Windows PowerShell:

$env:OPENAI_API_KEY="sk-..."
solvix analyze . --project --ai-mode assist

If the AI overlay fails, deterministic reporting still succeeds.

Practical Workflow

For a new repository:

solvix doctor
solvix analyze . --project --history

Then read:

1. Maintainer Brief
2. Judgment status
3. Primary target
4. Trace ID
5. Next verification step
6. No-send decisions

For an existing repository you already track:

solvix analyze . --project --history

Then check:

1. new findings
2. changed findings
3. repeated findings
4. resolved findings

For a report you want to share:

solvix analyze . --project --history --json --output solvix-report.json

What Solvix Does Not Claim

Solvix does not claim that every highlighted function is a bug.

It does not replace:

• profiling
• benchmarks
• tests
• code review
• maintainer context

Its job is to narrow attention, explain the evidence, and help you choose the next useful verification step.

Documentation

• Continuous Judgment Roadmap
• Architecture
• Release Operations
• CLI UX and Release Readiness
• Smoke Tests
• Changelog

Release Notes

Current development is focused on Solvix Core as a continuous judgment system:

• deterministic project understanding
• judgment calibration
• traceable findings
• run history
• clearer terminal output

Packaging and distribution channels should be updated only after the tested CLI experience is stable.