Skip to main content

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 build or pip install on a machine with a Constrained-Language-Mode PowerShell, a Restricted execution policy, a GBK codepage, or an unset ANDROID_HOME fails mid-run. devmap --mcp exposes a preflight tool the agent calls first — it returns ok / blockers / warnings plus 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 — flags ANDROID_HOME unset 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 --mcp speaks MCP over stdio and exposes scan_environment, query_tool, and preflight.
  • Security layer (opt-in): --audit-deps detects and invokes your installed SCA tools (OSV-Scanner / pip-audit / govulncheck / Trivy), parses their JSON, and merges findings into one view; --scan-secrets adds 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 check runs for every Python interpreter, and conda doctor runs for every conda env. With --health-network, npm doctor / rustup check are added. Missing/offline probes degrade gracefully to info (skipped). Passing checks are summarized as ✓ N checks passed — only warn/error surface under issues (N).
  • Share card: devmap --card prints a screenshot-friendly ASCII/Markdown card; devmap --share writes 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 scan writes the manifest to ~/.devmap/devmap.json (pure UTF-8, no BOM — directly parseable by Bun/Node/Python/jq).
  • Use query / devdiff against 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

MIT

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)

Source distribution for devmap 0.4.3
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)

Table of built distributions (wheels) for devmap 0.4.3
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page