A node is a JSON file on disk. An edge is a typed verb stored on both endpoints. The folder hierarchy is the containment structure. Nothing runs — no server, no daemon, no database — so the tracker lives inside the repository it tracks, versions with it, branches with it, and can be read by cat, grep and find. That makes it legible to a human, diffable by git, and directly operable by an agent.
--for-agentissues-fs-cli 0.3.0Every command below was verified against the CLI source, not against a README.
pip install issues-fs-cli
issues-fs init # creates .issues/
issues-fs types init # 12 node types, 10 link types
issues-fs create task "Write the DSL grammar page" --priority high --tags site,docs
issues-fs create bug "Label regex rejects a valid multi-word type"
issues-fs link Task-1 blocks Bug-1
issues-fs list --output table
issues-fs show Task-1 --depth 1
issues-fs list --for-agent # same data, JSON, for an agentThe walkthrough, with what each command writes to disk → · all 14 commands with their real flags →
Measured against the repositories and the wheels, not quoted from a README. This is a small, dense, well-tested codebase with an unusually complete conceptual layer underneath it.
12 node types and 10 link types, and an edge type is not a string — it carries a declared inverse and domain and range constraints on which node types it may join. Underneath, five regex-validated primitives in strict mode, so an invalid type, status, verb or label raises rather than being quietly coerced.
memory, local_disk, sqlite and zip — all real, all constructed through one factory over the memory-fs abstraction. The same graph can live in a directory, a SQLite file, a zip archive or nothing at all.
14 commands, 1,080 lines, 94 tests, three output formats, and git-style repository discovery — it walks up from your working directory to find .issues/, so it works from anywhere in the tree. Nodes, edges, comments and the type registry are all reachable from it.
147 nodes in real use. The flagship carries 71 nodes and 141 link entries across 84 files, nested eight path segments deep, with all 13 schema fields present on all 71 nodes. Not a demo graph — a product's actual plan of record.
59 documents, and the five at the centre of them became the conceptual foundation of the whole *.sgit.ai estate. Written here, in February 2026, and now the basis of a sibling site and a published book.
Each role is its own repository with its own ROLE.md and its own .issues/ graph, submoduled into the development umbrella. The Librarian, Cartographer, Journalist and Historian are argued as architecturally central rather than secondary — and the argument holds up.
This is the site's most distinctive claim and the most under-sold thing in the ecosystem. No other project in the estate has three. One of them needs no install at all.
Markdown with YAML front-matter, three folders, four mv operations. No install, no Python, no CLI, no runtime — for an agent that has a filesystem and nothing else. The whole protocol fits on one screen.
.issues flat-file DSLA line-oriented text format parsed into nodes: 11 source files, ~55 tests, three live example files, and a five-stage parse → check → normalise → map → construct pipeline wired straight into the repository API.
built and tested--for-agent JSONEvery one of the 14 CLI commands takes --for-agent, which forces JSON regardless of the configured format. Not a mode, not a second binary — one flag, and an agent that knows only that one rule can drive the whole surface.
Two packages are on PyPI, real, and installable today. They are also the two that matter — the library and the command.
| Install | Version | What you get |
|---|---|---|
pip install issues-fs | 0.7.0 | The Python API. 103-file wheel · 98 source files · 5,401 LOC · 604 tests. Graph__Repository, Node__Service with graph traversal and incoming-link lookup, Link__Service, Type__Service, comments, status services, and the .issues parser |
pip install issues-fs-cli | 0.3.0 | The issues-fs command. 23-file wheel · 14 commands · 94 tests · three output formats · --for-agent on every command |
Four more repositories exist and are further along on dev than on main: the service UI (142 files, runs locally, carries its own 49-node graph), the documentation package (all 59 documents), the development umbrella (19 submodules, eleven of them roles), and dev utils (535 LOC, 19 tests, a good user guide). CI publishes to PyPI only from main, so what is on PyPI is the last state of main rather than the state of the work. The release mechanism, in one table · package by package.
The philosophy underneath Issues-FS is that a node has no inherent meaning; meaning is discovered through the edges you can trace from it. That is why the type system is a graph of typed relationships rather than a schema of fields, and why an edge type carries domain and range constraints — blocks is not a string in a list, it is a verb with a stated inverse and a stated set of endpoints it may join.
That thinking was written here. thinking-in-graphs.md is dated 5 February 2026 and was written for Issues-FS; it reached SGraph Send on 11 June, four months later, and the whole estate now runs on it.
The boundary, stated plainly. graphs.sgit.ai owns the philosophy and teaches it at length, including as a book. This site owns the implementation — and the origin. The foundational five get one screen each here, with a link there for the argument; everything unique to Issues-FS — the schemas, the CLI, lite mode, the DSL, the roles, the live graphs — is only here. The full boundary map.
Issues-FS was built fast in February 2026 and the code has been ahead of its documentation ever since. That is the good direction for a project to drift in — everything below is a chore rather than a defect, and most of them are one command. They are listed here so nobody has to rediscover them.
dev → main where it is overdueSeven of eight repositories are ahead on dev, and CI publishes only from main. The documentation repository is furthest behind, which is why its pip install line does not resolve yet. The release helper is already in every repository. The gap, per repository.
issues-fs-service and issues-fs-service-client-python were published early, as placeholders, and the code behind them has not been written yet. Their PyPI summaries describe the intended server and client. Either is a fine outcome — the page just says which is true today. Detail.
They describe an earlier version of the project: fewer tests than there are, a backend and an integration that were considered and not taken, and a lexicon package that is still a design. Every correction runs the same way — the code is better than its description. All of them, with what was measured.
Three things are built, tested and in live use with no prose anywhere: the .issues DSL, the status services, and the eleventh role. This site is the start of that — /dsl/ is the first write-up of the DSL anywhere. The grammar itself is next.
Nine repositories ship Apache 2.0 with the appendix placeholder still in it. A one-line fix per repository, and it is what makes the licence usable by anybody else. The licence position.
Seven are published unresolved — the lexicon, the canonical layout, whether the index should exist, the self-inverse verb, the service, the lite upgrade path, and one circular dependency. None blocks using the tool. Q1–Q7.
Issues-FS is a git-native tracker with three operable surfaces. If you have a filesystem and no tooling, use lite: issues/open|blocked|done/NNN-slug.md with YAML front-matter, and four mv operations — see /lite/. If you can install, pip install issues-fs-cli and pass --for-agent to any of the 14 commands to force JSON. Address nodes by label (Task-1, Bug-27), never by GUID; link writes the inverse edge for you. Read another agent's issues/; never write into it. Enumerate a graph by walking for issue.json rather than reading _index.json, which is a cache. The upstream READMEs describe an earlier version — check a capability claim here before repeating it.