vissue

An issue tracker that is a directory of Org files. One file per project holds the issues as headings; :PARENT: groups them under a plan, :BLOCKED_BY: orders them, ready is the frontier any agent can pick up, claim is the lock so two agents do not take the same one, recall is what an issue stands on, :DEEDS: names what its work produced, and consensus weighs the ballots several agents cast on it. There is no second store: the files diff, merge and grep with the repository they live in, Emacs reads them with nothing installed, and a CLI and a Model Context Protocol server share one library. Agents write through those two surfaces, never by editing an issues.org.

Install

$ cargo install vissue-cli
$ cargo install vissue-mcp   # the MCP server, same version
$ cargo install vissue-hud   # summonable overlay, optional

Tagged releases carry prebuilt archives and a shell installer on the releases page. vissue completions zsh and vissue man come out of the binary.

A minute of it

$ vissue create --project parser "Reject a manifest with no header"
parser-k29f  TODO  [#C]  Reject a manifest with no header

$ vissue create --project parser --priority A "Publish the release notes"
parser-3xq7  TODO  [#A]  Publish the release notes

$ vissue update parser-3xq7 --block parser-k29f
parser-3xq7: state TODO -> BLOCKED (auto on block), blocked_by += parser-k29f

$ vissue ready
parser-k29f            TODO      [#C]  Reject a manifest with no header

The files land under <root>/Software/<project>/issues.org; the prefix is configurable and <root> comes from --root, VISSUE_ROOT, or a user-level route table that sends named projects to other checkouts.

Documentation

Full documentation is at vissue.rgoswami.me.

Page	What it answers
Getting started	An empty directory to a backlog two workers share
How-to	One task at a time: split a plan, share, watch, fold, project, validate
Reference	Commands, properties, config, export schema, exit statuses
Control	Unix socket protocol, `serve`, the terminal board and the HUD
Explanation	Why the file is the database, what `recall` and `consensus` are, and the sources
Emacs	The agenda, tag search, and `id:` links, with nothing installed
Org syntax	Org 9.8 mapped onto an `issues.org`
Org ecosystem	ELPA / MELPA names the tracker owns, reads, or preserves

The sources are Org under docs/orgmode/; bash docs/build.sh renders the site.

Contributing

Conventional commits, cargo fmt, and cargo clippy -- -D warnings. Run prek install for the hooks. The minimum supported Rust version is 1.89. See CONTRIBUTING.md for the interop checks a change to the command surface or the on-disk shape has to pass.

Citation

See CITATION.cff.

License

MIT. See LICENSE.