English · فارسی

Point it at any codebase. Get one report an AI assistant can actually use.

Quick start · Install · Usage · The report · More tools · Uninstall

Not to be confused with Sarand, a bioinformatics tool for antimicrobial-resistance gene neighbourhoods. This is an unrelated developer tool.

sarand scans a project, works out what it is, runs its tests, linters and security checks, and writes one file with everything an AI coding assistant needs: the project tree, the full source, the results, a health score and a written summary. Run it before you hand a codebase to an assistant, so the assistant starts with facts instead of guesses.

Why sarand

Quick start

Install it once with pipx (Python 3.10+; no Rust needed, the wheels are prebuilt):

pipx install sarand-cli
sarand --version

Other ways (from source, Arch, development) are under Install.

Then run it inside any project:

cd ~/my-project
sarand --full

The last lines tell you where the report went (by default the Downloads folder). Example output:

→ Detected: Rust, Python (cargo)
→ Scan engine: Rust core
→ Running tests (Python, Rust, Shell, JSON, TOML, Markdown)...
→ Running quality checks (Python, Rust, Shell, JSON, TOML, Markdown)...
→ Running security checks (Python, Rust, Shell, JSON, TOML, Markdown)...
→ Rendering Markdown report...
✓ Report completed

============================================================
Project: /home/you/my-project
Detected: Rust, Python
Engine  : Rust core
Output  : /home/you/Downloads/sarand-my-project-report.md
Files   : 163 included / 0 skipped / 1 excluded (secrets)
Health  : 76.0/100 (C)
============================================================

How it works

flowchart LR
    P[("Your project")] --> D["Detect languages<br/>and layout"]
    D --> S["Rust core scan<br/>tree, stats, hashes"]
    D --> A["Language analyzers<br/>tests, quality, security"]
    D --> G["Git, environment,<br/>TODOs, secrets"]
    S --> H["Health score<br/>and AI summary"]
    A --> H
    G --> H
    H --> R{"Renderer"}
    R --> O1["Markdown"]
    R --> O2["JSON, text, HTML"]
    R --> O3["PDF, SARIF"]
    O1 --> AI(["Your AI assistant"])

The CPU-heavy part (walking the tree, counting lines, hashing files to find duplicates) is a Rust crate exposed to Python through PyO3 and maturin. Everything that changes often, the analyzers, renderers, health score and CLI, is plain Python. If the Rust extension cannot be built or loaded on your platform, sarand falls back to a pure-Python scanner that produces the same report, only slower.

What's in the report

Install

Requirements

From PyPI (no Rust needed)

pipx install sarand-cli
sarand --version

The package is called sarand-cli on PyPI (the name sarand there belongs to an unrelated project); the command it installs is sarand. Prebuilt wheels cover Linux (glibc) on x86_64 and aarch64, macOS on Intel and Apple silicon, and Windows on x64, for every Python from 3.10 on. Other systems build from source, as below. To upgrade: pipx upgrade sarand-cli.

From source with pipx

pipx builds sarand in its own isolated environment and puts the sarand command on your PATH.

pipx install ~/sarand
sarand --version

To upgrade after pulling new source, use the installer script instead of a plain pipx install, which does not refresh an existing copy. It builds the current source first and only then replaces the old installation; if the build fails (no network, no Rust toolchain) your previous installation is restored, and it retries slow network failures on its own:

./install.sh

It finishes by printing the version it installed and tells you if a different sarand earlier on your PATH would still run instead of it.

If pipx itself is missing, install it with your package manager (sudo pacman -S python-pipx, brew install pipx, sudo apt install pipx) or with pip, then reload your shell:

python3 -m pip install --user pipx
pipx ensurepath

Arch Linux (AUR)

The AUR package is drafted but not published yet, so yay -S sarand does not work today. Use pipx.

Development install

pip install maturin
cd sarand
maturin develop --release

Building the package needs a Rust toolchain: the build backend is maturin, and pip install -e . fails without one (it tries to download Rust and gives up when it cannot). If the extension will not build on your platform (possible on some Termux/aarch64 toolchains), run sarand straight from the source tree instead. With no compiled core importable it uses the pure-Python scanner, and the report says Scan engine: pure-Python fallback:

python3 -m venv .venv && . .venv/bin/activate
pip install rich PyYAML filelock   # plus tomli on Python 3.10
PYTHONPATH=python python -m sarand --help

Point it at a project with -p, for example PYTHONPATH=/path/to/sarand/python python -m sarand -p ..

Usage

--full is shorthand for "give me everything": it turns on --quality and --security and removes the limits on file size, tree depth and tree entries. A --max-depth, --max-entries or --max-file-size you pass yourself still wins.

Large projects and small devices

Before it renders anything, sarand tells you how much source it is about to embed (Embedding about 12.4 MiB of source from 163 file(s)) and warns when that looks too large for the memory this machine has free. A complete --full report of a big project can be slow, or run out of memory, on a phone or a 2 GB laptop; the warning never blocks the run. To get a lighter report, use --no-source, lower --max-file-size (the default is 2M; --full removes it), or leave --full out.

Running sarand again on the same project replaces its previous report at that path and says so, so reports never pile up under one filename.

Security checks

--security adds the security tools of every detected language (for example bandit and pip-audit for Python, cargo-audit and cargo-deny for Rust, govulncheck for Go) and three project-wide checks:

Independently of this flag, sarand never copies a file that contains a detected secret into the report, and reports how many files it left out.

License policy

By default sarand only advises about copyleft licenses, because whether one matters depends on your project. If you know your rules, write them in a .sarand.toml at the project root and --security enforces them against the SBOM:

[licenses]
allow   = ["MIT", "Apache-2.0", "BSD-*", "ISC", "PSF-2.0"]
deny    = ["AGPL-*", "GPL-*"]
warn    = ["MPL-2.0"]
unknown = "allow"

[[licenses.exceptions]]
package = "somelib"
reason  = "GPL-3.0, used only as a build tool and never shipped"

• A OR B lets you choose, so a package is judged by its best alternative; A AND B needs every part to pass.
• Common non-SPDX spellings such as Apache 2.0 or PSFL are mapped to their SPDX ids. Any other unrecognised string must be listed in allow exactly as it is reported.
• A mistake in the file (a typo like alow, a wrong type, invalid TOML) is an error, never silently ignored.
• syft reads no license for Rust crates because Cargo.lock carries none, so keep unknown = "allow" there and let cargo deny cover Rust.

Health score

The score is transparent and adds up to 100:

Grades: A 90 and above, B 80, C 70, D 60, F below 60.

A score is only as trustworthy as the checks behind it, so the report also says how many checks actually ran. A check whose tool is not installed is skipped, and a skipped check proves nothing: when any were skipped, the Health section lists how many ran and how many did not, gives a confidence percentage, and names the tools to install. A security run in which every check was skipped no longer earns the full security points.

Configuration

The report folder is chosen in this order:

1. --output-dir on the command line
2. The SARAND_OUTPUT_DIR environment variable
3. The folder saved with --set-output-dir
4. ~/Downloads

The saved setting lives in a per-user config file:

The --cache data is stored in the output folder under .sarand-cache.

More tools

Paste a large report into a chat

Some chats take no file upload. python3 -m sarand.rc.command splits any file, typically a sarand --full report, into paste-sized chunks. Every chunk sits inside an integrity-checked envelope (session id, per-chunk hash and a final report hash) that an AI receiver can verify. It walks you through the chunks one at a time and remembers where you stopped, and on terminals that support OSC 52 (Termux included) it copies each chunk straight to the clipboard.

sarand --full -d ~/reports
python3 -m sarand.rc.command --source ~/reports/sarand-my-project-report.md

Run the second command again with no options for the next chunk. State is kept in .sarand-rc/. See docs/RC-AI-RECEIVER.md for the protocol as the receiving AI sees it.

Device storage and environment audit

python3 -m sarand.device_report.command is a separate, read-only tool. It scans a whole device, not one project, for space hogs, duplicate and stale files, build caches, package-manager footprints and Android/Termux environment details, and writes one Markdown report as evidence for a cleanup decision. It never deletes, moves, changes or installs anything.

python3 -m sarand.device_report.command --full -o ~/device-report.md

Built-in diagnostics

sarand --doctor checks the Rust core, your Python version, every per-language tool and the PDF engines. Each line says whether the tool is present and, if it is not, the exact command that installs it. A missing tool is informational; only an unsupported Python version fails the command. sarand --doctor also shows which copy of sarand is running (its version, where it lives, whether it is an editable development install) and warns when a second copy on your PATH shadows it or when an editable install lags behind its source tree. Every command above also answers to --help.

Add a language with a plugin

Implement the LanguageAnalyzer protocol (matches, entry_points, run_tests, run_quality, and optionally run_security) in your own package and register it in your pyproject.toml:

[project.entry-points."sarand.analyzers"]
zig = "sarand_zig_plugin:ZigAnalyzer"

sarand finds it and runs it alongside the built-in analyzers. A plugin that raises, returns the wrong type or cannot be loaded is skipped with a reported reason; it never crashes a scan. The full contract, version compatibility rules and author workflow are in docs/PLUGINS.md, with a working example in examples/sarand-plugin-justfile.

Monorepos and workspaces

sarand detects Cargo workspaces and npm, Yarn and pnpm workspaces and lists their members. For Node workspaces it runs tests and lint inside each member (labelled packages/api: npm test) and skips whatever the root script already fans out, so nothing is reported twice. What is and is not supported, and how the health score treats members, is in docs/WORKSPACES.md.

Troubleshooting

Uninstall

Installed with pipx:

pipx uninstall sarand-cli

Installed as a development install:

pip uninstall sarand

sarand keeps a few things outside the package. Delete them if you want a clean removal:

Contributing

AGENTS.md is the source of truth for architecture, conventions and the roadmap. Before opening a pull request, run:

ruff format .
ruff check .
mypy python
pytest -q

Continuous integration runs the same checks on Linux, macOS and Windows.

License

Released under the MIT License.