Installation

issy can be installed both globally and in your repository. We recommend both for the best experience — global for convenience, local for version pinning.

Global installation

A global install brings flexibility and speed to your local workflows.

# npm
npm install issy --global

# pnpm
pnpm add issy --global

# yarn
yarn global add issy

# bun
bun install issy --global

Once installed globally, run commands from your terminal:

issy                          # Start the web UI
issy list                     # List open issues (roadmap order)
issy next                     # Show next issue to work on
issy create --title "Bug"     # Create an issue
issy learn                    # Print AI-agent instructions

Repository installation

When collaborating with other developers, pin the version by adding issy as a devDependency:

# npm
npm install issy --save-dev

# pnpm
pnpm add issy --save-dev --ignore-workspace-root-check

# yarn
yarn add issy --dev --ignore-workspace-root-check

# bun
bun add issy --dev

You can continue using your global installation to run commands. Global issy automatically defers to the local version if one exists.

Initialize a project

Create the .issy/issues/ directory in your project:

issy init

Add --seed to create a welcome issue that demonstrates the format:

issy init --seed

Teach AI agents

issy learn prints the canonical AI-agent reference for your installed issy version:

issy learn

Add this line to AGENTS.md so agents know when to load it:

When the task involves creating, reading, updating, listing, searching, prioritizing, closing, reopening, or choosing project issues, tasks, bugs, improvements, or roadmap work, run `issy learn` first and follow its guidance.

For assistants that support skills, you can also install the lightweight bootstrap skill:

issy skill install

Or, without running the issy wrapper:

npx skills add miketromba/issy

The CLI still needs to be available when the assistant runs issy learn.

Verify installation

Check that everything is working:

issy --version

Migrating from v0.4

If upgrading from v0.4.x (which used .issues/ instead of .issy/):

issy migrate

This moves your issues to .issy/issues/ and assigns roadmap order to all open issues.