mint: Minimal Issue & Needs Tracker

crates.io PyPI npm CI codecov

This is a global, single-machine, SQLite-backed issue system CLI for AI agents.

plan-demo

Usage

In AI Agent

/mint   # In a new session.
# Or
/mint <Something>

Most of the time, it works by itself.

In Shell (Optional)

mint tui

Most of the time, it changes by itself.

Features

  • Single global database at $XDG_DATA_HOME/mint/mint.db (MINT_DB_PATH overrides) — no per-project install, cross-project shared via refs
  • 6-state state machine (open/planned/dev/test/done/dropped) with mandatory test_cmd on close
  • Containers: milestones (versioned releases) + plans (agent execution plans) with 5-state derived status
  • Built-in dedup (normalized-title fuzzy match) + full-text search (FTS5)
  • mint export: full JSON/TSV dump (issues with labels/links + plans + milestones + labels) for backup/migration
  • Agent adapters: Claude Code plugin, Codex hooks, OpenCode plugin — failure signals + issue context injected automatically
  • TUI (mint tui): live dashboard, ratatui-based, non-TTY falls back to text snapshot
  • Lightweight single binary (~1.7 MB), no daemon, millisecond startup

Install the CLI

The mint binary ships to three registries (package name mint-faa, command mint). Pick any:

cargo install mint-faa        # crates.io — compiles from source (any platform)
pip install mint-faa          # PyPI — prebuilt wheel (Linux/macOS/Windows)
npm install -g mint-faa       # npm — downloads the platform binary from GitHub Releases
  • crates.io: source build; needs a Rust toolchain.
  • PyPI: prebuilt maturin wheels — install anywhere Python runs, no compiler needed.
  • npm: a cargo-dist installer that fetches the correct prebuilt binary for your platform (Linux/macOS/Windows) from GitHub Releases. Linux binaries are musl-static (single file, no glibc dependency).

Pre-release versions (0.5.0-alpha.1 style) are only published to npm / GitHub Releases; crates.io and PyPI get stable releases only.

Or build from source: cargo install --path .

Install the Plugin

Install the Claude Code plugin

# From GitHub (one-liner):
claude plugin marketplace add https://github.com/yanqd0/mint.git
# or SSH: claude plugin marketplace add git@github.com:yanqd0/mint.git

claude plugin install mint-faa@mint          # English skill (default)
# Or: claude plugin install mint-faa-cn@mint # Chinese skill

# Or from a local checkout:
claude plugin marketplace add ./claude-plugin
claude plugin install mint-faa@mint

# restart the session for hooks to take effect

# Upgrade (two levels: marketplace source + plugin version):
claude plugin marketplace update mint
claude plugin update mint-faa@mint        # or mint-faa-cn@mint
# restart the session (hooks snapshot on startup)

# Uninstall:
claude plugin uninstall mint-faa@mint
claude plugin marketplace remove mint     # optional

Install the Codex adapter

# One-liner (global): installs hooks into ~/.codex + skill into ~/.agents/skills
./codex-adapter/install.sh

# Or project-scoped:
./codex-adapter/install.sh --project

# Uninstall:
./codex-adapter/install.sh --uninstall

# restart Codex for hooks to take effect; non-managed hooks need /hooks trust

The adapter injects failure signals (mint: tool X failed — <cmd>) and issue context (mint list) into Codex sessions, and ships AGENTS.md + a .agents/skills/mint symlink to the shared skill. Full flow lives in .agents/skills/mint/SKILL.md.

Install the OpenCode plugin

# One-liner (global): plugin into ~/.config/opencode/plugins + skill into ~/.config/opencode/skills
./opencode-adapter/install.sh

# Or project-scoped (plugin symlink into .opencode/plugins; skill already at .agents/skills/mint):
./opencode-adapter/install.sh --project

# Uninstall:
./opencode-adapter/install.sh --uninstall

# restart OpenCode for the plugin to load

The plugin injects failure signals (mint: tool X failed — <cmd>), issue context (mint list), and commit reminders into OpenCode sessions, and marks the host (mint-adapter: opencode) so the shared skill routes to its OpenCode rules. Full flow lives in .agents/skills/mint/SKILL.md.

Data lives in a single global SQLite database at $XDG_DATA_HOME/mint/mint.db (MINT_DB_PATH overrides).

Project links

Data verified by PyPI on Aug 16, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for yanqd0 from gravatar.com yanqd0

GitHub Statistics

Data verified by PyPI on Aug 16, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT

Requires

Python >=3.8

Tags

issue-tracker cli sqlite ai-agents

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mint_faa-0.5.0.tar.gz (154.8 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

mint_faa-0.5.0-py3-none-win_amd64.whl (1.3 MB view details)

Uploaded Python 3Windows x86-64

mint_faa-0.5.0-py3-none-manylinux_2_5_x86_64.manylinux1_x86_64.whl (1.4 MB view details)

Uploaded Python 3manylinux: glibc 2.5+ x86-64

mint_faa-0.5.0-py3-none-macosx_10_12_x86_64.whl (1.3 MB view details)

Uploaded Python 3macOS 10.12+ x86-64

File details

Details for the file mint_faa-0.5.0.tar.gz.

File metadata

  • Download URL: mint_faa-0.5.0.tar.gz
  • Upload date:
  • Size: 154.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for mint_faa-0.5.0.tar.gz
Algorithm Hash digest
SHA256 f1bd788723e4a75adfbd4c5ceff191ffa3be196b313c2177342190e8e1b160f0
MD5 b74c139f07a0ed3f172c2aa1cca2c44b
BLAKE2b-256 0d5577a8ff3de901ae8a1958d51ac44e41e0bf83f58bcc63af53596e942596a9

See more details on using hashes here.

Provenance

The following attestation bundles were made for mint_faa-0.5.0.tar.gz:

Publisher: publish-pypi.yml on yanqd0/mint

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file mint_faa-0.5.0-py3-none-win_amd64.whl.

File metadata

  • Download URL: mint_faa-0.5.0-py3-none-win_amd64.whl
  • Upload date:
  • Size: 1.3 MB
  • Tags: Python 3, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for mint_faa-0.5.0-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 d4e2588bae9676980710b06ed4e8329108de2b7e9cc19ed9263a4b6b9ccaf6f8
MD5 6d36b716b7668aa77033f88ee61c22aa
BLAKE2b-256 ddcbe7a139f319530a792a2444b81e93ac8387c24b2faddda950cd4f9df57f96

See more details on using hashes here.

Provenance

The following attestation bundles were made for mint_faa-0.5.0-py3-none-win_amd64.whl:

Publisher: publish-pypi.yml on yanqd0/mint

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file mint_faa-0.5.0-py3-none-manylinux_2_5_x86_64.manylinux1_x86_64.whl.

File metadata

File hashes

Hashes for mint_faa-0.5.0-py3-none-manylinux_2_5_x86_64.manylinux1_x86_64.whl
Algorithm Hash digest
SHA256 496cc36c654a5b22e9a5f0f770e1edc0bb8b9078d357acb06af266a262dd60ba
MD5 e5b2e0ebe35010d7432df158126bf8ca
BLAKE2b-256 5585b30ccd4d2354fc1e9603b39099bfe410de247500c3da51106136460ccd74

See more details on using hashes here.

Provenance

The following attestation bundles were made for mint_faa-0.5.0-py3-none-manylinux_2_5_x86_64.manylinux1_x86_64.whl:

Publisher: publish-pypi.yml on yanqd0/mint

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file mint_faa-0.5.0-py3-none-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for mint_faa-0.5.0-py3-none-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 45b9e260a8fa44a66c0ea179028279f2583e252c11384113bff2251f245e7f65
MD5 0480ce86830bba9554275e6085f46af3
BLAKE2b-256 97e79a5b4b80a2722124df79adb0ab5326a3c3c4301480e894dec85f7d3e2af2

See more details on using hashes here.

Provenance

The following attestation bundles were made for mint_faa-0.5.0-py3-none-macosx_10_12_x86_64.whl:

Publisher: publish-pypi.yml on yanqd0/mint

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page