kanthord overview
Read this page first. It says what kanthord is, names the six concepts every other page builds on, and maps the rest of the documentation.
What kanthord is
kanthord is one long-running daemon on Node.js 24+. It stores a plan as a graph
of tasks, hands those tasks to external coding-agent workers over HTTP, and
records every state change in one SQLite file. An operator drives it with the
kanthord CLI; workers drive it through the same HTTP API.
The daemon owns state, never execution. A worker claims a task inside a fenced lease, runs its agent loop in a git clone outside the daemon process, and reports back. The daemon serializes conflicting work, accounts attempts, and keeps an append-only event log.
Six concepts that carry everything
Plan graph
An imported document becomes nodes in three kinds — initiative, objective, task — connected by dependency edges. Waived edges are skipped.
Node lifecycle
pending → ready → running → done | partial | blocked.
Only legal transitions exist, and each one appends an event.
Lease and fence
A time-limited claim on a node. The fence counter never resets, so a stale holder cannot write after a takeover.
Run and attempt
An objective run schedules task runs; a try is one attempt with a pinned model registration. The attempt limit blocks a failing task.
Workspace clone
One git clone per objective, shared by its tasks. Profile and conventions freeze at clone time.
Home
The directory holding everything that outlives the process:
kanthord.db, worktrees, journal, keys.
The layered shape
Ten layers, one dependency direction: every arrow points down. Click any layer or component to open its detail page.
not-implemented
⌂ persisted resource
kanthord … · claims, heartbeats, reports over HTTPHow to read these pages
| If you want to know… | Read |
|---|---|
| how the layers relate and what constrains them | each layer page under Architecture, top to bottom |
| how a piece cooperates at runtime | Follow a request — one claim traced end to end |
| how tasks are selected and run in parallel | Scheduling & execution |
| what a word means | Glossary |
| where a rule comes from | the source diagram and the proposal documents in the engine submodule |
Invariants worth memorizing
- One transaction per write command: a state transition and its event append never sit in two transactions.
- Determinism: same input, same output, same order, same bytes. Ties break by ULID, compared bytewise.
- The CLI speaks HTTP only. It imports no command and no query.
- Startup order: load config → acquire home lock → probe git tools → open and migrate SQLite → bootstrap actor → construct services → recover home → bind handlers → listen.