Extending the command line
for every operator.
Workwarrior treats the CLI as a first-class surface — not a fallback. This section documents active work to make the command line more expressive, more observable, and more structurally sound: for the developer at a laptop, the operator on a factory floor, and the agent running on hardware that may never see a GUI.
The goal is a CLI that carries genuine operational intelligence — one that can track the shape of work over time, surface behavioral signals, and coordinate across human and automated actors — without sacrificing the speed and composability that make terminal tools worth using in the first place.
Times
Workwarrior's approach to time is structural, not cosmetic. Rather than logging durations after the fact, the system continuously records the behavioral state of work as it happens — building a replayable, geometrically interpretable record that can serve everything from personal reflection to industrial monitoring.
Stream System
#stream-systemThe Workwarrior Stream System (WWSS) is a deterministic, append-only event substrate that unifies task identity, behavioral signals, time intervals, and geometric visualization into a single replayable timeline. It is not a feature added to Workwarrior — it is the kernel from which all other representations are derived.
A single append-only stream is the source of truth. All views — tasks, intervals, signals, and geometry — are derived through deterministic replay.
Each layer in the system is named for and modeled on a real historical precedent. The technical achievement is collapsing these historical models into one unified event format.
Dial-based time recorders where a continuous trace replaced discrete punches. Time became a field, not a series of entries. Workwarrior's Dey layer carries a sampled, continuous behavioral signal: intensity, stability, fragmentation.
Instantaneous marks — punches and state changes rather than duration. Frick events are structural boundaries: START, STOP, PAUSE, RESUME, SWITCH.
Start/stop recording and accumulation of worked time into bounded intervals. Bundy intervals are not stored — they are derived from Frick boundaries during replay. The interval is always a computation, never a fact on disk.
Symbolic encoding of real-world states into compact, machine-readable records. The stream's <t> <op> <a> <b> <c> line format is directly analogous to a punched card row: fixed tokens, numeric payload.
The present state of a system is a derivation of recorded history, not a stored snapshot. The ledger is never corrected — only appended to. Workwarrior extends this from files to behavioral time-state.
The only required persistent artifact is a single append-only log file:
~/.ww/stream.log. Every event is five tokens.
Canonical line structure
Five fields per line: timestamp, opcode, and three numeric payload values. No JSON. No headers. No schema versioning. Human-readable debugging without tools; deterministic replay by any parser that reads lines in order.
All derived structures are computed during replay. Nothing below is stored authoritatively.
A sampled, three-dimensional behavioral signal: intensity (activity density), stability (execution coherence), fragmentation (context-switching entropy). The system's real-time cognitive load meter — neither a task count nor a simple timer.
fields: i · s · fThe control-flow graph of behavior. Structural boundaries in the timeline: START, STOP, PAUSE, RESUME, SWITCH. Context switching is an inferred state transition, not a command pair.
types: START · STOP · PAUSE · RESUME · SWITCHIntervals derived entirely from Frick boundaries. Never stored. The same stream can produce different interval segmentations if the Frick reducer rules change — without touching any stored data.
fields: start · end · task_id · confidenceTracks how repeated patterns affect longer-horizon state: fatigue, elasticity, crystallization per task type, fracture memory. Stored via S events as optional snapshots.
fields: fatigue · elasticity · crystallizationCooper layer
Cooper transforms the Dey time series into a geometric field: time becomes angle, intensity becomes radius, fragmentation becomes geometric deformation. A focused day produces a smooth ring. A fragmented day produces jagged, asymmetric geometry. A collapsed day inverts toward the center.
Cooper is not primarily a display technique. As a computational object it is a mapping from time-series state vectors to a continuous geometric manifold — enabling:
Normal behavior = stable ring. Anomalies appear as radial bulges, jagged edges, or radial collapse. No threshold tuning per metric.
High-radius zones = high-load periods where injecting tasks is costly. Stable arcs = optimal execution windows.
Overlapping Cooper fields reveal contention zones; divergence indicates specialization. Coordination as vector field alignment.
Cooper-derived metrics define reward signals: stability up → reward; fragmentation up → penalty; sustained intensity → nonlinear reward curve.
Every CLI command is a macro-expansion into stream events. The CLI is not an interface to the system — it is a compiler front-end for a time-structured event machine.
- ww task 2 start→ F START + B task:2
- ww task 3 start→ F SWITCH + B task:3
- ww emit D 0.5 0.7 0.2
- ww emit F START
- ww emit T "note"
- ww view dey
- ww view frick
- ww view bundy
- ww view cooper
- ww replay --full
- ww replay --at 10:30
- ww replay --task 2
- ww agent run optimizer
- ww agent handoff task:2→ F HANDOFF
- ww sync taskwarrior
- ww daemon start
- ww smm start
The system maps directly to factory and off-earth environments. What industrial systems currently lack is not data — it is a unified interpretive layer connecting machine state, human intent, and operational rhythm.
Dey → Sensor telemetry
Continuous load, vibration, and throughput signals mapped directly onto the intensity / stability / fragmentation triple.
Frick → Machine state transitions
Start / stop / fault events expressed as the same opcode set used for human task lifecycle.
Bundy → Production runs / shifts
Clean segmentation of operational cycles derived from state boundaries — not stored, always reconstructable.
Cooper → Plant-wide shape
Entire facility state as a single geometric field. Rhythm, bottlenecks, load balance, and change traceability from one operational shape.
Agents as stream citizens
No special agent API. No privileged channel. Agents read via replay, write via the same event format as humans. Handoffs are stream events.
Eliminates sessions
State is not held in memory — it is reconstructed from the stream. Enter work by selecting a time window, not opening a session.
A time-indexed instruction tape of five-token events where opcodes encode continuous signals (D), state transitions (F), semantic labels (T), identity bindings (B), and system events (S).
A pure, deterministic function over an ordered event stream that produces full system state — intervals, signals, task mappings, geometric projections, and adaptive state — from a single source of truth.
A state-space embedding of work behavior in polar coordinates where time becomes angle, intensity becomes radius, and fragmentation becomes geometric deformation — enabling anomaly detection, scheduling optimization, and multi-agent coordination through field geometry.
A deterministic, append-only event kernel that ingests human, system, and agent actions and exposes all operational state as replayable projections over a unified temporal stream — suitable for personal productivity, agentic systems, and industrial observability.
Stream in Detail
#stream-in-detailComplete technical treatment of the Workwarrior Stream System — architecture, lineage, formats, visualization, agentic and industrial applications.
Historical Lineage: Where the Layers Come From
Each layer in the system is named for and modeled on a real historical precedent. None are invented in isolation.
Alexander Dey's dial-based time recorders (late 19th century) introduced rotating surfaces where a continuous trace replaced discrete punches. Time became a field, not a series of entries. Workwarrior's Dey layer inherits this: a sampled, continuous behavioral signal carrying three values at each point in time.
Frederick W. Frick's mechanical recorders emphasized instantaneous marks — punches and state changes rather than duration. The system advances via discrete events, not continuous measurement. Frick events are the structural boundaries: START, STOP, PAUSE, RESUME, SWITCH.
Willard Le Grand Bundy's late-19th-century time clocks established start/stop recording and accumulation of worked time into bounded intervals. Bundy intervals are not stored in the stream — they are derived from Frick boundaries during replay. The interval is always a computation, never a fact on disk.
Herman Hollerith's punched-card systems (1890 US Census) introduced symbolic encoding of real-world states into compact, machine-readable records suitable for aggregation. The stream's <t> <op> <a> <b> <c> line format is directly analogous to a punched card row: fixed tokens, numeric payload, machine-processable.
From Luca Pacioli's double-entry accounting (1494 onward): the present state of a system is a derivation of recorded history, not a stored snapshot. The ledger is never corrected — only appended to. Modern version control (Git) formalized the same principle for software. Workwarrior extends this from files to behavioral time-state.
None of these components are novel individually. The technical achievement is collapsing them all into a single unified event stream where:
The Stream Format
The only required persistent artifact is a single append-only log file: ~/.ww/stream.log
| Field | Type | Meaning |
|---|---|---|
t | int | Timestamp (epoch minutes or epoch seconds) |
op | char | Opcode: D, F, T, B, S |
a | float/int | Primary payload |
b | float/int | Secondary payload |
c | float/int | Optional third payload (0 if unused) |
| Code | Name | Meaning |
|---|---|---|
D | Dey | Continuous state sample: intensity, stability, fragmentation |
F | Frick | State transition: START, STOP, PAUSE, RESUME, SWITCH |
T | Tag | Semantic annotation or label |
B | Binding | Link a Taskwarrior ID to the current stream segment |
S | System | Regeneration snapshot, system events |
The format is deliberately minimal — five tokens per line, no JSON, no headers, no schema versioning. Append-only writes with minimal I/O overhead; human-readable debugging without tools; exact analogy to punched-card encoding; deterministic replay by any parser that reads lines in order.
The Four Derived Layers
All derived structures are computed during replay. Nothing below is stored authoritatively.
The full Dey layer is computed from a sliding window: intensity via exponential moving average over activity rate; stability via variance of task-switching patterns; fragmentation via entropy of project distribution over a time window. Dey is the system's behavioral CPU meter — a real-time readout of cognitive or operational load that is neither a task count nor a simple timer.
Frick events are the control-flow graph of behavior — structural boundaries in the timeline. Context switching is an inferred state transition, not a command pair. The system detects it from task binding changes.
Bundy intervals are derived entirely from Frick boundaries — never stored. The same stream can produce different interval segmentations if the Frick reducer rules change, without touching any stored data. Gaps below a threshold are bridged into a single interval, giving more human-meaningful segmentation than raw start/stop pairs.
Tracks how repeated patterns of work affect system state over longer time horizons than a single session. Update rules: fatigue += avg(fragmentation) · elasticity -= interruption_rate · crystallization[task] += sustained_blocks. Stored via S events as optional snapshots.
Cooper: The Geometric Projection Layer
Cooper is not a stored layer. It is a post-replay computation that transforms the Dey time series into a geometric field:
| Dimension | Source | Visual encoding |
|---|---|---|
| Angle | Time of day | Position around ring |
| Radius | Dey intensity | Distance from center |
| Smoothness | Dey stability | Edge coherence |
| Deformation | Dey fragmentation | Geometric distortion |
The result is a state-space embedding in polar coordinates. The entire work day becomes a single deformable shape. A focused, productive day produces a smooth ring with consistent radius. A fragmented, interrupted day produces jagged, asymmetric geometry. A collapsed day (overload or abandonment) inverts toward the center.
Normal behavior produces stable ring structure. Anomalies appear as radial bulges (spikes), jagged edges (fragmentation), angular jitter (instability), or radial collapse (overload). Detection becomes distance from canonical manifold — no threshold tuning required.
High-radius zones indicate high-load periods where injecting tasks is costly; stable arcs indicate optimal execution windows; fragmentation zones indicate where context switching should be avoided.
Multiple agents contributing to the same stream each generate Cooper fields that can be overlaid. Overlap produces contention zones; divergence indicates specialization; alignment reveals cooperative execution windows.
Cooper-derived metrics define reward signals without explicit programming: stability up → reward; fragmentation up → penalty; sustained intensity → nonlinear reward curve favoring coherent work trajectories over raw throughput.
Cooper fields can be clustered by radial density distributions, curvature signatures, and deformation gradients — producing unsupervised discovery of operational archetypes: "types of days," "types of tasks," "types of agent behavior."
Looping arcs indicate stuck reasoning. Radial collapse indicates overload. Discontinuities indicate context loss. The failure becomes visible in shape before it appears in logs.
The Replay Engine
The replay engine is the read side of the entire system. Its contract: state = replay(stream, t_end=None)
Properties: Pure function — no side effects, no hidden clocks. Deterministic — same input → identical output, always. No hidden state — everything reconstructable from the stream.
Append-only writes are cheap. Periodic snapshots (S events) allow partial replay: snapshot + tail instead of full stream. Cooper is computed lazily on demand. All derived caches are disposable — rebuildable from the stream at any time.
- Stream must be ordered by timestamp
- Reducers must be idempotent
- No implicit state outside the stream
- Any randomness must be seeded from stream data
System Architecture (WWSS as Kernel)
WWSS is not a feature — it is the runtime substrate everything else depends on.
Taskwarrior is no longer the authoritative system — it becomes the identity layer. WWSS is the temporal layer. Identity lives in TaskWarrior; time-shaped reality lives in WWSS.
Accept events from CLI commands, Taskwarrior hooks, Timewarrior hooks, agent processes, and SMM observers. Normalize inputs, enforce schema, assign timestamps.
Atomic appends to stream.log. No mutation. No updates. No deletes. Idempotent retry handling for duplicate event delivery.
Deterministic reconstruction of Dey, Frick, Bundy, task bindings, Cooper geometry, and regeneration state. All views are derived endpoints, not stored data.
WWSS tolerates missing agent input, delayed Taskwarrior hooks, duplicate events, and partial ingestion. Replay fixes inconsistency; the stream is never corrected, only appended to; contradictions become observable signal — they increase fragmentation in the Dey layer, making them visible in Cooper geometry.
- Append-only truth — No modification of history
- Deterministic replay — Same stream → same state
- No hidden state — Everything reconstructable
- Time-first model — All meaning is time-indexed
The Stream Monitoring Manager (SMM)
The SMM is the active observation subsystem — running inside WWSS, continuously sampling external signals and emitting D events and inferred F transitions.
- TaskObservermonitors Taskwarrior state changes
- TimeObservermonitors Timewarrior tracking
- ShellObservermonitors terminal activity
- FocusObservermonitors application focus
- IdleObserverdetects idle periods
Sampling is fixed-interval (e.g. 30s) with debounce and thresholds. The SMM can only write events — it can never modify past ones.
CLI as Compiler Front-End
Every CLI command is a macro-expansion into stream events. The CLI is not an interface to the system — it is a compiler front-end for a time-structured event machine.
- ww task 2 start→ F START + B task:2 + D bump
- ww task 3 start→ F SWITCH + B task:3
- ww emit D 0.5 0.7 0.2
- ww emit F START
- ww emit T "note text"
- ww view dey
- ww view frick
- ww view bundy
- ww view cooper
- ww replay --full
- ww replay --at 10:30
- ww replay --from 08:00 --to 12:00
- ww replay --task 2
- ww agent run optimizer
- ww agent handoff task:2→ F HANDOFF + B + T
- ww sync taskwarrior
- ww sync timewarrior
- ww daemon start
- ww smm start
Data Format Specifications
All caches are disposable. The stream is canonical.
ASCII Visualization Layer
The ASCII layer is a deterministic projection of the stream onto a fixed-width character grid — not a fallback, but a first-class rendering that directly maps the same primitives driving the underlying system.
| Layer | Data type | ASCII primitive |
|---|---|---|
| Dey | Continuous signal | Height / density / block characters |
| Frick | Discrete events | Markers: │ ● S P R ↑ ↓ |
| Bundy | Intervals | Horizontal bars |
| Task | Identity | Labels / ANSI color |
| Cooper | Geometry | Radial / deformed fields |
Agentic Systems: The Operational Case
Modern agent systems fail in predictable ways: fragmented memory, no temporal structure, no grounding in operational load. WWSS solves this by giving agents a shared time spine where every action is anchored: time → state → action → outcome.
Agents are not external actors. They are deterministic participants in the same event system as humans. No special agent API. No privileged channel. Same stream.
Reduce concurrency.
Pause, request clarification.
Schedule recovery block.
Trigger overload alert.
Sessions disappear because state is not held in memory — it is reconstructed from the stream. Instead of open session → work → close session, the model is continuous stream → replay at any point → act.
Industrial Application
The system maps directly to factory and industrial operations contexts.
| WWSS Layer | Industrial Equivalent |
|---|---|
| Dey | Sensor telemetry: load, vibration, throughput |
| Frick | Machine state transitions: start / stop / fault |
| Bundy | Production runs / shifts |
| Task bindings | Work orders / maintenance tickets |
| Cooper | Plant-wide operational "shape" — energy and efficiency field |
What industrial systems currently lack is not data — SCADA, PLC logs, sensor streams, and maintenance tickets already exist. What is missing is a unified interpretive layer connecting machine state → human intent → operational rhythm. WWSS provides that layer. The Cooper field becomes a "heat map of time dynamics" — not a chart, not a dashboard, but a topological projection of the entire system.
What Makes This Architecturally Distinctive
Most operational systems are:
Reactive — alert-driven, not structurally interpretable.
Fragmented — one tool per domain, no unified layer.
Non-replayable — lost history meaning; present state is not derivable from past.
WWSS is:
Replayable — full history is always recoverable.
Unified — single stream, multiple projections.
Structurally interpretable — behavior has geometry, not just logs.
This positions the system closer to Git for operational reality — full replay of factory behavior or agent work history — and a CPU scheduler for human and machine work — intensity = load, fragmentation = context switching cost, stability = execution coherence. The real innovation is the reduction of all layers to a single time-indexed event tape with deterministic replay: a temporal abstraction layer over operational systems that is both replayable and geometrically interpretable.
Implementation Stack
Required
- Stream writer (append-only log management)
- Replay engine (pure function, deterministic)
- Frick boundary reducer
- Bundy interval builder
- Taskwarrior wrapper (hook → B/F events)
- Basic SMM (idle + command + task observers)
Optional for v1
- Cooper renderer
- Dey cache
- Regeneration model
- Timewarrior sync adapter
Stream processor
Rust or Go — performance, correctness guarantees
Event store
SQLite for local; TimescaleDB for time-series at scale
WebSocket server
Real-time stream delivery to browser UI
Frontend renderer
Canvas or WebGL for Cooper geometry; SVG for simpler views
The most consequential architecture decision: whether WWSS runs as a daemon (central kernel) or as a distributed append-only log with local replicas. The former fits personal and small-team use. The latter enables industrial-scale and multi-agent deployments where the stream itself becomes the coordination medium across machines.
Visualize
#visualizeThe ASCII visualization layer is a deterministic projection of the stream onto a fixed-width character grid — not a fallback, but a first-class rendering that maps the same primitives driving the underlying system. Geometry, interval, signal, and identity expressed as characters.
Midwests
#midwestsA collection of visualization explorations: ASCII renders of Cooper rings, Bundy timelines, Dey waveforms, Hollerith-encoded stream structures, and multi-layer composites. These images represent an evolving visual language for time-shaped work data.
In the production Jekyll site, replace the JS-populated gallery with a
{% for image in site.data.cli_gallery %} loop over
_data/cli_gallery.yml, or use
{% assign imgs = site.static_files | where_exp: "f","f.path contains '/assets/cli/midwests/'" %}
to auto-enumerate images dropped into assets/cli/midwests/.
Each entry only needs src, alt, and caption.