WinterSolve

Understand any repository from the terminal. Offline, in seconds, no account.

You open a repository you have never seen. What is it, how do you run it, where are the tests, is anything risky, what should you look at first?

wintersolve brain . answers all of that in one report: languages and stack, source and test layout, the commands you need, an architecture map, a security and privacy check, and a short list of risks and next actions. It reads files; it never phones home. Output is plain text you can paste into an issue, Markdown for a wiki, or JSON for your tooling.

Try it

pipx install wintersolve        # or: python -m pip install wintersolve
cd path/to/any/project
wintersolve brain .

If wintersolve is not found afterwards, python -m wintersolve brain . always works. Want the latest commit instead of a release? pipx install git+https://github.com/harshitkrhere/WinterSolve.git

What you get

Real output from running WinterSolve on its own repository (lightly trimmed; the full report is in examples/):

WinterSolve Repo Brain
======================
Project: WinterSolve
Offline mode: yes

Languages:
  - Python: 39
  - Markdown: 29
  - PowerShell: 2
Detected stack:
  - GitHub Actions
  - Python package
  - pre-commit
Source layout:
  - src
  - src/wintersolve
  - src/wintersolve/modules
  - src/wintersolve/providers
  - src/wintersolve/workflows
Documentation health:
  - README contains the expected core sections.
  - Core open-source hygiene files are present.
Detected commands:
  - install editable: `python -m pip install -e .` (pyproject.toml, medium)
  - test: `python -m pytest` (pyproject.toml, medium)
  - lint: `pre-commit run --all-files` (.pre-commit-config.yaml, medium)
  - pipx: `pipx install wintersolve` (README.md, medium)
Architecture map:
  - docs: Project documentation; notable: docs/ARCHITECTURE.md, docs/COMMANDS.md, ...
  - src: Application or library source code; notable: src/wintersolve/cli.py, ...
  - tests: Automated tests; notable: tests/conftest.py, tests/test_cli.py, ...
Security and privacy:
  - Status: clear
  - Files checked: 86
  - Secret-like values are redacted before they appear in any report.
  - Bandit ran on Python files (medium and high severity): 0 issue(s).
Risks:
  - None detected
Next actions:
  - Run the detected test command before making changes.
  - Use `wintersolve explain <file>` on the most important source files.
  - Use the architecture map as the first contributor onboarding guide.

On a repository with problems, the same report names them: a committed AWS key (redacted in the output), eval() on user input, SQL built from request data, a missing test directory, a README with no install section.

The smaller commands are just as concrete. debug names the fix, not only the category:

$ echo "ModuleNotFoundError: No module named 'cv2'" | wintersolve debug
...
Likely causes:
  - Python dependency or import path issue
Next steps:
  - `cv2` is provided by the `opencv-python` package: `python -m pip install opencv-python`.
  - Install into the environment that runs the code: activate the virtual environment first, ...

explain reads a file the way a person would, in Python, JavaScript/TypeScript, Go, Rust, Java, and more than a dozen other languages and formats. Here it is on command.go from Cobra:

Summary:
  - command.go is a Go file with 2072 lines.
  - Its header comment says: Package cobra is a commander providing a simple interface to create powerful modern CLI interfaces.
  - It has 13 definitions.
  - It imports 10 modules: 9 from the standard library, 1 from third-party packages (github.com/spf13/pflag).
Symbols and sections:
  - type FParseErrWhitelist
  - struct Group
  - struct Command (116 methods)
  ...

Commands

Every command exits 0 on success, 1 if the analysis failed, and 2 for usage errors or targets that cannot be analyzed. Full reference: docs/COMMANDS.md.

A few things people do with it:

wintersolve brain . --format markdown --output REPO_BRAIN.md     # onboarding doc
wintersolve brain . --format json | jq '.security.findings'       # feed a script
pytest 2>&1 | wintersolve debug                                   # explain a failure
wintersolve brain ~/code/some-repo --no-bandit                    # fastest possible

Why WinterSolve

• Offline by default. No API keys, no accounts, no telemetry, no update checks. Safe to run on private code.
• Fast on real repositories. One filesystem walk that prunes node_modules, virtual environments, and build output before descending.
• Honest. Heuristics are labelled as heuristics. The security section says exactly which checks ran, and severity is earned: high only for unambiguous token formats, never for "this line mentions a password", and low for eval() or a fake password in test code.
• Specific. Advice names the package to install, the port that is busy, or the line to start reading, instead of a category of problem.
• Structured. Plain text that pastes cleanly, Markdown for wikis, JSON with a schema_version for tools. Same commit, same report, every time.
• Small. Two runtime dependencies (typer, rich), plain dataclasses, strict typing, tests that run in seconds.

Use it in CI

- run: python -m pip install wintersolve
- run: wintersolve brain . --format markdown --output repo-brain.md
- run: cat repo-brain.md >> "$GITHUB_STEP_SUMMARY"

The report shows up in the Actions job summary. A drop-in workflow and the recipe for failing a build on high-severity findings are in docs/INTEGRATIONS.md.

Installation

Python 3.10 or newer, on Linux, macOS, or Windows. Details and troubleshooting: docs/INSTALLATION.md.

How it works

cli.py  ->  modules/*.py (one analyzer each)  ->  frozen dataclasses  ->  report.py

Analyzers never print and never touch the network. brain calls all of them and composes one report. Adding an analyzer is a module, a renderer, a few lines in the CLI, and a test. See docs/ARCHITECTURE.md.

What it is not

WinterSolve is not an AI assistant and does not need one. It will not write your code, and its security scan is a first pass, not an audit. There is an optional provider interface for people who want to build AI features on top of redacted reports; the CLI never calls it.

Security and privacy

WinterSolve reads the directory you point it at (skipping .git, caches, virtual environments, and dependency folders), runs git status for review, and optionally runs Bandit. That is the complete list. Anything that looks like a credential is redacted before it reaches a report, and explain refuses files outside the project root. Details: docs/SECURITY_MODEL.md. Found a problem in WinterSolve itself? Please follow SECURITY.md.

Development and tests

git clone https://github.com/harshitkrhere/WinterSolve.git && cd WinterSolve
python -m venv .venv && source .venv/bin/activate      # Windows: .venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
ruff check . && ruff format --check . && mypy && pytest

That last line is the whole quality gate, and it is exactly what CI runs on Linux, macOS, and Windows across Python 3.10 to 3.14. Tests use temporary fixture projects and finish in seconds.

Contributing

Small contributions are the best ones here: a stack marker WinterSolve misses, a command it should have found, an error message it does not recognise, a false positive it should not raise. Each is a few lines plus a test.

Start with CONTRIBUTING.md, or BEGINNER.md for a guided first week. Ideas and questions go in Discussions; bugs in Issues.

Status

Alpha (the current release is on the PyPI badge above). The command set is stable; report wording may still change between minor versions, and the JSON schema_version is bumped for any breaking change. See the changelog and the roadmap.

If WinterSolve saved you time, a star helps other people find it.

License

MIT.