| name | knotch-query |
| description | Read the current state of a unit — current phase, status, shipped milestones, model timeline — or find units that match a predicate. Works for active, archived, abandoned, and handed-off units alike (projections are pure historical reads). Use when the agent needs a fact before planning its next action. |
| paths | ["crates/**",".knotch/**"] |
| allowed-tools | Bash(knotch show *) Bash(knotch current) Bash(knotch unit list) Bash(knotch log *) |
knotch-query
Projections are pure. Calling them is free (O(n) on log length, no
I/O beyond the load). Prefer a projection over re-deriving state
from raw events.
Built-in projections (knotch_kernel::project)
| Function | Returns | Use for |
|---|
current_phase(log) | Option<W::Phase> | "What should I work on next?" |
current_status(log) | Option<StatusId> | "Has this been archived / abandoned?" |
shipped_milestones(log) | Vec<W::Milestone> | "Which user stories are done?" |
effective_events(log) | Vec<Event<W>> | Supersede-aware view of the log |
model_timeline(log) | Vec<ModelTimelineEntry> | "Which model was active for each event window?" |
tool_call_timeline(log, tool, call_id) | Vec<ToolCallFailureEntry> | Per-(tool, call_id) retry history |
subagents(log) | Vec<SubagentEntry> | Completed subagent roster |
All are pure fns. They take &Log<W>; obtain the log with
repo.load(&unit).await?.
Cross-unit queries (knotch-query)
use knotch_query::QueryBuilder;
use knotch_kernel::StatusId;
let units = QueryBuilder::<W>::new()
.where_status(StatusId::new("in_review"))
.since(jiff::Timestamp::from_second(1_700_000_000)?)
.limit(20)
.execute(&repo)
.await?;
Filters AND-combine. execute walks repo.list_units() and loads
each. For large workspaces, prefer where_status or where_phase
early — they short-circuit per-unit.
Workflow-specific projections
Summary helpers are workflow-specific — the canonical Knotch
workflow ships only the core projections above. Adopter workflows
that want LLM-facing summaries add them on their own
WorkflowKind impl; see examples/workflow-vibe-case-study/src/lib.rs
for a reference implementation (summary_for_llm).
Custom projections
Implement Projection<W> (trait in knotch_kernel::project):
pub struct UnshippedGates;
impl<W: WorkflowKind> Projection<W> for UnshippedGates {
type View = Vec<W::Gate>;
fn project(log: &Log<W>) -> Self::View { ... }
}
Projections must be pure: no I/O, no Timestamp::now(), no hidden
state. Verified by policy, not by compiler.
Do not
- Walk
log.events() by hand if a projection already exists.
- Cache the
Arc<Log<W>> returned by load — projections are
cheap; a stale log hides fresh events.
- Call
project_* inside repo.append's precondition — the
precondition already sees the right snapshot via AppendContext.
