ai-dev-cli-tools MCP server
Commit Nov 10, 2026Optimizes AI coding agent workflows by converting raw development logs into compact, deterministic Markdown and JSON reports to save tokens.
Also known as MatthiasLew/ai-dev-cli-tools
- Stars
- 3
- Tools
- 1
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 10, 2026
- License
- MIT
What is ai-dev-cli-tools MCP?
ai-dev-cli-tools optimizes AI coding agent workflows by converting raw development logs into compact, deterministic Markdown and JSON reports to save tokens. It exposes 1 tool, such as prompts.
Summary generated from the project's README
About ai-dev-cli-tools MCP server
Reducing token consumption for AI coding agents is what ai-dev-cli-tools enables by converting massive development logs into compact Markdown and JSON reports. Instead of forcing an LLM to read through entire test outputs, repository trees, or raw Git diffs, this tool runs local scripts to collect data and provides the agent with a concise summary to decide its next move. It manages all state, including logs and context artifacts, within a local .ai directory that is ignored by Git.
Developers use the ai-dev mcp serve command to expose project status, implementation planning, and bounded context as structured tools via STDIO. This local setup requires no network listener and is designed to work with clients like Gemini CLI. The system includes specialized commands like context build for creating task-specific packages and task for one-shot handoffs that deliver file references instead of full content to save costs. It also features a coordination system for multiple agents to claim or release tasks using an atomic local task board.
What you can do with it
- 1Minimize token usage during coding tasksAn AI agent can receive a compact summary of project changes and test results instead of reading through massive raw logs.
- 2Generate task-specific context packagesA developer can instruct an AI to build a bounded context for a specific issue without using any external LLM or cloud services.
- 3Coordinate multiple AI agents on one repoTeams using multiple agents can prevent conflicts by using a local task board with expiring leases.
- 4Perform safe project bootstrappingPrepare a new project environment by automatically detecting technologies like Python, Node, or Rust and applying conservative local commands.
Written from the project's README. Every use case is checked against a quote from it.
ai-dev-cli-tools MCP tools 1
Detected from the READMEprompts
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablematthiaslew/ai-dev-cli-tools is public and reachablegithub.com/matthiaslew/ai-dev-cli-tools ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-10github.com/matthiaslew/ai-dev-cli-tools ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model1 tool description and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubAI 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/.
Ecosystem integrations
HOL Guard
HOL Guard includes an opt-in
command.ai-dev safety extension for reviewing sensitive ai-dev commands.
The integration was merged upstream in PR #2943
on October 12, 2026.
The extension provides structured evidence for policy review of:
ai-dev integrations install --force— forced integration configuration overwrites.ai-dev index daemon start/stop— background indexer lifecycle changes.ai-dev agents claim/release— agent task coordination changes.
It is registered as an external, opt-in extension in HOL Guard. See the extension descriptor and command rules for the integration contract.
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 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
| Command | Status |
|---|---|
| doctor | implemented |
| scan | implemented |
| map | implemented |
| check | implemented |
| check --explain | implemented |
| test affected | implemented |
| test flaky / check --retry-flaky | implemented |
| index status/update/rebuild | implemented |
| index daemon | implemented |
| plan / MCP plan_work | implemented |
| task / MCP prepare_task | implemented with reference-first delivery and token receipts |
| semantic status/index | implemented with built-in Tree-sitter, LSP, and provider plugins |
| policy assess / execution enforcement | implemented |
| sarif | implemented |
| cache status/prune/clear/layout | implemented |
| logs summarize | implemented |
| context build | implemented |
| diagnostics | implemented |
| mcp serve | implemented |
| watch | implemented |
| benchmark run/compare/gate/corpus | implemented |
| integrations install | implemented for Codex, Claude Code, Cursor, Gemini CLI, and generic MCP |
| dashboard status/serve | implemented, loopback-only |
| telemetry import/status and MCP record_usage | implemented, provider-reported usage only |
| telemetry gate/pricing snapshots and MCP usage_status | implemented, local and fail-closed |
| p50/p95 token optimizer and accuracy-first model recommendations | implemented, read-only |
| aggregated telemetry export and latency trends | implemented, content-free |
| performance latest/compare | implemented |
| capabilities | implemented |
| git status | implemented |
| git inspect | implemented |
| finish | implemented |
| bootstrap | implemented |
| environment explain | implemented |
| run | implemented |
| stop | implemented |
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 buildis implemented as a bounded local context pack builder.bootstrapis 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
ai-dev 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.
ai-dev-cli-tools MCP questions
What tools does ai-dev-cli-tools MCP provide?
It exposes 1 tool, including prompts.
How can I use this as an MCP server?
You can run 'ai-dev mcp serve' to expose project status, implementation planning, and bounded context as structured tools for clients like Gemini CLI.
Does the tool share my source code or secrets?
No, the tool is designed to never share source code, prompts, model responses, repository names, file paths, or secrets.
How do I install the toolkit?
You can install it using pipx with the command: pipx install ai-dev-cli-tools==1.3.0