What ships, and what is queued
Two packages are on PyPI, real, and installable today — the library and the command, with 698 tests between them. Four more repositories are built and sit further along on dev than on main, and two service packages were published early as placeholders. This page says which is which, from live PyPI queries and unzipped wheels rather than from any README.
Why a page like this is worth writing at all. Nothing in the ecosystem currently tells you what is installable — the versions in the READMEs are behind the code, and the release state of eight repositories is not visible from any one of them. A visitor deciding whether to use Issues-FS should be able to answer “what can I pip install today” in one screen, and now can.
The two you can install
issues-fs 0.7.0 — the core library
pip install issues-fs| Wheel | 103 files |
| Source | 98 .py files, 5,401 LOC |
| Tests | 604 test functions across 45 files, 8,213 test LOC — 1.5 lines of test per line of source |
| Requires | Python ≥ 3.12, osbot-utils, memory_fs, and issues-fs-cli |
| Contains | An importable Python API. No CLI and no HTTP in this package |
The public surface, if you are importing rather than shelling out: Graph__Repository and Graph__Repository__Factory for storage across four backends; Node__Service for nodes and traversal (traverse_graph, find_incoming_links); Link__Service for edges; Type__Service for the type registry; Comments__Service for comments; five status services producing a full health payload; and the .issues parser. The data model these operate on.
One oddity worth knowing before you pin versions: issues-fs lists issues-fs-cli in its own pyproject.toml, so the library depends on its own CLI. It resolves fine; it is just circular, and it is open question Q7.
issues-fs-cli 0.3.0 — the end-user surface
pip install issues-fs-cli # provides the `issues-fs` console script| Wheel | 23 files |
| Source | 17 .py files, 1,080 LOC |
| Tests | 94 test functions across 7 files |
| Built on | Typer · no_args_is_help=True · help string “Git-native graph-based issue tracking” |
| Contains | 14 commands, three output formats, and --for-agent on every one |
Repository discovery is git-style: CLI__Context.discover_issues_root() walks up from the working directory looking for a .issues/, so the command works from anywhere inside the tree. This is the most credible thing in the ecosystem — small, tested, and every claim on the command page checked against its source.
The four that are built and not yet published
All four exist, all four are further along on dev than on main, and CI publishes to PyPI only from main. So “not on PyPI” here means “the merge has not happened”, not “the work does not exist” — the mechanism, in one table.
issues-fs-service-ui — v0.2.1 in repo
142 files, 27 commits. The largest UI artefact in the ecosystem and the only part with a running local mode (scripts/run-locally.sh). It carries its own live graph — 49 nodes, 22 link entries, 9 node types, three of which are not in the shipped defaults — and an automation-runner app of 803 LOC of scripted scenarios. It loads d3, mermaid, vis-network, cytoscape, cytoscape-dagre and dagre from public CDNs; vendoring and attributing those is on the list. Two test files today, plus a Playwright suite that is written and commented out.
issues-fs-docs — v0.1.6 in repo
Holds all 59 documents in the corpus, including the five that became the estate's conceptual foundation. Its README already carries the install line and a PyPI badge, which will start resolving the moment dev reaches main — this repository is the furthest behind and the highest-leverage merge available, at 24 commits.
issues-fs-dev — v0.3.2 in repo
The development umbrella: 19 gitlinks, eleven of them role repositories. This is where the self-referential structure lives — each role its own repository with its own ROLE.md and its own .issues/. The eleven roles.
issues-fs-dev-utils — v0.1.1 in repo
535 LOC, 19 tests, a genuinely good docs/user-guide.md, and a 14-topic Librarian-maintained topic_map.json. Cross-repository developer tooling that works and that nobody can currently find: it appears in no ecosystem map — not in the umbrella's repository table, not in the core's, not in the architecture overview. Worth both publishing and listing.
The two service packages, published early
issues-fs-service 0.2.0 and issues-fs-service-client-python 0.2.0 were published on 5 February 2026 to reserve the names and the shape. Six commits each, all on that day. Each wheel contains eight files and no functional code yet — an __init__.py, a version module and dist-info — while the PyPI summaries describe the intended server and client.
| Package | Its PyPI summary describes | What is in the wheel today |
|---|---|---|
issues-fs-service 0.2.0 | “FastAPI server with REST endpoints” | 8 files. No FastAPI application yet, though osbot-fast-api is already declared as a dependency |
issues-fs-service-client-python 0.2.0 | “API schemas and Python client” | 8 files. No client or schemas yet |
The practical consequence, so nobody builds against a plan: no HTTP endpoint exists in any published package today. Anything you read describing an Issues-FS API surface is a design, and this site labels it as one. Filling the wheels or retiring the names are both reasonable outcomes — it is request N3, and until it is decided this page says which is true.
The honest reading
Eight repositories imply a platform; the wheels contain a library and a CLI. This site offers the second reading — and the second reading is a good one: 6,481 lines of source with 698 tests behind it, a real type system, four storage backends and three agent-operable surfaces is a substantial thing to have built.
| Layer | State |
|---|---|
| Core library and CLI | shipping installable today, 698 tests between them |
The .issues DSL | shipping inside the core package — and written up here for the first time |
| Issues-FS-lite | usable today the protocol is complete and needs no implementation — /lite/ |
| The UI | built, unpublished 142 files, runs locally, its own 49-node graph |
| The service and its client | design names reserved on PyPI; no endpoint yet |
| The lexicon | design ~7,000 words of architecture — published as argued design |
And one thing worth saying out loud, because it is an unusual and reassuring failure mode: the code is in better shape than its documentation. Every correction on the corrections page runs the same direction — there are more tests than claimed, more submodules than claimed, more roles than claimed. Nothing was promised and quietly dropped; the descriptions simply stopped being updated while the work carried on.
For an agent
Two packages are installable and real: pip install issues-fs (the Python API, 0.7.0, 604 tests) and pip install issues-fs-cli (the issues-fs command, 0.3.0, 14 commands). issues-fs-service and issues-fs-service-client-python resolve on PyPI but their wheels contain no code yet — do not build against them, and treat their summaries as intent rather than description. issues-fs-service-ui, issues-fs-docs, issues-fs-dev and issues-fs-dev-utils are built but not yet on PyPI, so a pip install line for them in a README will not resolve today. No HTTP endpoint exists in any published package. Before repeating a capability claim from an Issues-FS README, check it against /shipped/corrections.html.