nitpicking

module

v0.3.0 Latest Latest Go to latest Published: Apr 27, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/pinkhop/nitpicking

Links

Open Source Insights

README ¶

Nitpicking

Nitpicking (np) is a local-only, single-machine CLI issue tracker for AI-agent and solo-developer workflows. It keeps issue tracking inside your workspace, stores data in a local SQLite database under .np/, gates mutations behind explicit claims, and avoids hosted services, background daemons, global git hooks, or repo-coupled automation.

Inspired by Steve Yegge's beads project, Nitpicking keeps the useful local workflow ideas while deliberately staying narrower and less invasive.

What It Is

A workspace-local issue tracker rooted at .np/
A CLI designed for both humans and agents using the same command surface
A claim-based coordination model instead of hidden locks or background processes
A lightweight planning and execution tool for local work

What It Is Not

Not a hosted issue tracker
Not a multi-machine sync system
Not a background service or daemon
Not a git hook manager
Not an agent orchestrator

Why It Is Different

Local-only by design. Issues live in a SQLite database inside .np/; there is no remote service, account, or network dependency.
Claims gate mutations. Updating, deferring, deleting, or closing an issue requires its claim ID. Claims primarily exist for multi-agent coordination, but they also give solo humans a visible "work is in progress" marker.
Readiness is built in. np claim ready, np ready, and np blocked help the tool choose work based on blockers and state instead of forcing everything through manual assignment.
Humans and agents share the same CLI. Interactive forms exist for people, while JSON commands and agent utilities support non-interactive workflows without a separate API.
It stays out of the way. No git hooks, no daemons, no server process, and no hidden state outside your workspace.

The Basic Loop

For day-to-day use, start with one habit:

np ready
np claim ready --author "$USER"
# do the work
np close --claim <CLAIM-ID> --reason "Done."

That is enough to use np without adopting labels, epics, or agent setup on day one. When the backlog needs light structure, keep the workflow flat and add labels such as kind:bug, area:auth, or task-group:auth-overhaul.

Installation

Download a release binary

Prebuilt static binaries are available on the Releases page. Set VERSION to the release version (without the leading v) you want to install; for example:

VERSION=0.2.0

macOS (Apple Silicon):

curl -fsSL "https://github.com/pinkhop/nitpicking/releases/download/v${VERSION}/nitpicking_${VERSION}_darwin_arm64.tar.gz" -o np.tar.gz
tar xzf np.tar.gz np
xattr -d com.apple.quarantine np   # IMPORTANT: remove quarantine attribute
mv np ~/.local/bin/                # or:  sudo mv np /usr/local/bin/
rm np.tar.gz

macOS (Intel):

curl -fsSL "https://github.com/pinkhop/nitpicking/releases/download/v${VERSION}/nitpicking_${VERSION}_darwin_amd64.tar.gz" -o np.tar.gz
tar xzf np.tar.gz np
xattr -d com.apple.quarantine np   # IMPORTANT: remove quarantine attribute
mv np ~/.local/bin/                # or:  sudo mv np /usr/local/bin/
rm np.tar.gz

Linux (x86_64):

curl -fsSL "https://github.com/pinkhop/nitpicking/releases/download/v${VERSION}/nitpicking_${VERSION}_linux_amd64.tar.gz" -o np.tar.gz
tar xzf np.tar.gz np
sudo mv np /usr/local/bin/
rm np.tar.gz

Linux (ARM64):

curl -fsSL "https://github.com/pinkhop/nitpicking/releases/download/v${VERSION}/nitpicking_${VERSION}_linux_arm64.tar.gz" -o np.tar.gz
tar xzf np.tar.gz np
sudo mv np /usr/local/bin/
rm np.tar.gz

Build from source

Prerequisites:

Go 1.26+
make

git clone https://github.com/pinkhop/nitpicking.git
cd nitpicking
make build

This produces a static binary at dist/np. You can invoke it directly with ./dist/np or copy/symlink it somewhere on your PATH.

Users: start with the Quickstart guide.
Contributors: start with Developer Onboarding for the shortest path from clone to first safe change.

Quickstart

This is the shortest useful end-to-end flow:

Initialize a workspace-local issue database.
Create an issue.
Inspect the backlog.
Claim work before mutating it.
Close the claimed issue with a reason.

# In your workspace directory
np init FOO

# Create an issue in the interactive form
np create

# See what is available
np ready

# Claim the next ready issue and note the returned claim ID
np claim ready --author "$USER"

# Close the claimed issue
np close \
  --claim <CLAIM-ID> \
  --reason "Done."

np close --reason records the reason as a comment and closes the issue in one atomic step.

np discovers the workspace by walking up from the current directory, so after np init you can run commands from the repo root or any subdirectory below it. If you need to bypass parent traversal, use the global --workspace flag or NP_WORKSPACE.

Human And Agent Paths

Humans and agents use the same CLI, but they typically use it differently:

Action	Human	Agent
Create an issue	`np create` in a terminal launches the interactive form	`np json create --author "$AUTHOR"` reads JSON from stdin
Inspect work	`np list`, `np show <ISSUE-ID>`, `np ready`	Add `--json` for machine-readable output
Claim work	`np claim ready --author "$USER"`	`np claim ready --author "$AUTHOR" --json`
Update a claimed issue	`np form update --claim <CLAIM-ID>`	`np json update --claim <CLAIM-ID>`
Comment on an issue	`np form comment --author "$USER" <ISSUE-ID>`	`np json comment --author "$AUTHOR" <ISSUE-ID>`

For humans, the TTY-driven commands are the default path:

np create
np list
np claim ready --author "$USER"
np show <ISSUE-ID>

For agents and scripts, prefer machine-readable output and the stdin-driven JSON commands:

np claim ready --author "$AUTHOR" --json
np show <ISSUE-ID> --json
np list --ready --json
np json create --author "$AUTHOR"
np json update --claim <CLAIM-ID>
np json comment --author "$AUTHOR" <ISSUE-ID>

To bootstrap an agent session, use:

np agent name --seed=$PPID
np agent prime

The --seed=$PPID flag ties the generated name to the agent's process ID, so the same process always produces the same author identity. Omit --seed only when you want a fresh random name each time.

How It Works

Each workspace gets its own .np/ directory with the embedded SQLite database and related metadata.
Start with flat task issues. Use labels for grouping, routing, and metadata such as kind:bug, area:auth, or task-group:auth-overhaul.
Epics are optional. Add them only when flat tasks plus labels are not enough and you need explicit hierarchy, progress tracking, or grouped closure.
Claiming is the concurrency gate. Comments and most non-hierarchical relationships can be added without a claim, but field updates and state transitions require one.
Readiness is computed. In the default flat workflow, a task is ready when it is open and unblocked.
np create auto-detects its mode: piped stdin reads JSON, while a TTY launches the interactive form UI.
Backup and restore are built in for moving or recovering a local workspace.

Main Command Groups

The root CLI is organized into these workflow-first categories:

Setup: init
Core Workflow: create, claim, close, show, list, ready, blocked
Issues: issue, epic, rel, label, comment, form
Agent Toolkit: json, agent
Admin: admin
Info: version

Run np --help for the current command tree.

Within admin, the most important maintenance commands are admin doctor, admin backup, and admin restore.

Documentation Map

Start with the Quickstart Guide.

From there, the main user entry points are:

Quickstart — The smallest useful task-first workflow
Agent Setup — How to configure coding agents to use np
Daily Work — The flat task workflow humans and agents repeat once the tracker becomes part of daily work
Core Concepts — Claims, readiness, issue roles, relationships, and priorities
Labels Guide — Label naming, flat grouping, filtering, routing, and day-to-day usage
Epics — Optional hierarchy when flat tasks and labels are not enough
Multi-Agent Operations — Coordinating multiple agents in one workspace
Command Reference — Full CLI reference
Troubleshooting — Diagnostics and recovery steps
FAQ — Common questions and operational tradeoffs

See the broader docs index for the full documentation map.

Contributor Links

Contributor and implementation material is available, but it is secondary to the user onboarding path above:

Developer Onboarding — First-day reading order and the shortest contribution path
Developer Setup — Build tooling, Make targets, and local setup
Architecture — The authoritative layering and dependency rules
CLI Implementation Guide — Command, wiring, and testing conventions

License

Nitpicking is licensed under the terms of the MIT license. See LICENSE for the full text.

AI Disclosure

This project's source code and documentation were created in part or in whole using generative AI under the direction of the author.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
np command Package main is the entry point for the np binary.	Package main is the entry point for the np binary.
internal
adapters/driven/backup/jsonl Package jsonl implements the backup driven-port interfaces using the JSON Lines format.	Package jsonl implements the backup driven-port interfaces using the JSON Lines format.
adapters/driven/storage/memory Package memory provides a first-class in-memory implementation of the persistence port interfaces.	Package memory provides a first-class in-memory implementation of the persistence port interfaces.
adapters/driven/storage/sqlite Package sqlite implements the persistence port interfaces using an embedded SQLite database via zombiezen.com/go/sqlite (pure Go, no CGO).	Package sqlite implements the persistence port interfaces using an embedded SQLite database via zombiezen.com/go/sqlite (pure Go, no CGO).
cmd/admincmd Package admincmd provides the "admin" parent command, which groups maintenance and administrative operations under a single namespace.	Package admincmd provides the "admin" parent command, which groups maintenance and administrative operations under a single namespace.
cmd/admincmd/backupcmd Package backupcmd provides the "admin backup" command, which creates a JSONL backup of the entire issue database.	Package backupcmd provides the "admin backup" command, which creates a JSONL backup of the entire issue database.
cmd/admincmd/completion Package completion provides the "completion" command, which outputs shell completion scripts for bash, zsh, and fish.	Package completion provides the "completion" command, which outputs shell completion scripts for bash, zsh, and fish.
cmd/admincmd/doctor
cmd/admincmd/gc
cmd/admincmd/restorecmd Package restorecmd provides the "admin restore" command, which restores the issue database from a JSONL backup file.	Package restorecmd provides the "admin restore" command, which restores the issue database from a JSONL backup file.
cmd/admincmd/tally Package tally provides the "tally" admin subcommand — a dashboard showing summary statistics about the issue database.	Package tally provides the "tally" admin subcommand — a dashboard showing summary statistics about the issue database.
cmd/admincmd/upgrade Package upgrade implements the "admin upgrade" command, which migrates the nitpicking database from its current schema version to v3.	Package upgrade implements the "admin upgrade" command, which migrates the nitpicking database from its current schema version to v3.
cmd/admincmd/where Package where provides the "where" command, which prints the absolute path of the discovered .np/ directory.	Package where provides the "where" command, which prints the absolute path of the discovered .np/ directory.
cmd/agent
cmd/blocked Package blocked provides the "blocked" shortcut command — lists issues that have unresolved blocked_by relationships.	Package blocked provides the "blocked" shortcut command — lists issues that have unresolved blocked_by relationships.
cmd/claim
cmd/closecmd Package closecmd provides the "close" workflow shortcut — a combined close-with- reason command that adds a comment and then closes the issue in one step.	Package closecmd provides the "close" workflow shortcut — a combined close-with- reason command that adds a comment and then closes the issue in one step.
cmd/comment
cmd/create Package create provides the root-level "create" command, which auto-detects its input mode using IOStreams TTY detection: when stdin is a pipe, it delegates to the JSON create path; when stdin is a TTY, it launches the interactive form.	Package create provides the root-level "create" command, which auto-detects its input mode using IOStreams TTY detection: when stdin is a pipe, it delegates to the JSON create path; when stdin is a TTY, it launches the interactive form.
cmd/epiccmd Package epiccmd provides the "epic" parent command with subcommands for epic-specific operations such as completion status tracking.	Package epiccmd provides the "epic" parent command with subcommands for epic-specific operations such as completion status tracking.
cmd/formcmd Package formcmd provides the "form" parent command, which groups interactive, TUI-based subcommands for issue creation and modification.	Package formcmd provides the "form" parent command, which groups interactive, TUI-based subcommands for issue creation and modification.
cmd/importcmd Package importcmd provides the "import" parent command, which groups subcommands for importing issues from structured file formats (currently JSONL).	Package importcmd provides the "import" parent command, which groups subcommands for importing issues from structured file formats (currently JSONL).
cmd/init
cmd/issuecmd Package issuecmd provides the "issue" parent command, which groups issue management operations under a single namespace.	Package issuecmd provides the "issue" parent command, which groups issue management operations under a single namespace.
cmd/issuecmd/delete
cmd/issuecmd/historyview
cmd/issuecmd/search
cmd/jsoncmd Package jsoncmd provides the "json" parent command, which groups agent-oriented subcommands that accept structured JSON input on stdin and produce JSON output unconditionally.	Package jsoncmd provides the "json" parent command, which groups agent-oriented subcommands that accept structured JSON input on stdin and produce JSON output unconditionally.
cmd/labelcmd Package labelcmd provides the "label" parent command, which groups label management operations under a single namespace.	Package labelcmd provides the "label" parent command, which groups label management operations under a single namespace.
cmd/list
cmd/ready Package ready provides the "ready" shortcut command — a quick way to list issues that are available for work.	Package ready provides the "ready" shortcut command — a quick way to list issues that are available for work.
cmd/relcmd Package relcmd provides the "rel" parent command, which groups relationship management operations under a single namespace.	Package relcmd provides the "rel" parent command, which groups relationship management operations under a single namespace.
cmd/relcmd/graphcmd Package graphcmd implements the "graph" CLI command, which renders the issue hierarchy and relationships as a Graphviz DOT file.	Package graphcmd implements the "graph" CLI command, which renders the issue hierarchy and relationships as a Graphviz DOT file.
cmd/root Package root constructs the root command that assembles all subcommands and defines cross-cutting behavior in the Before hook (signal handling and schema version gating).	Package root constructs the root command that assembles all subcommands and defines cross-cutting behavior in the Before hook (signal handling and schema version gating).
cmd/show
cmd/version Package version implements the "version" command, which prints the application's build version and — when --verbose is set — VCS metadata (version control system, commit revision, and commit timestamp).	Package version implements the "version" command, which prints the application's build version and — when --verbose is set — VCS metadata (version control system, commit revision, and commit timestamp).
cmdutil Package cmdutil provides shared infrastructure for command implementations: the Factory for dependency injection, typed errors for centralized classification, build metadata extraction, and flag helpers.	Package cmdutil provides shared infrastructure for command implementations: the Factory for dependency injection, typed errors for centralized classification, build metadata extraction, and flag helpers.
core Package core implements the driving port interface defined in internal/ports/driving.	Package core implements the driving port interface defined in internal/ports/driving.
domain Package domain defines the core business types, error categories, and identity types for the nitpicking issue tracker.	Package domain defines the core business types, error categories, and identity types for the nitpicking issue tracker.
domain/history Package history defines the HistoryEntry entity — an immutable, append-only record of every mutation to an issue's state.	Package history defines the HistoryEntry entity — an immutable, append-only record of every mutation to an issue's state.
iostreams Package iostreams provides an abstraction over standard I/O with TTY awareness, color control, and test substitution.	Package iostreams provides an abstraction over standard I/O with TTY awareness, color control, and test substitution.
ports/driven Package driven defines the driven port interfaces — the contracts that the core requires from its persistence and backup layers.	Package driven defines the driven port interfaces — the contracts that the core requires from its persistence and backup layers.
ports/driving Package driving defines the driving port — the use-case boundary that CLI and other adapters invoke.	Package driving defines the driving port — the use-case boundary that CLI and other adapters invoke.
wiring Package wiring is the application's configurator layer — the outermost ring of the hexagonal architecture.	Package wiring is the application's configurator layer — the outermost ring of the hexagonal architecture.