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.

Install

python -m pip install --upgrade pipx
pipx install ai-dev-cli-tools==1.2.2
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 deterministic p50/p95 usage, latency, cache share, cost, and quality attribution by client, model, phase, tool, task kind, and day. It recommends rolling token ceilings with an explicit safety margin. Cheaper-model recommendations appear only when both models have enough local quality samples, the candidate meets the configured accuracy target, complete same-currency cost evidence proves a saving, and the allowed accuracy drop is respected. It never switches a model or overwrites a policy. MCP clients can call the read-only optimize_usage tool for the same report. telemetry export writes only this aggregated evidence as JSON or CSV inside the project. It excludes request IDs, prompts, responses, and repository content and refuses to overwrite an existing file.

Incremental mode stores the latest schema-versioned manifest plus up to 50 content-addressed historical manifests under .ai/cache/, and reports changed versus reused files. Pass --since <context-id> to compare against an explicitly retained context. Default limits are --max-chars 50000, --max-files 30, --max-file-chars 8000, and --max-diff-chars 15000. Secret-bearing and generated paths such as .env, private keys, caches, build output, .ai/logs, and .ai/reports are excluded from snippets.

Reports and Logs

Validation results are cached by default using repository, command, workspace, runtime, and platform fingerprints; use check --no-cache to force execution. check --resume reuses only exact successful checkpoint fingerprints. --policy feedback-first runs cheaper waves first and cancels later expensive waves after a required failure; complete retains comprehensive execution. index status/update/rebuild manages the reusable repository index, while cache status/prune/clear provides bounded local cache maintenance; cache layout emits a deterministic stable-prefix manifest and provider breakpoint recommendations. See docs/CACHE_AND_INDEX.md.

Short reports are written to .ai/reports/ as Markdown and JSON. Full command output is written to .ai/logs/ and ignored by Git. Check summaries include exit codes, durations, first failure hints, grouped repeated messages, test counts, and full log paths.

JSON reports use schema 1.1 with schema_version, tool_version, command, status, exit_code, timestamps, project_root, summary, issues, artifacts, and metadata.

ai-dev feedback combines Git changes, changed validation, adaptive incremental context, focused rerun hints, stage timings, and local session state into one compact agent protocol report. Adaptive context remains local and deterministic, scopes unchanged-file memory to a normalized task fingerprint, broadens uncertain requests, and never overrides explicit limits. A client may acknowledge the previous delta.state_fingerprint through --ack-state; only then can identical successful feedback become a small receipt. This prevents one AI client from inheriting another client's assumed context. Failures and warnings always remain live, and --no-delta forces the complete response. Its observation lifecycle replaces superseded results with content-addressed IDs expandable through ai-dev explain; see docs/OBSERVATION_LIFECYCLE.md.

Every expandable issue, check, file, snippet, diff, workspace, and artifact receives a stable local evidence_id. The report metadata lists references; ai-dev explain <evidence-id> --tail 100 retrieves only that evidence. ai-dev baseline create <name> stores a compact local snapshot under .ai/cache/baselines/, and baseline compare <name> leads with new/resolved failures, issue codes, and status regressions. Pass --compare <name> to check or context build to apply that regression contract directly to the current report. Reproducible local A/B suites use benchmark run and benchmark compare; see docs/BENCHMARKS.md. Research-backed context and token-efficiency recommendations are documented in docs/TOKEN_EFFICIENCY_RESEARCH.md.

Auto Detection

scan detects Python, Node.js, Java, Rust, PHP, Docker, Make, CI workflows, package managers, scripts, entrypoints, tests, lint, formatters, type checkers, and .env.example variables.

Supported examples:

• Python: pyproject.toml, requirements.txt, pytest, ruff, black, mypy, coverage.
• Node.js: package.json, npm, pnpm, yarn, Jest, Vitest, ESLint, Prettier, TypeScript.
• Java: Maven, Gradle, tests, Checkstyle, SpotBugs, JaCoCo when configured.
• Rust: Cargo test, fmt, clippy.
• PHP: Composer, PHPUnit, PHPStan, PHP-CS-Fixer when configured.

Configuration

Optional .ai-dev-tools.toml:

[project]
name = "example-project"

[commands]
test = "pytest"
lint = "ruff check ."
typecheck = "mypy src"

[ignore]
paths = ["node_modules", ".venv", "dist", "build"]

[reports]
directory = ".ai/reports"
logs_directory = ".ai/logs"

[execution]
mode = "enforce"
maximum_impact = "high"
allow_prefixes = ["python -m pytest", "python -m ruff", "python -m mypy"]
deny_prefixes = ["git reset", "git clean"]

Configuration takes precedence over auto detection. Invalid or unknown configuration is reported through config_warnings instead of crashing normal scans.

Local Validation

Before pushing a larger stage, run:

python -m ruff check .
python -m mypy src tests scripts
python -m coverage run -m pytest
python -m coverage report --fail-under=90
python -m build
python scripts/validate_ci.py
python scripts/test_installed_package.py
git diff --check

python scripts/test_installed_package.py rebuilds the wheel, installs only that wheel into a clean virtual environment in a path containing spaces, and verifies the installed ai-dev entrypoint without editable install or PYTHONPATH.

Command Status

Scope Notes

The planned product capability set is complete as of 1.2.0. See docs/PROJECT_COMPLETE.md for the maintenance boundary and the exact acceptance evidence required for future changes.

• Monorepo/workspace detection and per-subproject command routing: implemented.
• Per-subproject check and bootstrap working directories: implemented.
• Runtime requirement detection and version validation: implemented.
• context build is implemented as a bounded local context pack builder.
• bootstrap is implemented as a conservative local setup planner/executor.
• Auto-commit, auto-push, destructive cleanup, remote source transmission, and GUI are intentionally out of scope.

Intentional Limits

Version 1.2.0 does not reset, clean, commit, push, merge, clone organizations, synchronize repositories, delete containers, publish releases, or remove user files.

Shell completion scripts are generated with ai-dev completion bash|zsh|fish|powershell and can be sourced or installed using the normal mechanism for the selected shell.