istar

istar is an issue tracker written in Recoil: SQLite storage, a transport-agnostic API core, an HTTP JSON transport, and a static browser client on top. It is built for two consumers equally — an agent that reads and writes issue state as part of its normal work, and a human who triages and plans in a browser — which is why the API is the product and the browser client is just one consumer of it (docs/design/2026-09-03-istar-issue-tracker-design.md).

Status

State	Items
Built	SQLite storage and migrations, transport-agnostic API core, HTTP transport with sixteen operations, bearer-token write authentication, Forgejo, GitHub and GitLab webhooks (commit and pull/merge request links, close on merge), embedded HTML client, developer test suites
Designed, not built	NDJSON socket transport, importer for the Recoil repository's docs/plans/backlog/*.md, two-way forge sync
Out of scope for v1	Project CRUD, labels, deletes, markdown export, git synchronisation

Confirmed directly for this pass, not just carried over from the design: no istar/transport/socket.rcl exists in this tree. docs/seed-issues.rcl is gone — its findings were entered into istar by hand once; every substrate finding is now a tracked istar #N issue, cited that way throughout docs/.

Quickstart

istar is built against one pinned commit of the Recoil compiler, and ./build.sh refuses to build against any other. Check that first — it is cheap, since it compiles nothing:

./build.sh --check-pin

See docs/development.md for what the pin buys and how to get a Recoil checkout at it. Once the pin check passes:

./build.sh
./istar-server

and open http://localhost:8080. The platform-specific binary embeds the checked-in web/ client and statically linked SQLite; it can run from a directory without web/. It still needs the platform C runtime and filesystem access to its database. Builds have been exercised on x86_64-apple-darwin; the other three native target recipes await verification on their hosts. See docs/running.md for target scope and deployment details. Before exposing the server to a network, read its network exposure guidance: it listens on every interface, and bearer tokens sent over plain HTTP can be observed.

On first start, if ./istar.db does not exist, istar initializes it with a 36-issue English showcase about building case software for the authority in Kafka's The Trial. It appears in the recoil project. Existing databases, including empty ones, are left unchanged. A custom ISTAR_DB path gets schema initialization without showcase content.

To restore the showcase in the selected database, stop the server and run ISTAR_DB=/path/to/demo.db ./istar-server --reset-showcase. This replaces all issue, comment, and link content while preserving projects and authentication tokens. With ISTAR_DB unset, it resets ./istar.db.

A Docker image is documented in docs/docker.md.

The client

web/index.html and web/app.js are a vendored, build-free Alpine.js page: it lists and filters issues, and opens a detail view with children, links and comments (web/index.html). Every view — the filtered list, a single issue, or a search — is addressable through the URL hash, so a direct link and browser back/forward both work (web/app.js). The issue body renders as markdown through markdown-it, with a raw-source toggle next to the rendered view; comment bodies render as markdown too, but that toggle is issue-only — no comment has a raw-source affordance (web/app.js).

Why Recoil

istar is Recoil's own issue tracker: it replaces the markdown plan files under the Recoil repository's docs/plans/backlog/, which cannot be queried, filtered, cross-referenced, or updated concurrently. It is also Recoil's first real package-mode workspace of this size, and several of the substrate limitations recorded during its build came directly out of exercising package mode for the first time. See the v1 design spec for the full reasoning and the limitation ledger it produced, rather than a restatement of it here.

Repository map

Path	What's there
istar/	the Recoil source: model, storage, repo layer, API core, HTTP transport
web/	authoritative browser client source; build.sh embeds it without a web bundler
tests/	the Recoil test suite, run through tests/run.r3
test/	the JavaScript test suites — unit and browser
docs/	this documentation, plus the design specs, plans and workflow record
.superpowers/	per-task execution records for each implementation plan
build.sh, test.sh	the root scripts — build the binary, run the suites

Documentation

• docs/api.md — the JSON API reference
• docs/running.md — building, running and configuring the server
• docs/development.md — the pin, the suites, and the module map
• docs/workflow.md — how the specs, plans and execution records fit together
• docs/design/ — dated design specs, starting with the v1 design
• docs/plans/ — plans with unfinished implementation or verification work
• docs/plan-history/ — completed implementation plans retained as history
• CONTRIBUTING.md — the contributor checklist

Licence

Apache-2.0 — see LICENSE. web/vendor/ carries three third-party libraries under their own licences; see web/vendor/VENDOR.md.