 ███╗   ███╗██╗███╗   ██╗████████╗
 ████╗ ████║██║████╗  ██║╚══██╔══╝
 ██╔████╔██║██║██╔██╗ ██║   ██║
 ██║╚██╔╝██║██║██║╚██╗██║   ██║
 ██║ ╚═╝ ██║██║██║ ╚████║   ██║
 ╚═╝     ╚═╝╚═╝╚═╝  ╚═══╝   ╚═╝

Disciplined agentic development for Claude Code

v0.7.5 — Parallel execution. File freezing. Smart browser. Zero slop.

Core philosophy: Slop is an engineering problem, not an LLM problem. If an agent produces bad code, fix the environment — never patch the output.

Install

curl -fsSL https://raw.githubusercontent.com/3li7alaki/mint/main/install.sh | bash

This installs the mint CLI globally and (if Claude Code is installed) the Claude plugin for auto-routing.

CLI

mint init                       # Claude reads your project, configures mint perfectly
mint init --yes                 # headless — auto-detect, no prompts (CI/scripts)
mint config                     # view current config
mint config --global            # view global user defaults
mint config set key value       # edit project config (dot notation, validated)
mint config set --global k v    # set a global default
mint config list                # show all available config keys with types and defaults
mint doctor                     # health check — static checks + tiered output
mint doctor --fix               # health check + Claude applies context-aware fixes
mint update                     # update mint + Claude migrates ALL registered projects
mint clean                      # remove stale worktrees from parallel execution

Global Defaults

Set user preferences that apply to all projects:

mint config set --global autoCommit false
mint config set --global reviewers.security.model opus
mint config set --global isolation.plan worktree

Global config lives at ~/.mint/config.json. Project config always overrides global. Global config also tracks a project registry — every mint init registers the project, and mint update migrates all registered projects at once.

Project Setup

Run mint init in your project (seeds from global defaults if set):

.mint/
├── config.json             — gates, reviewers, browser, design, plugins
├── hard-blocks.md          — what agents can never do
├── issues.jsonl            — failure log (JSONL — concurrent-safe, grep-able)
├── wins.jsonl              — success log (JSONL)
├── patterns.jsonl          — graduated recurring patterns (JSONL)
├── instincts.jsonl         — auto-learned conventions (JSONL)
├── sessions/               — per-session state files (gitignored)
│   └── <session-id>.json  — one file per concurrent Claude Code session
├── .freeze-list.json       — frozen/guarded file paths (gitignored)
├── .browser-sessions.json  — browser cookie persistence (gitignored)
└── .gate-ledger.jsonl      — gate run tracking for dedup (gitignored)

How It Works

You describe what you want. mint auto-detects the right approach:

| What you say | What mint does | |---|---| | Small fix, typo, config tweak | Quick — fixes directly, gates enforced | | Feature, component, API route | Plan — decomposes into XML specs, executes atomically | | Multiple features, batch of work | Ship — interviews you, plans phases, executes all | | "Browse to", "scrape", "debug in browser" | Browse — PinchTab-powered browser automation | | "How should I...", "Compare..." | Research — investigates, saves structured report | | "Check quality", "Audit" | Verify — runs all gates and audits | | "Design review", "Design profile" | Design — design intelligence commands | | "Set up doc tracking" | Doc Setup — scans docs, maps sections to code, builds manifest | | "Optimize my setup", "Am I using mint fully?" | Optimize — full audit of config, docs, workspace, agents, features | | /freeze src/auth/ | Freeze — blocks all file modifications under that path | | /guard package.json "no new deps" | Guard — freeze + reason shown to agents | | /unfreeze --all | Unfreeze — remove all freezes |

No commands to memorize. Just describe what you want to build.

The Pipeline

You describe a feature
        │
  Challenge (optional) — is this the right thing to build?
        │
  Decompose into XML specs with dependency graph
        │
  Build wave plan from <depends-on>:
    Wave 1: [001, 002]     ← independent, run in parallel
    Wave 2: [003, 004]     ← depend on wave 1, parallel
    Wave 3: [005]          ← depends on 003 + 004
        │
  Per wave: dispatch specs (parallel Agent calls or parallel worktree sessions)
        │
  Per spec:
    Fresh subagent executes (reads existing code, matches patterns)
    → Gates: lint → types → tests
    → Stage 1: Spec reviewer (gate)
    → Stage 2 (parallel, scaled by diff size):
        Quality + Security + Conventions + Tests + Business + Performance + Design
    → Atomic commit
    → Doc-manifest check: update stale documentation
        │
  You review the final result

Parallel execution: Independent specs run simultaneously — either as parallel Agent calls within one session, or as separate claude -p processes in isolated git worktrees. Concurrency is configurable (default: 3). Scope enforcement prevents parallel specs from modifying the same files.

Ecosystem & Integrations

mint integrates with best-in-class external tools. Each is optional and toggleable — mint works without any of them, but they make it significantly more capable.

| Tool | What it does for mint | Install | |------|----------------------|---------| | PinchTab | Browser automation — navigate, scrape, debug, screenshot via lightweight Go binary + Chrome. Agents talk to it via HTTP API, get compact accessibility tree (~800 tokens vs 10k+ raw DOM). | curl -fsSL https://pinchtab.com/install.sh \| sh | | context-mode | Sandboxed execution + FTS5 search + session continuity. Keeps verbose tool output out of context window. ~97% token savings on test output, ~99% on URL fetching. | claude mcp add context-mode -- npx -y context-mode | | Impeccable | Design steering commands (/polish, /audit, /critique, /bolder, etc.) with curated anti-patterns and design vocabulary. By Paul Bakaus, Apache 2.0. | npx skills add pbakaus/impeccable |

mint init offers to install each one. mint update keeps them current. mint doctor checks their health.

Core Features

Parallel Execution

Specs don't run one-by-one. mint builds a dependency graph from <depends-on> fields, groups independent specs into waves, and dispatches them in parallel.

Two modes:

In-session: Parallel Agent calls within one Claude Code session (no isolation needed for non-overlapping scopes)
Multi-session: Separate claude -p processes, each in its own git worktree. Fully isolated. Configurable concurrency (default: 3).

{
  "isolation": { "plan": "worktree" },
  "parallel": { "concurrency": 3, "maxBudgetPerSpec": 5.0 }
}

After a wave completes, worktree branches merge back. Scope enforcement via the pre-edit hook prevents parallel specs from touching the same files. Cleanup: mint clean.

File Freezing

Protect files and directories from modification. The pre-edit hook hard-blocks writes — agents can't bypass it.

/freeze src/auth/                          # Block all edits under src/auth/
/guard package.json "no new deps"          # Block + tell agents why
/freeze src/**/*.test.ts                   # Glob patterns work
/unfreeze src/auth/                        # Remove specific freeze
/unfreeze --all                            # Remove all

Agents see the block reason and must adjust their approach — find an alternative, skip the file, or ask you. Session-scoped (clears when task completes).

Scope Enforcement

Every spec declares <can-modify> and <cannot-modify>. The pre-edit hook reads the active spec and blocks writes outside scope — not advisory, not cooperative. Hard block.

If an agent legitimately needs a file outside scope, it stops and reports the blocker. The orchestrator can expand scope with your approval.

Browser Support

Built-in browser automation powered by PinchTab. Not a plugin — a core feature. Agents can navigate pages, fill forms, scrape data, take screenshots, and debug live apps.

How it works: PinchTab runs a lightweight Go binary that controls Chrome via an HTTP API. mint agents talk to it with curl — no Puppeteer, no Selenium, no heavy dependencies. The accessibility tree gives agents a compact page representation (~800 tokens vs 10k+ for raw DOM).

# Install PinchTab (mint init offers to do this)
curl -fsSL https://pinchtab.com/install.sh | sh

# WSL2: also install Linux-side Chromium
sudo apt install -y chromium-browser

# Start it
pinchtab &

What agents can do:

Navigate to URLs and interact with elements (click, type, select)
Extract structured data from pages
Debug live apps — check console errors, DOM state, localStorage
Verify UI changes after implementation
Capture screenshots for review
Persistent sessions — login once, cookies survive between tasks

Commands:

/browse <url> [task] — navigate and interact
/screenshot [url] — capture page state
/scrape <url> [what] — extract structured data
/browser login <url> — log in manually, mint saves the session
/browser sessions — list saved sessions

Smart, not blind: Agents poll for page readiness instead of sleep 3. Error recovery diagnoses failures (stale refs, timeout, PinchTab down) and retries intelligently. Auto-starts PinchTab if not running.

Token-efficient: Agents use the cheapest PinchTab endpoint per task — /text for content (~800 tokens), filtered snapshots for interactions (~3600), diffs for changes. Full snapshots only when needed.

Enable/disable

Mint

Install / Use

README