CLIIT

Markdown-native issue tracking for coding agents.

Install · Quickstart · Usage · AI coding agents · Configuration

Keep issues, work plans, claims, and completion evidence in Git. No server or account required. CLIIT (Command-Line Issue Tracker) stores each issue as a Markdown file in .issues/, so your backlog reviews in pull requests and travels with the clone.

• Plain files you own. Read and edit issues in any text editor, even without CLIIT.
• Focused daily workflow. Search, prioritize, assign, and track dependencies from your terminal.
• A clear next step. issue next selects actionable work by status, priority, and age.
• Continuity for coding agents. JSON output, issue claims, and saved work plans help sessions pick up where they left off.

Install

Requires Python 3.10+. Works on Linux, macOS, and Windows. Install from PyPI with uv:

uv tool install cliit
issue --version

Both issue and cliit run the same CLI. To update, run uv tool upgrade cliit. If your shell cannot find issue, run uv tool update-shell and reopen your terminal.

Alternatively, run python -m pip install cliit inside an activated virtual environment. Git is optional for installation; use it to share issues and view their history.

Quickstart

Run these commands in your project's root directory:

issue init
issue create "Fix login redirect" "The session cookie disappears after sign-in." -p high -l bug
issue list
issue next
issue start ISS-001

The example assumes a new tracker; use the ID returned by create in an existing one. start marks the issue in progress and creates .issues/work/ISS-001.md. Edit that plan as you work, keeping its checkpoints and next step current.

After implementing and checking the fix, record the result:

issue close ISS-001 --completed -m "Fixed session cookie handling." --verified "Signed in and confirmed the session survives the redirect."

Commit .issues/ alongside your code to keep the issue, work plan, and resolution in the same history.

Usage

Run issue --help for all commands, or issue <command> --help for its options.

Find and organize work

Statuses are open, in-progress, and closed. Priorities are high, medium (the default), and low. Repeat -l to add or filter by multiple labels; filters combine, and search requires every word to match, ignoring case.

list places the most urgent rows nearest your terminal prompt. next prefers in-progress work, then higher priority, then older issues. It skips closed and blocked issues, and skips other people's assignments when your identity is known. It only reads unless you add --claim.

Close with a reason

Every close requires one reason and a nonblank, single-line message (-m).

Evidence flags are repeatable: --commit <sha>, --test "<command>", --pr <url>, and --verified "<manual check>". A close supported only by --verified is accepted with a warning.

Use issue close to close an issue; issue set ... closed is refused. Reopening clears the current resolution, while committed history remains available through issue log.

AI coding agents

Set ISSUE_USER to a distinct name for each worker, or use your configured git config user.name. Then use the same workflow from a script or agent:

issue init --agents
issue brief --json
issue next --claim --json
issue start ISS-001

Use the ID returned by next for start. Claims coordinate workers in the same working copy; --claim tries another candidate if one is taken. Claiming requires an identity and does not change the issue's status.

In a fresh project, init --agents creates shared instructions in AGENTS.md and a CLAUDE.md import. Existing instructions are preserved.

Work plans live at .issues/work/ISS-001.md. Update checkpoints, decisions, discoveries, Current, and Next as work progresses. Running start again resumes an existing plan without overwriting it. It refuses blocked, closed, or someone else's issues unless you explicitly use --anyway for blockers or --take for ownership and reopening.

Use issue next --compact or issue start ISS-001 --compact for a shorter plan summary. Read the full plan when recovering context; next --compact cannot be combined with --json. issue check --plans reports plan progress.

Event logs record observations separately from the editable plan:

issue event ISS-001 "Worker started" --type lifecycle
issue event ISS-001 --json

Events are appended to .issues/work/ISS-001.events.jsonl. Use --stdin to record piped output instead of a text argument.

Configuration

Commands find .issues/ by walking up from the current directory. init always creates a tracker in the current directory.

For example, set an agent identity with export ISSUE_USER=agent-1 on macOS/Linux or $env:ISSUE_USER = "agent-1" in PowerShell.

File format

An issue is a Markdown document with flat key: value frontmatter:

---
id: ISS-001
status: open
created_at: 2026-09-11T10:00:00+06:00
priority: high
labels: auth, bug
---
# Fix login redirect

The session cookie disappears after sign-in.

Optional metadata includes updated_at, assignee, and blocked_by. Labels and blocker IDs are comma-separated; resolution evidence is a JSON array. Values occupy one printable line. Write files as UTF-8 with LF line endings; CRLF is accepted on read. Unknown frontmatter keys survive CLI edits.

You can edit files directly. Run issue check afterwards to catch malformed metadata, missing references, dependency cycles, and damaged work artifacts.

Stability

CLIIT is currently 0.1.0. These interfaces are maintained compatibility contracts, including before 1.0:

• Issue files: existing field names and meanings stay stable; absent optional fields stay absent, and unknown frontmatter keys are preserved.
• JSON output: existing keys and types stay stable; additional keys may appear. list, search, check, and event reads return arrays; view, next, and brief return objects on success. Optional issue fields may be absent. Diagnostics go to stderr.
• Exit codes: an empty filter result is 0; a lookup with no result or a refused write is 1. A partially successful batch write also returns 1.
• Configuration: the three environment variables above keep their meanings.

Human-readable output, stderr wording, work-plan and event-log file formats, and internal Python modules are not stable APIs. Use the CLI and --json for integrations.

Scope

CLIIT is built for a backlog shared through one repository. It works offline and outside Git, but committed history requires Git. There is no hosted UI, notification service, or synchronization with GitHub Issues.

For bugs and questions, use GitHub Issues. For security reports, see SECURITY.md. Project setup and the pull request workflow are in CONTRIBUTING.md.