Zinn is published on npm as two packages: the CLI, @zinn-dev/cli, and the core library at @zinn-dev/core.
Requirements
The CLI and core run on Node.js 24.15.0 or newer. Core also runs on Bun, and the CLI can run on Bun through bunx.
On a Node.js 24 release older than 24.15.0, npm installs Zinn with an engine warning, and every command that opens the database prints an ExperimentalWarning about SQLite to stderr. Output on stdout, including --json, is unaffected.
Install the CLI
npm i -g @zinn-dev/cli
Check that the zinn command is available:
zinn --version
The quick start creates a first project and task.
Run the CLI on Bun
The zinn command runs on Node.js. To run the CLI on Bun, even where Node.js is installed, use bunx --bun and put the Zinn command after the package name:
bunx --bun @zinn-dev/cli --help
Bun’s documentation explains how --bun overrides a Node.js shebang.
Use with coding agents
Choose either setup for your coding agent:
Skill
Install the Zinn workflow skill. It covers picking up work, keeping task context, recording follow-ups, and handing off for review.
zinn skill install
The command installs the skill bundled with your Zinn CLI, so the skill matches the commands your CLI has. It installs globally for use across repositories and applies where the user or repository uses Zinn. The installer is the open-source skills CLI, which the command runs through npx.
Repository rule
Add this line to your AGENTS.md or CLAUDE.md, then let the agent discover commands through zinn --help:
This repository uses Zinn for work tracking. Before substantial work, on resume, and before finishing, check the relevant task and keep it current. Use zinn --help to discover commands.
Add core to a project
npm i @zinn-dev/core
See the Core library guide for a runnable example with database configuration.
Upgrade
Save a backup of the database first:
zinn backup
Then install the latest CLI. It brings the core release it was built with:
npm i -g @zinn-dev/cli@latest
If you installed the agent skill, update it separately:
npx skills update -g
After switching Node versions or package managers, run zinn skill install again instead. The CLI then lives in a new folder, and the command installs the skill from there.
In a project that uses core, upgrade it there:
npm i @zinn-dev/core@latest
Name @latest: npm saves core with a ^0.x range, which stays within one minor release.
A newer release upgrades an older database the first time it opens it, saving a backup first.
See Data and backups for backup, restore, and database-upgrade behavior.
Uninstall
Uninstalling the CLI also removes the core it brought:
npm uninstall -g @zinn-dev/cli
In a project that uses core, remove it there:
npm uninstall @zinn-dev/core
Uninstalling leaves your data in place. The Zinn directory holds the database, backups and settings. It is ~/.zinn unless ZINN_DIR or a settings file chooses another. Deleting it removes every project and backup.