devmap
The environment-reliability insurance for AI agents. Before an agent changes your machine, let it ask devmap one question: "can this environment run my command cleanly right now?" — and get a structured answer instead of a mid-run failure.
devmap is the developer-focused spiritual successor to fastfetch: instead of only printing system specs, it scans the development surface of your machine — runtimes, package managers, IDEs, per-interpreter pip packages, conda/WSL/Docker environments, Visual Studio dev shells, project-local virtual environments, mobile SDKs (Android / Flutter / Dart / NDK), and the Windows pre-flight state an AI agent dies on — and produces a single machine-readable manifest plus an actionable issue list. As an MCP server it plugs straight into Cursor / Cline / Claude Desktop / Codex / CodeBuddy / WorkBuddy, so the agent calls preflight before it ever shells out a command.
Install
This PyPI package ships the real devmap CLI. The wheel embeds the compiled devmap app (devmap/_devmap.mjs) and launches it through Node.js (or Bun, if present) — so pip install devmap && devmap works standalone, with no npm install and no build step:
pip install devmap
devmap --version
Requirements at runtime: Node.js (or Bun) on PATH. Python is only the installer/launcher wrapper — the package has zero Python dependencies.
The npm channel (
npm i -g devmap) ships the same bundle and is equally valid. Pick whichever package manager you already use.
Why devmap (and why it is built for agents)
- AI agents break on dirty environments, not on missing specs. An agent that shells out a
flutter buildorpip installon a machine with a Constrained-Language-Mode PowerShell, a Restricted execution policy, a GBK codepage, or an unsetANDROID_HOMEfails mid-run.devmap --mcpexposes apreflighttool the agent calls first — it returnsok / blockers / warningsplus the exact Windows and mobile-SDK constraints, so the agent fixes (or asks the user to fix) them up front. - The agent stays in control. devmap is a read-only oracle. It never modifies your environment — it reports, and the agent decides. No hidden mutations, no "helpful" auto-fixes.
Features
- One-command full scan of the dev environment (runtimes, package managers, IDEs, environment layers, mobile SDKs, and Windows pre-flight).
- PATH conflict graph: detects multi-version tools, shadowed binaries, and ghost/broken symlinks (e.g. Windows App Execution Aliases that look broken but aren't). This is devmap's original wedge — 14 source-available rivals all lack it.
- Off-PATH awareness: reports installed-but-not-on-PATH tools, while correctly treating version-manager environments (conda envs, nvm versions) as by-design off-PATH.
- Mobile SDK moat (exclusive): Android SDK (
ANDROID_HOME/sdkmanager/adb), Flutter (version + channel + bundled Dart), standalone Dart, and NDK — flagsANDROID_HOMEunset while tools are on PATH, dev/beta Flutter channels, and multiple NDK versions silently shadowing each other. No competitor scans this. - Windows pre-flight moat (exclusive): six checks an agent dies on — PowerShell execution policy, Constrained Language Mode (error), console code page, schannel cert-revocation, App Execution Aliases shadowing real
python/curl, and the safe-delete shim that makes deletions fail closed. - MCP server:
devmap --mcpspeaks MCP over stdio and exposesscan_environment,query_tool, andpreflight. - Security layer (opt-in):
--audit-depsdetects and invokes your installed SCA tools (OSV-Scanner / pip-audit / govulncheck / Trivy), parses their JSON, and merges findings into one view;--scan-secretsadds a fully offline hardcoded-credential scan over a curated allowlist of$HOME/project config files, with every matched value redacted. devmap is a scanner/orchestrator, not a CVE database. - Health layer: converges official self-checks into one view, per environment. Offline by default:
pip checkruns for every Python interpreter, andconda doctorruns for every conda env. With--health-network,npm doctor/rustup checkare added. Missing/offline probes degrade gracefully toinfo(skipped). Passing checks are summarized as✓ N checks passed— onlywarn/errorsurface underissues (N). - Share card:
devmap --cardprints a screenshot-friendly ASCII/Markdown card;devmap --sharewrites it to./devmap-card.md. - Three sub-commands:
scan(the fact source),query(ask the manifest),devdiff(compare two manifests — environment drift / cross-machine consistency). - Zero external dependencies. Pure TypeScript, shipped prebuilt.
Usage
devmap defaults to scan — you can drop the scan word entirely.
devmap # pretty-print to terminal, write ~/.devmap/devmap.json
devmap --json # machine-readable JSON (devmap.json schema) to stdout
devmap --report # full markdown report
devmap --scan-root C:\src # also scan project-local envs under a root
devmap --wsl-deep # also wake stopped WSL distros and probe their tools (slower)
devmap --outdated # hit PyPI to list upgradable pip/conda packages (needs network)
devmap --ci # exit code 1 if any error-severity issue is found
devmap --card # print a screenshot-friendly share card
devmap --share # write the share card to ./devmap-card.md
Key scan flags:
| Flag | Description |
|---|---|
--json |
Emit machine-readable JSON (the devmap.json schema) to stdout. |
--report |
Emit a full markdown report. |
--card |
Print a screenshot-friendly share card (pure ASCII/Markdown — never mojibakes on GBK consoles). |
--share |
Write the share card to ./devmap-card.md. |
--no-manifest |
Do not persist the manifest to disk. |
--manifest <path> |
Read/write the manifest at a custom path (default ~/.devmap/devmap.json). |
--disable <r1,r2> |
Disable check rules by ID prefix (e.g. path.duplicate, pip.outdated, security). |
--shell <list> |
Which shell views to reconstruct: current|powershell|gitbash|wsl|all. |
--scan-root <dir> |
Root(s) to scan for project-local environments (comma-separated). Default: cwd. |
--outdated |
Network check for upgradable pip/conda packages (off by default). |
--wsl-deep |
Probe inside stopped WSL distros (off by default to avoid waking them). |
--audit-deps |
Invoke installed SCA tools and merge CVE findings into the report (opt-in, uses network). |
--scan-secrets |
Scan a curated allowlist of credential files for hardcoded secrets (opt-in, offline, values redacted). |
--health-network |
Also run network health probes (npm doctor / rustup check). |
--mcp |
Run as an MCP server over stdio instead of scanning. |
--ci |
Exit non-zero on any error-severity issue. |
--quiet |
Suppress the live scan progress feedback (for scripts/CI). |
--bom |
Prefix output with a UTF-8 BOM so Notepad-like viewers render it correctly (stdout redirect/pipe only). |
--mcp — run as an MCP server
devmap --mcp
Register it with any MCP-capable agent (Cursor / Cline / Claude Desktop / Codex / CodeBuddy / WorkBuddy / VS Code):
{
"mcpServers": {
"devmap": { "command": "devmap", "args": ["--mcp"] }
}
}
Three tools are exposed. The server targets MCP 2026-07-28 — stateless core (server/discover, no handshake required), tool annotations (readOnlyHint), JSON Schema outputSchema + structuredContent results, and cacheable tools/list — while still answering the legacy initialize handshake for older clients.
| Tool | Purpose |
|---|---|
preflight |
Call this first. Returns ok / blockers / warnings plus the environment constraints (PowerShell language mode, execution policy, codepage, schannel revocation, Android/Flutter state) that would break the command you are about to run. |
scan_environment |
Run a full scan and return the manifest. |
query_tool |
Ask an existing manifest about a specific tool (version, path, on-PATH state). |
// agent -> devmap (MCP)
{ "tool": "preflight", "arguments": { "target": "powershell", "forAgent": true } }
// -> { "ok": false, "blockers": ["win.langmode"], "warnings": ["win.execpolicy", "win.schannel"],
// "languageMode": "ConstrainedLanguage", "codepage": 936, "schannelRevoke": true, ... }
blockers non-empty ⇒ fix first. ok: true ⇒ the agent can proceed.
query — ask the manifest
devmap query # everything
devmap query node # tools whose id contains "node"
devmap query runtime.node # dot-form category.tool selector (runtime / pkg / ide)
devmap query --issues # only issues
devmap query --conflicts # only conflicts (multiVersion / path / ghost)
devmap query --off-path # only off-PATH installs
devmap query --kind runtime # filter by category
devmap query --where conda # filter by install path substring
devdiff — compare two manifests
devmap devdiff # stored manifest vs current live scan
devmap devdiff <file> # stored/before vs <file>
devmap devdiff <a> <b> # compare two manifest files
Reports added/removed installs, version changes, and issues added/resolved.
Output
- The default
scanwrites the manifest to~/.devmap/devmap.json(pure UTF-8, no BOM — directly parseable by Bun/Node/Python/jq). - Use
query/devdiffagainst a stored manifest without re-scanning.
Encoding note
Output is UTF-8. Windows Notepad may mojibake a BOM-less UTF-8 file — open it in VS Code, Windows Terminal, or an IDE, or add --bom when redirecting. When reading a BOM-prefixed file in Python, use open(p, encoding="utf-8-sig").
Repository
https://github.com/StevenLOL/devmap
License
Metadata
Release files for devmap 0.4.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| devmap-0.4.3.tar.gz | 48.5 kB | Without provenance | Details for devmap-0.4.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| devmap-0.4.3-py3-none-any.whl | Python 3 | none | any | Details for devmap-0.4.3-py3-none-any.whl |
Total release size: 92.7 kB
Release files / devmap-0.4.3.tar.gz
| Download URL | devmap-0.4.3.tar.gz |
|---|---|
| Size | 48.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7f33ff10fab145859d9381ade7d4c8e1b04451a0a6e56061f91064b62c820b27
|
|
BLAKE2b-256 checksum How to use checksums |
c0e9c05591cc44189a7673da247001714519fe9aa12333d5550da9ade6971b4b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / devmap-0.4.3-py3-none-any.whl
| Download URL | devmap-0.4.3-py3-none-any.whl |
|---|---|
| Size | 44.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
dc37dc37475628f6ce3d8dcd8ac0c59dec50139712e79e30b76bb5fd0745d276
|
|
BLAKE2b-256 checksum How to use checksums |
ddf99e94f4e1fd52142d76d8be7852f1aee2e2553bffe7dcc43c1bc87b4155be
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Security for devmap 0.4.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.