docs · install & usage

Your profile in under a minute.

One clone, one command — no account, no signup, no upload. nextmillionai runs entirely on your machine. Here's how to install it, what each command does, and exactly what it reads.

install

Clone and run

Requirements: Python 3.9+, zero runtime dependencies. Runs straight from the clone — no install step, no build.

# See it instantly with bundled demo data — your own data untouched
git clone https://github.com/nextmillionai/nextmillionai && cd nextmillionai
python3 -m nextmillionai report --demo

# Build your own profile: consent → assess → opens both views
python3 -m nextmillionai start

A one-line pipx install nextmillionai / uvx nextmillionai is coming in a later release. For now, git clone is the whole install.

the commands

What each command does

Run start for the whole flow, or step through it yourself.

calibrate
Consent + scope — you see exactly what's read, and your answers are saved.
assess
Scan + score locally → one assessment JSON. --code adds opt-in repo evidence (metrics only); --project ~/path scans one repo.
report
Serve both views; picks a free port, opens the browser. --demo serves the bundled example.
enrich
Your own AI agent writes the narrative from real signals — never a score. Opt-in and revocable (enrich --revoke).
export
Write a static, self-hostable folder with a redacted assessment.json — private signals verified absent.
publish / unpublish
Send the curated, derived-only JSON to a registry after explicit confirmation / revoke it any time.
sync
Merge devices through a private git repo you own — deduped, never double-counted, revocable.
privacy · the two promises

What it reads — and what never leaves

read locally

Your sessions + git

Claude Code, Cursor, and Codex sessions already on disk, plus git (commit log + dependency names). It derives how you build — never your source code, never raw prompt text.

promise 1

Nothing is uploaded

No server in the assessment path, no silent upload. The only network path is an explicit publish — derived signals only, and revocable.

promise 2

Computed, not estimated

Plain arithmetic over counted signals against research-anchored bands. No percentiles, no leaderboards. Unmeasurable is marked insufficient, never guessed.

wider field

Many tools, declared fidelity

Beyond the first-class tools: Copilot Chat, Cline, Cody, Continue.dev, Aider, Windsurf, Zed AI, JetBrains AI, plus local models (Ollama, LM Studio, llama.cpp). Each adapter declares deep / counts / presence.

the views

What report serves

Everything renders locally on localhost from one assessment JSON.

/profile
The credential dashboard — Overview · Work · Lab · Provenance · Share.
/report
The deep, shareable deliverable — narrative, scores, the positioning map, per-project breakdown, evidence appendix.
/methodology
Every formula, served from the same engine as an interactive explorer. See the overview →
/how-it-works
Command reference + pipeline map, with search — the deep version of this page, served from your own machine.
sharing · three levels, each explicit

You decide what leaves

default

Local

Localhost only. Nothing is shared until you choose to.

self-host

Export

export writes a static folder + a redacted assessment.json — hidden projects and private signals verified absent. The report is the shareable artifact.

opt-in

Publish coming soon

Send the same curated JSON to a registry after seeing exactly what leaves; unpublish revokes. Today it targets a self-hosted reference registry.

from your agent

MCP coming soon

An MCP server with 15 tools lets any MCP-compatible agent (Claude Code, Cursor, Cline) build and query your profile directly. The code is in the repo.

go deeper

The full docs live in the repo

Every contract is open and versioned. Read them on GitHub, or run the tool and open /how-it-works locally.

SCORING-METHODOLOGY →Every formula and band, with provenance. SCHEMA →The one assessment JSON + shareable/private map. ADAPTERS →Tool coverage, fidelity, exactly what's read. TRUST →Anti-gaming: what a report proves, what it doesn't. PRIVACY →The two promises, in full. CONTRIBUTING →Add a tool adapter or shape the methodology.

Ready? One clone and one command — it walks you through the rest on first run.

README on GitHub → Get it free