storyhook

story

story is a CLI-first story and issue tracker built for local repositories, scripting, and AI coding agents.

It keeps active work in project-local JSON event logs, archives closed work into SQLite, and favors short commands that are easy to type, pipe, and automate.

Why story

• Local-first: project data lives in /.storyhook so it can travel with the repository.
• Agent-friendly: concise commands, stable --json output, and explicit exit codes.
• Audit-friendly: open stories are append-only JSONL event streams.
• Safe under concurrent use: all writes use a project-scoped file lock; archived stories live in SQLite with WAL enabled.

Current capabilities

• Create and show stories
• Add comments with story <id> "comment"
• Assign members
• Define project states mapped to OPEN or CLOSED
• Set and clear awaiting blockers
• Set priority levels (critical, high, medium, low, none)
• Add and filter by labels/tags
• Search stories by title, comments, and labels
• Project summary with state/priority breakdown
• Find next ready-to-work stories (story next)
• Add and remove story relationships
• Derive read-only ancestor-of and descendent-of family relationships on show output
• Archive stories immediately when they move into a CLOSED state
• Reopen archived stories
• Import/export stories (JSON bulk operations)
• Generate AI context documents (story context)
• Session handoff documents (story handoff)
• Dependency graph analysis (critical path, blocked chains, parallel groups)
• Configurable project ID prefix
• Run integrity checks with story doctor and best-effort repair with story doctor --fix

Install

Quick install (Linux / macOS)

curl -fsSL https://raw.githubusercontent.com/mikeydotio/storyhook/main/install.sh | sh

This detects your platform and architecture, downloads the latest release binary, and installs it to ~/.local/bin/story.

To install to a different location:

STORYHOOK_INSTALL_DIR=/usr/local/bin curl -fsSL https://raw.githubusercontent.com/mikeydotio/storyhook/main/install.sh | sh

To install a specific version:

STORYHOOK_VERSION=v0.2.0 curl -fsSL https://raw.githubusercontent.com/mikeydotio/storyhook/main/install.sh | sh

Install with Cargo

cargo install storyhook

Or from a local checkout:

cargo install --path .

Prebuilt binaries

Download a release archive from the releases page and extract the story binary to a directory in your PATH.

Available targets:

• story-x86_64-unknown-linux-gnu.tar.gz — Linux x86_64
• story-aarch64-unknown-linux-gnu.tar.gz — Linux ARM64
• story-x86_64-apple-darwin.tar.gz — macOS Intel
• story-aarch64-apple-darwin.tar.gz — macOS Apple Silicon

Claude Code plugin

storyhook ships a Claude Code plugin (plugin/claude-code/) that adds workflow skills (/storyhook:storyhook-context, /storyhook:storyhook-work, …) and session hooks. There are two ways to install it; both register it properly so Claude Code loads the /storyhook:* commands.

CLI-first — if you already installed the story CLI (above):

story plugin install claude-code

This registers mikeydotio/storyhook as a marketplace and installs the plugin through the claude CLI. It requires the claude CLI on your PATH.

Marketplace-first — if you prefer to install the plugin before the CLI:

/plugin marketplace add mikeydotio/storyhook
/plugin install storyhook@storyhook

The marketplace route installs the plugin but not the story CLI. Once the plugin loads, run /storyhook:storyhook-install and the plugin will install and verify the CLI for you.

After installing the plugin (either route), start a new Claude Code session so the /storyhook:* commands load.

Uninstall

If installed via the install script or manual download:

rm ~/.local/bin/story

If installed via Cargo:

cargo uninstall storyhook

To remove the Claude Code plugin:

story plugin uninstall claude-code

This unregisters the plugin via the claude CLI, cleans up project-local config, and removes any legacy plugin directory left by older versions.

Quick start

Initialize a project inside the repository you want to track:

story init

Create a story:

story new "Build CLI parser"

Add collaborators:

story member add "Mikey Ward <[email protected]>"
story member add -g mikeyward

Work the story:

story SH-1 assign mikey
story SH-1 "Parser skeleton is in place"
story SH-1 awaits "waiting on command grammar decision"
story SH-1 awaits --clear
story SH-1 is in-progress "Hooked up argument routing"
story SH-1 is done "Merged and verified"

Relate stories:

story SH-1 parent-of SH-2
story SH-2 precedes SH-3
story SH-4 conflicts-with SH-5
story SH-2 parent-of SH-3 --remove

Prioritize, label, and triage: