nitpicking

module

v0.1.1 Latest Latest Go to latest Published: Apr 3, 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, which gives humans and agents an explicit coordination primitive.
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.

Installation

Download a release binary

Prebuilt static binaries are available on the Releases page.

macOS (Apple Silicon):

curl -fsSL https://github.com/pinkhop/nitpicking/releases/latest/download/nitpicking_0.1.1_darwin_arm64.tar.gz -o np.tar.gz
tar xzf np.tar.gz np
xattr -d com.apple.quarantine np
sudo mv np /usr/local/bin/
rm np.tar.gz

macOS (Intel):

curl -fsSL https://github.com/pinkhop/nitpicking/releases/latest/download/nitpicking_0.1.1_darwin_amd64.tar.gz -o np.tar.gz
tar xzf np.tar.gz np
xattr -d com.apple.quarantine np
sudo mv np /usr/local/bin/
rm np.tar.gz

Remove the quarantine attribute that macOS GateKeeper applies to downloaded files by running xattr -d com.apple.quarantine /usr/local/bin/np after moving the binary into place. Without this step, macOS will block np with an "unidentified developer" warning. The commands above already include this step before the mv; if you move the binary to a different location, run xattr -d com.apple.quarantine /path/to/np against the final path.

Linux (x86_64):

curl -fsSL https://github.com/pinkhop/nitpicking/releases/latest/download/nitpicking_0.1.1_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/latest/download/nitpicking_0.1.1_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 Getting Started guide.
Contributors: see Developer Setup for build, lint, test, and release-related commands.

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 PKHP

# Pipe JSON into create, or run `np create` with a TTY for the interactive form
np create --author "$USER" <<'JSONEND'
{
  "role": "task",
  "title": "My first task"
}
JSONEND

# See what is available
np list

# 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 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.

For Agents

Agents should prefer machine-readable output:

np claim ready --author "$AUTHOR" --json
np show <ISSUE-ID> --json
np list --ready --json

For stdin-driven workflows, np also ships explicit JSON subcommands:

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
np agent prime

Claude Code example:

mkdir -p .claude/rules/
np agent prime > .claude/rules/issue-tracking.md

How It Works

Each workspace gets its own .np/ directory with the embedded SQLite database and related metadata.
Issues are either task or epic. Use labels for further categorization such as bug, feature, or area.
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. A task is ready only when it is open and unblocked; an empty epic can be ready when it needs decomposition.
np create auto-detects its mode: piped stdin reads JSON, while a TTY launches the interactive form UI.
Backup and restore are built in, and np import jsonl supports bulk creation from structured JSONL input.

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, import
Info: version

Within admin, the most important maintenance commands are admin where, admin doctor, admin backup, admin restore, admin gc, admin completion, admin tally, and admin reset.

Run np --help for the current command tree.

Documentation Map

Start with the Getting Started Guide.

From there, the main user entry points are:

User Documentation Index — Overview of all user-focused guides
Key Concepts — Claims, readiness, issue roles, relationships, and priorities
Daily Use Guide — The commands you will repeat most often once the tracker becomes part of your workflow
Workflow Guides — Task-only, epic-driven, label-driven, and multi-agent workflows
Agent Integration Guide — How to configure coding agents to use np
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 Setup — Build tooling, Make targets, and local setup
Architecture — The authoritative layering and dependency rules
Design Guide — Code patterns and implementation conventions
Launch Process — How main() dispatches to commands

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/agent
cmd/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/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/comment
cmd/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/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/delete
cmd/doctor
cmd/done Package done provides the "close" workflow shortcut — a combined close-with- reason command that adds a comment and then closes the issue in one step.	Package done provides the "close" workflow shortcut — a combined close-with- reason command that adds a comment and then closes the issue in one step.
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/gc
cmd/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/historyview
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/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/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/root Package root constructs the root command that assembles all subcommands and defines cross-cutting behavior in the Before hook (signal handling).	Package root constructs the root command that assembles all subcommands and defines cross-cutting behavior in the Before hook (signal handling).
cmd/search
cmd/show
cmd/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/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).
cmd/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.
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.