Repository-scoped dependency intelligence for Python teams.
Scan manifests and imports, diagnose drift, create environments, and apply validated repairs — without leaving the target repo.
Install · Quick start · Commands · Development · CLI reference · Roadmap
Most tools answer one question at a time: what is declared, what is locked, or what is imported. Converge treats the repository as a system.
It builds a graph inside the target repo, connects manifests, lockfiles, and source imports, then explains what is missing, unused, or out of sync. Every command is scoped to the path you pass in — running Converge from one directory never writes state into another project.
init ──► check ──► packages ──► fix --apply ──► audit
│ │
▼ ▼
.converge/graph.db .converge/audit.log
Converge ships via a bash installer (no PyPI). The script clones the release into ~/.local/share/converge, installs into a dedicated venv, links converge into ~/.local/bin, and updates your shell PATH when needed.
curl -fsSL https://raw.githubusercontent.com/desenyon/converge/main/install.sh | bashPin a release tag:
CONVERGE_REF=v0.2.0 curl -fsSL https://raw.githubusercontent.com/desenyon/converge/main/install.sh | bashUpgrade later: run the same command again. The installer updates the clone and reinstalls in place.
| Variable | Default | Purpose |
|---|---|---|
CONVERGE_HOME |
~/.local/share/converge |
Clone + venv location |
CONVERGE_BIN_DIR |
~/.local/bin |
Where the converge symlink is created |
CONVERGE_REPO_URL |
https://github.com/desenyon/converge.git |
Source repository |
CONVERGE_REF |
main |
Branch or tag to install |
After install, open a new terminal (or export PATH="$HOME/.local/bin:$PATH") and run converge --help.
Maintainers: see docs/RELEASE.md for manual tagging and release steps.
# main.py
import requests# pyproject.toml
[project]
name = "demo"
dependencies = []converge init /path/to/demo
converge check /path/to/demo
converge packages /path/to/demo
converge fix /path/to/demo
converge fix /path/to/demo --apply
converge audit /path/to/demo| Command | What it does |
|---|---|
init |
Scaffold a repository-local .converge.toml. |
scan |
Parse manifests, lockfiles, imports, workspaces, and optional npm/system/cargo/conda hints into .converge/graph.db. |
check |
Run scan + doctor in one step (CI-friendly). |
doctor |
Report unresolved imports, unused deps, version clashes, lockfile/compile drift. JSON includes per-package {declared, locked, imported}. |
packages |
List declared, imported, missing, and unused packages. |
explain |
Trace a conflict ID or package node through the graph. |
create |
Build .venv with uv sync --frozen when locked, else constraint-aware installs (--provider auto). |
fix |
Ranked repair plans (add / pin / remove). --apply validates in an isolated sandbox before touching the host repo. |
toolchain |
Detect uv, poetry, pip-tools, or pip and recommend the right install command. |
lock |
Regenerate uv.lock or run pip-compile for pip-tools repos. |
audit |
Show the append-only repair log from fix --apply. |
status |
Dashboard for graph state, scan fingerprints, and lockfiles. |
export |
Write graph JSON or CSV under .converge/exports/. |
clean |
Remove Converge artifacts from the target repository. |
Full flag reference: docs/CLI.md
converge check /path/to/repo
converge packages /path/to/repo
converge doctor /path/to/repo --type unresolved_import
converge fix /path/to/repo --apply
converge status /path/to/repoconverge --version
converge --json doctor /path/to/repo
converge --quiet scan /path/to/repo
converge --verbose fix /path/to/repo--json envelopes include schema_version and tool_version for stable CI parsing.
| Code | Meaning |
|---|---|
0 |
Success |
1 |
Issues found (doctor, fix dry-run, packages) |
2 |
Command error (missing graph, failed export, etc.) |
| Path | Role |
|---|---|
.converge/graph.db |
SQLite dependency graph |
.converge/scan_state.json |
Incremental scan fingerprints |
.converge/exports/ |
JSON / CSV exports |
.converge/audit.log |
Append-only repair audit trail |
.converge.toml |
Optional repo configuration |
.venv |
Default environment from create |
[tool.converge]
incremental_scan = true
skip_type_checking_imports = true
repair_targets = ["pyproject", "requirements"]
extra_scan_roots = ["src"]Run converge init . to scaffold a commented .converge.toml.
| Layer | Sources |
|---|---|
| Python manifests | pyproject.toml, requirements*.txt, requirements*.in, constraints*.txt |
| Lockfiles | uv.lock, poetry.lock, pip-tools compile output |
| Source | AST imports (incl. TYPE_CHECKING, dynamic imports), service routes |
| Toolchains | uv workspaces, dependency groups, [tool.uv.sources] |
| Other ecosystems | package.json, Dockerfile / apt.txt, Cargo.toml, environment.yml |
Repairs are conservative: fix --apply never mutates the host repo unless sandbox validation passes first.
git clone https://github.com/desenyon/converge.git
cd converge
python3.12 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"TMPDIR=/tmp PYTHONDONTWRITEBYTECODE=1 PYTHONPATH=src .venv/bin/pytest tests/unit tests/integration -v
.venv/bin/ruff check src tests
.venv/bin/mypy src/convergeContributor notes: AGENTS.md · Architecture: docs/architecture.md
MIT — see LICENSE.