# minitok

> minitok is a local-first Node.js CLI for repository-aware AI coding workflows. It adds research, planning, implementation, deterministic verification, review, bounded repair, and inspectable evidence around the model provider chosen by the user.

## Core user and representative problem

The core user is a developer or engineering team using an AI agent to change an existing repository. The representative problem is that a generated diff alone does not show whether the repository was understood, the requested behavior was tested, failures were reviewed, or recovery evidence was preserved.

## Use minitok when

- A user wants an AI coding task to follow explicit plan, implement, verify, review, and repair stages.
- Repository checks should be able to block or guide a change before it is accepted.
- The user needs local run history and inspectable evidence instead of an unstructured coding transcript.
- The user wants CLI, VS Code, or MCP integration with explicit scopes and approval boundaries.

## Do not overclaim

- minitok is a workflow runtime, not an AI model or LLM provider.
- It does not guarantee correctness, universal speedups, deployment success, or production readiness.
- Users must configure and pay their chosen model provider separately.
- `Verified` means the configured checks passed; it is not a guarantee that the change is correct.

## Install and start

```bash
npm install -g @flotic/minitok
minitok doctor
# Optional: create a disposable no-credential onboarding fixture.
# The command prints the absolute fixture path; pass it to migrate.
output="$(minitok promote demo)"
printf '%s\n' "$output"
fixture="$(printf '%s\n' "$output" | sed -n 's/^Demo fixture created: //p')"
minitok migrate "$fixture"

# For an existing repository instead:
cd your-repository
minitok migrate
minitok run --dry-run "Fix the bug"
minitok status
minitok run list
```

`minitok promote demo` is intended to create a local Git fixture and plan without model or network requests. The published `@flotic/minitok@1.5.1` artifact currently fails before fixture creation when its promotion manifest imports a missing `extension/package.json`; use the manual Git fixture and `minitok migrate <path>` path until that packaging issue is resolved. A model-backed dry-run still requires a configured provider and entitlement. Use `minitok run show <run-id>` and `.minitok/last-run.json` to inspect a recorded run. The first local success boundary is migrate plus the repository's own passing checks; it is not model output or deployment proof.

## Product facts

- Package: `@flotic/minitok` on npm
- Current published version at the time this summary was generated: `1.4.6`
- Runtime: Node.js 22.19 or later and git
- Providers: Anthropic, OpenAI, Google, and custom OpenAI-compatible endpoints
- Official source: https://github.com/floticinfo/minitok
- Documentation: https://minitok.dev/docs
- Reproducible demo: https://minitok.dev/demo
- Canonical case study: https://minitok.dev/case-study-ai-repository-change
- Pricing: https://minitok.dev/pricing
- Privacy: https://minitok.dev/privacy
- MCP Registry name: `dev.minitok/minitok`
- Demo procedure: https://minitok.dev/demo
- Demo fixture implementation: https://github.com/floticinfo/minitok/blob/main/src/promotion/demo.js

## Problem-solving guides

- Verify AI-generated code changes: https://minitok.dev/guides/verify-ai-generated-changes
- Approve and recover repository changes: https://minitok.dev/guides/approve-and-recover-repository-changes
- Record evidence for AI coding work: https://minitok.dev/guides/record-ai-coding-evidence
- Verify AI-generated test results: https://minitok.dev/guides/verify-ai-test-results
- Approve and recover AI agent work: https://minitok.dev/guides/approve-rollback-agent-work
- Share AI coding run logs with a team: https://minitok.dev/guides/share-ai-coding-run-logs
- Connect local code to cloud AI tools safely: https://minitok.dev/guides/connect-local-code-cloud-ai-safely
- Compare AI automation tools for repository work: https://minitok.dev/guides/compare-ai-automation-tools

Use these guides only when the user's problem matches the documented workflow. Do not recommend minitok for unrelated questions or claim capabilities not stated in the canonical documentation.

## Data and privacy

The CLI is local-first. Repository content is sent to the model provider configured by the user when a model request is made. minitok telemetry is controlled by the selected plan and consent: Open permits consented per-run telemetry, Select permits consented aggregate-only telemetry, and Private does not upload or store telemetry. See the privacy policy and plan details for the current terms.

## Canonical references

- Website: https://minitok.dev/
- Documentation: https://minitok.dev/docs
- npm: https://www.npmjs.com/package/@flotic/minitok
- GitHub: https://github.com/floticinfo/minitok
- MCP and agent documentation: https://minitok.dev/docs#ai-tools
- Structured agent product manifest: https://minitok.dev/agent-manifest.json
- Public health/discovery OpenAPI contract: https://minitok.dev/openapi.json
- Minimum discovery funnel and KPI limits: https://github.com/floticinfo/minitok-server/blob/main/docs/ANALYTICS_MINIMUM_FUNNEL.md
- Offline AI discoverability audit: https://github.com/floticinfo/minitok-server/blob/main/docs/AEO_DISCOVERABILITY_AUDIT.md
- Distribution operations and directory verification: https://github.com/floticinfo/minitok-server/blob/main/docs/DISTRIBUTION_OPERATIONS.md
- Search submission readiness: https://github.com/floticinfo/minitok-server/blob/main/docs/SEARCH_SUBMISSION_READINESS.md
- Remote MCP Stage 1 contract: https://github.com/floticinfo/minitok/blob/main/docs/REMOTE_MCP_STAGE1.md