clissue

Local-first issue tracking as files — create, lint, search, and evolve issues in your repo (with optional LLM-assisted drafting).

If you like issues you can review in PRs, branch/merge, and grep, clissue is for you.

What is clissue?

clissue is a CLI that stores issues as a small folder of plain files in your repository:

• issues/<IDENTIFIER>/issue.md — the issue body + YAML frontmatter
• issues/<IDENTIFIER>/relations.yml — structured links (blocking / blocked-by / related / duplicate-of)
• issues/<IDENTIFIER>/attachments.yml — URLs and file attachments

It’s “local-first”: your tracker lives with your code, works offline, and integrates naturally with Git workflows.

Why would I use this?

• PR-native: review issue changes like code changes.
• Audit trail: history is your Git log.
• Fast search: plain-text fallback search + optional projection database.
• Enforced consistency: clissue lint keeps frontmatter and metadata tidy.
• Optional LLM help: clissue propose can draft issues into a reviewable file.

Features

• Initialize a repo config + registries (clissue init)
• Create issues manually (clissue new)
• Draft issues via LLM into .clissue/drafts/... (clissue propose)
• Lint issues, optionally auto-fix (clissue lint --fix)
• List/show/search issues (clissue list, clissue show, clissue search)
• Attach URLs/files (clissue attach)
• Add/remove relations (clissue relation)
• Update workflow state, labels, priority (clissue state, clissue labels, clissue priority)
• Build/search a projection DB (clissue rebuild)
• Print local usage guidance for agents (clissue skill)

Installation

Option A: install as a dev dependency (recommended)

pnpm add --save-dev clissue

Then run via:

pnpm exec clissue --help

Option B: global install

pnpm add --global clissue

Quickstart

1) Initialize clissue

clissue init --team-name "Alpha Elite" --team-key ALE

This creates:

• clissue.config.json
• issues/registry/* (teams, workflow states, labels, priorities, …)
• your issues/ directory (if missing)

2) Create a new issue (manual)

clissue new --team-key ALE --title "Fix scroll regression in knob"

3) Lint issues

clissue lint

Auto-fix what can be fixed:

clissue lint --fix
clissue lint

CLI reference

Run:

clissue --help

init

clissue init --team-name "Alpha Elite" --team-key ALE

Upgrade/migrate built-in config defaults in an existing repo:

clissue init --upgrade

new (manual issue creation)

clissue new --team-key ALE --title "Add empty state to search results"

Use new when your input is already clear and you want full control.

propose (LLM-assisted draft)

clissue propose --input "Users report the knob scrolls twice on macOS. Investigate and fix." --accept

• Writes a draft to: .clissue/drafts/<IDENTIFIER>/issue.md
• With --accept, writes the finalized issue to: issues/<IDENTIFIER>/issue.md

Tip: keep issues/** in version control, but don’t commit .clissue/drafts/**.

list

clissue list

Include triage/closed:

clissue list --show-triage
clissue list --show-closed

show

clissue show --identifier ALE-12

search

clissue search --query "scroll regression"

rebuild (projection DB)

clissue rebuild

attach

Attach a URL:

clissue attach --identifier ALE-12 --url "https://example.com/repro-video"

Attach a file:

clissue attach --identifier ALE-12 --file "./artifacts/screenshot.png"

relation

Add a relation:

clissue relation --identifier ALE-12 --related-identifier ALE-3 --type blocked-by

Remove a relation:

clissue relation --identifier ALE-12 --related-identifier ALE-3 --type blocked-by --remove

Relation types:

• blocked-by: can’t proceed until dependency completes
• blocking: this issue blocks another
• related: contextual link without dependency
• duplicate-of: duplicate tracking

state

List states:

clissue state --list

Set state:

clissue state --identifier ALE-12 --state "In Progress"

labels

List labels:

clissue labels --list

Set labels (comma-separated):

clissue labels --identifier ALE-12 --labels "bug,ui"

priority

List priorities:

clissue priority --list

Set priority (0–4):

clissue priority --identifier ALE-12 --priority 2

File layout

Typical structure:

issues/
  registry/
    teams.yml
    workflow-states.yml
    issue-labels.yml
    priorities.yml
  ALE-12/
    issue.md
    relations.yml
    attachments.yml
.clissue/
  drafts/
    ...

LLM proposals (how it works)

clissue propose runs a configurable “provider command template” that must output valid JSON matching clissue’s schema. This keeps proposals deterministic and easy to validate/lint.

If you don’t want LLM help, ignore propose entirely and stick to new.

Contributing

PRs welcome.

Suggested workflow:

pnpm install
pnpm run typecheck
pnpm run test
pnpm run lint

License

MIT