Start a timer for a discrete coding task and, when historical data is available, return a duration estimate derived from similar past tasks.

When to use: before starting any distinct unit of work — a bug fix, a feature, a refactor, a test-writing pass. Use one task per logical unit; do not batch unrelated changes under a single task. Always pair with velocity_end_task so the task row is closed and the dataset stays clean.

Side effects: inserts a new row into the local SQLite database at ~/.velocity-mcp/tasks.db (override via HOME). Computes a best-effort duration prediction by querying historical rows of the same category/tags; predictions run locally and are cached per-task. Federated upload is disabled unless the user has explicitly opted in via velocity-mcp federation enable.

Returns: JSON with task_id (pass this to velocity_end_task), started_at ISO timestamp, message, and — when enough historical data exists — a prediction block containing point estimate in seconds, p25/p75 range, confidence (low/medium/high), whether the estimate was calibrated, and whether it drew on federated data.

Stop a task timer started with velocity_start_task, record the outcome, and return the actual duration alongside a comparison to the historical median for similar tasks.

When to use: immediately after finishing — or abandoning — any task started with velocity_start_task. Always call, even on failed or abandoned outcomes; skipping leaves orphaned active rows that pollute future predictions and stats.

Side effects: updates the task row in ~/.velocity-mcp/tasks.db with end timestamp, duration, status, optional file/line counts, and any telemetry passed in. Shells out to git diff --stat HEAD~1 and git log --since (5s timeout each) to capture diff stats; safely no-ops outside a git repo. On completed status: computes a semantic embedding for similarity matching, records a calibration residual, and — if the task belonged to a plan — seals the plan when its last active task ends.

Returns: JSON with task_id, duration_seconds (numeric), duration_human (formatted), category, tags, and a message that compares this run's duration to the historical median for the category+tags combination ("you were 23% faster", "right on pace", etc.). Includes a git_diff block with lines added/removed, files changed, and commits made during the task when a git repo is detected.

Detect documentation drift — find places in README.md, CHANGELOG.md, and other project markdown where the docs reference commands, flags, APIs, or files that the code no longer matches.

When to use: before tagging a release, after large refactors or renames, when onboarding a new contributor, or as a periodic health check. Set git: true to additionally flag docs that have not been touched since a closely related source file changed significantly.

Side effects: reads all markdown files and source files reachable from the project root (respecting .gitignore). Never writes, auto-fixes, or moves files — this is a pure reporting tool.

Returns: plain-text, JSON, or markdown report listing each drifted section with file:line references and a one-line explanation of the mismatch (e.g. "README references --deep flag removed in src/cli.ts:42"). Exit 1 if any drift is found.

Validate a project's .env files against its envalid schema — catch missing required variables, type mismatches, and values outside allowed ranges.

When to use: before booting the app locally, during CI, after a teammate adds a new required env var, or when switching between development and production configs. Pass environment to validate a specific .env.{env} file.

Side effects: reads .env, .env.local, and .env.{environment} from the project root, and reads the envalid schema (typically src/env.ts or a similar file exporting cleanEnv(...)). Does not write or transmit env values anywhere — validation is local-only.

Returns: plain-text, JSON, or markdown report listing each declared variable, whether it is present, whether its value matches the expected type, and any schema-level validation errors with file:line references. Exit 1 on any validation failure.

Scan a project for port conflicts between ports declared in common dev-server config sources (.env files, package.json scripts, docker-compose.yml, devcontainer.json, Procfile, Makefile, framework defaults, and a project-local .berthrc) and ports currently listening on the host.

When to use: before running npm run dev, docker compose up, or any other dev-server command — especially after switching branches in a monorepo where multiple services may want the same port. Safe to call repeatedly; read-only and side-effect free.

Side effects: enumerates listening TCP ports on the host via platform-appropriate commands (lsof on macOS/Linux, netstat on Windows) and inspects running Docker containers for published ports. Reads only the config files listed above; never opens, closes, or binds any ports. No network I/O beyond local loopback checks.

Returns: plain-text (or JSON) report listing each configured port, whether it is free or in use, and — for occupied ports — the PID and process name of the holder. Exit 1 when a conflict is detected, 0 otherwise.

Detect the project's tech stack and regenerate AI context files (CLAUDE.md, .cursorrules, .windsurfrules, AGENT.md) from the project's .aware.json config.

When to use: after adding or removing a framework/language, when AI context files fall out of date, or when onboarding a new agent to the repo. Do not call on every turn — run once per session or after stack changes.

Side effects: reads package.json, requirements.txt, pyproject.toml, go.mod, Cargo.toml, and similar manifest files to detect the stack. Writes or overwrites CLAUDE.md, .cursorrules, .windsurfrules, and AGENT.md in the project root based on .aware.json templates. Never modifies source code.

Returns: plain-text summary listing the detected stack, the files written (or that would be written, in dry-run mode), and any errors. Exit 0 on success, non-zero on failure.

Scan all dependency licenses in a project and — if a policy file is present — validate each package against that policy, flagging disallowed licenses (e.g. GPL in a proprietary codebase) or packages with unknown licenses.

When to use: before shipping a release, when adding a new dependency, during compliance or legal review, or as a CI gate. Set production: true to skip devDependencies and audit only what actually ships.

Side effects: reads supported lockfiles (package-lock.json or npm-shrinkwrap.json for Node; Cargo.lock for Rust; requirements.txt with hashes, uv.lock, or poetry.lock for Python) plus local node_modules / vendor manifests to resolve license strings. Pnpm, yarn, and go are not yet supported — vow exits with a clear error when only those lockfiles are present. Read-only; no network requests.

Returns: plain-text, JSON, or markdown summary of package → license mapping grouped by license family (MIT/Apache/BSD/GPL/unknown), with per-package links. Exit 1 if any dependency violates the policy or has an unknown license, 0 otherwise.