AI Dev CLI Tools

Cross-platform Python CLI helpers for AI coding agents and humans who want concise, deterministic development reports instead of huge logs.

ai-dev runs repeatable project checks locally, stores full logs under .ai/logs/, and returns compact Markdown/JSON summaries under .ai/reports/.

Problem

AI coding agents often spend tokens reading full test output, repository trees, dependency noise, repeated warnings, and raw Git diffs. This project follows one rule:

Scripts do the work and collect data.
AI reads a short report and decides what to do next.
Full logs stay on disk until needed.

Generated state under `.ai/logs/`, `.ai/reports/`, `.ai/context/`, `.ai/cache/`,
`.ai/runtime/`, and `.ai/tmp/` is local and ignored by Git. Logs, reports, and context
artifacts may be removed when no longer needed; cache, runtime, and temporary state must always
be safe for `ai-dev` to recreate.

Help improve ai-dev

ai-dev is being evaluated on real-world coding-agent workflows.

If you want to support development, you can optionally enable privacy-preserving opt-in telemetry without persistent user identifiers.

Community Telemetry is OFF by default. Installation never automatically activates it.

Commands

ai-dev telemetry sharing status
ai-dev telemetry sharing enable basic
ai-dev telemetry sharing enable research
ai-dev telemetry sharing disable
ai-dev telemetry sharing preview
ai-dev telemetry sharing flush

• OFF: Nothing is collected or sent.
• BASIC: Minimal operational metrics (command name, category, outcome, duration bucket, OS family, Python version).
• RESEARCH: BASIC metrics plus model provider usage (model name, token counts, task outcome, repo size bucket).

Default production endpoint: https://35.209.177.185.sslip.io/v1/events (can be overridden with AI_DEV_COMMUNITY_TELEMETRY_ENDPOINT).

Never shared:

• source code
• prompts
• model responses
• repository names
• file names or paths
• usernames/emails
• secrets/API keys

Preview what data fields would be shared from your repository:

ai-dev telemetry sharing preview --level research

Or view a synthetic example payload:

ai-dev telemetry sharing preview --level research --sample

For complete details on data handling, allowed scalar metrics, and local queueing, see docs/community-telemetry.md.

Install

python -m pip install --upgrade pipx
pipx install ai-dev-cli-tools==1.3.0
ai-dev --help

For a source checkout, use pipx install .. See docs/DISTRIBUTION.md for the Trusted Publishing and upgrade policy.

For development:

python scripts/dev.py --check

This creates a locked, repository-local .venv, disables ambient user-site packages, and routes temporary validation files through .ai/tmp/dev. Run python scripts/dev.py --diagnose for machine-readable Git metadata, temp-directory, Python, and proxy diagnostics without installation.

Windows

.\ai.ps1 doctor
ai-dev scan --project "C:\path with spaces\project"

Linux and macOS

./ai.sh doctor
ai-dev check --mode fast --project "/path/with spaces/project"

Commands

ai-dev doctor
ai-dev scan
ai-dev map --max-files 500 --max-depth 6
ai-dev check --mode fast
ai-dev check --mode changed  # reports changed files and falls back safely when test mapping is uncertain
ai-dev check --mode full --jobs 4
ai-dev check --mode changed --policy feedback-first --resume
ai-dev check --mode changed --compare main
ai-dev check --mode changed --retry-flaky 1
ai-dev check --mode changed --retry-infra 1
ai-dev plan --task "implement rate limiting" --mode changed
ai-dev task --task "implement rate limiting" --client codex --json
ai-dev index update
ai-dev index daemon start
ai-dev index daemon status
ai-dev index daemon stop
ai-dev semantic status
ai-dev semantic index --backend auto
ai-dev policy assess -- python -m pytest
ai-dev sarif --input .ai/reports/agent-plan.json
ai-dev cache status
ai-dev cache layout
ai-dev baseline create main
ai-dev baseline compare main
ai-dev benchmark run --suite examples/benchmarks/output-budget-smoke.json --variant baseline
ai-dev benchmark corpus --manifest examples/benchmarks/agent-corpus.json --trials 3
ai-dev integrations install all
ai-dev integrations install gemini
ai-dev dashboard serve --port 8765
ai-dev telemetry import response.json --client codex --format openai
ai-dev telemetry import gemini-response.json --client gemini --format gemini
ai-dev telemetry status --json
ai-dev telemetry optimize --min-sessions 5 --json
ai-dev telemetry export --format csv --output .ai/telemetry-exports/usage.csv --json
ai-dev telemetry gate --json
ai-dev telemetry pricing import pricing.json --provider openai --version 2026-09-01
ai-dev telemetry pricing activate openai 2026-09-01
ai-dev explain issue:<id> --tail 100
ai-dev explain --symbol "src/app.py#Application.run" --tail 100
ai-dev feedback --task "fix authentication timeout"
ai-dev feedback --task "fix authentication timeout" --ack-state <state-fingerprint>
ai-dev feedback --task "fix authentication timeout" --no-delta  # force the full payload
ai-dev watch --mode changed --debounce 500
ai-dev session status
ai-dev bootstrap --if-needed
ai-dev environment explain
ai-dev diagnostics
ai-dev completion bash
ai-dev mcp serve
ai-dev test affected
ai-dev test flaky
ai-dev logs summarize
ai-dev context build
ai-dev git status
ai-dev git inspect
ai-dev finish

All commands support --project, --json, --quiet, --help, and --version at the top level.

Local MCP server

ai-dev mcp serve exposes project status, implementation planning, compact feedback, bounded context, validation, and progressive evidence as local structured tools for clients including Gemini CLI. The STDIO server is dependency-free, has no network listener, fixes all calls to one project root, and defaults validation to preview-only. After consuming a successful build_context response, a client can return its summary.delta.state_fingerprint as acknowledged_state; an identical safe state then becomes a compact receipt, while changed or unsafe context remains live.

codex mcp add ai-dev -- ai-dev --project "/absolute/path/to/project" mcp serve

See docs/MCP_SERVER.md for tool schemas, approvals, project-scoped configuration, and security boundaries.

For the recommended agent loop—plan, retrieve, implement, validate, and expand only failed evidence—see docs/AGENT_WORKFLOW.md.

For agents sharing a repository, ai-dev agents add|claim|heartbeat|release|complete|status maintains an atomic local task board with expiring leases and declared-path conflict detection. See docs/AGENT_COORDINATION.md for the workflow and safety limits.

Bootstrap

ai-dev bootstrap prepares a detected project with conservative, project-local commands. Use --explain to see the plan without modifications, --dry-run to validate planning without executing modifying commands, and --create-env to allow copying .env.example to .env only when .env is missing.

Supported strategies include Python uv, Poetry, pip with pyproject.toml, pip with requirements.txt, Node npm/pnpm/Yarn, Maven wrapper or system Maven, Gradle wrapper or system Gradle, Cargo, and Composer.

See docs/BOOTSTRAP.md for safety rules and configuration.

Managed application runtime

ai-dev run supports explain, dry-run, foreground, and supervised background modes. ai-dev stop sends a token-authenticated request to the matching local supervisor and never kills an arbitrary PID read from stale state. See docs/RUNTIME.md.

Context Builder

ai-dev context build creates a bounded local context package for coding agents without calling any LLM, embedding API, or cloud service.

ai-dev context build --task "fix auth tests"
ai-dev context build --changed-only --max-chars 50000
ai-dev context build --incremental  # emits only candidates changed since the last pack
ai-dev context build --incremental --since <context-id>
ai-dev context build --compare main
ai-dev context build --profile review
ai-dev context build --profile implement
ai-dev context build --profile docs
ai-dev context build --retrieval auto --explain  # explains retrieval or abstention
ai-dev context build --tokenizer o200k_base --token-budget source=8000 --token-budget diffs=2000
ai-dev context build --refine issue:<id> --refinement-rounds 2 --refinement-max-files 5
ai-dev context build --compression conservative
ai-dev context build --adaptive  # task-aware budget; uncertainty expands, explicit limits win
ai-dev context build --include "src/**/*.py" --exclude "tests/fixtures/**"
ai-dev context build --explain --json

Artifacts are written to .ai/context/context-latest.md and .ai/context/context-latest.json by default. The builder includes detected technologies, git state, changed files, related tests, validation plan, recent commits, selected snippets, limited diffs, latest check errors, masked secret findings, and budget/truncation metadata. Large Python files use AST-aware symbol snippets, while large JavaScript and TypeScript files use conservative top-level symbol selection instead of blindly returning only the beginning of the file.

Selective retrieval defaults to auto: focused includes or changed files can abstain from broad cross-file retrieval, while missing focus, broad configuration changes, and broad task scopes fall back to the full candidate set. Use --retrieval always to expand or --retrieval never to keep only focused roots and inferred related tests. The JSON and Markdown reports explain the decision and expose a related-test false-negative proxy.

Install ai-dev-cli-tools[tokenizers] to enable exact local cl100k_base or o200k_base counting. Without that optional extra, accounting uses the explicit UTF-8-bytes/4 estimate and reports a fallback if an exact tokenizer was requested. Repeated --token-budget category=N limits source, diffs, tests, logs, maps, history, cached input, or output independently. --provider-usage <json> normalizes OpenAI, Anthropic, or Gemini usage fields from a project-local file without network access.

ai-dev task is the default one-shot handoff for an AI client. It combines the bounded plan, selected context, and check preview while delivering file references instead of full content. Use --include-content only when the consumer truly needs the bodies. The response includes a state fingerprint and a token savings receipt; return that fingerprint with --ack-state only after consuming the response. Explicit acknowledgements are stored per client under .ai/cache/client-state/, so Codex, Claude Code, Cursor, Gemini CLI, and generic consumers never inherit one another's assumed context. Receipts remain local under .ai/token-efficiency/.

Provider-reported usage can be recorded through MCP record_usage or imported from a bounded, project-local JSON/JSONL file with ai-dev telemetry import. OpenAI Responses, Anthropic, and a stable generic envelope for Cursor or other clients are normalized without retaining prompt or response content. telemetry status and the loopback dashboard aggregate input, cached input, output, and reasoning tokens by client. Optional cost values are local estimates computed from .ai-dev/telemetry-pricing.json; no changing provider price is hardcoded and no value is presented as a provider invoice. See docs/INTEGRATIONS_AND_DASHBOARD.md. Project-local .ai-dev/telemetry-budgets.json can enforce rolling aggregate limits globally, per client, and per model, and compare two chronological session windows for token or cost regressions. ai-dev telemetry gate returns a failing report for violations, while MCP record_usage immediately returns the active alerts and read-only usage_status provides a compact pre-flight check.

telemetry optimize calculates deterministi