CLI Enhancements

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.

cli / times

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-system

The 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.

Historical Lineage

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.

Dey Alexander Dey — late 19th c.

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.

Frick Frederick W. Frick — mechanical recorders

Instantaneous marks — punches and state changes rather than duration. Frick events are structural boundaries: START, STOP, PAUSE, RESUME, SWITCH.

Bundy Willard Le Grand Bundy — 1880s

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.

Hollerith Herman Hollerith — 1890 Census

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.

Pacioli / Git 1494 → version control

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.

Stream Format

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.

<t> <op> <a> <b> <c> # Opcodes: D Dey continuous state sample F Frick state transition T Tag semantic annotation B Binding link task ID → segment S System regen snapshot, events # Worked example: 480 D 0.6 0.7 0.2 # i=0.6 s=0.7 f=0.2 482 F 1 0 0 # START 482 B 2 0 0 # bind task:2 540 F 2 0 0 # PAUSE 545 F 4 0 0 # SWITCH
The Four Derived Layers

All derived structures are computed during replay. Nothing below is stored authoritatively.

Dey continuous

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 · f
Frick discrete

The 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 · SWITCH
Bundy derived

Intervals 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 · confidence
Regeneration adaptive

Tracks 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 · crystallization
Cooper — Geometric Projection

Cooper 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.

# Polar projection: angle ← time of day (24h → 2π) radius ← Dey intensity (distance from center) smooth ← Dey stability (edge coherence) deform ← Dey fragment (geometric distortion)

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:

Anomaly detection

Normal behavior = stable ring. Anomalies appear as radial bulges, jagged edges, or radial collapse. No threshold tuning per metric.

Agent scheduling

High-radius zones = high-load periods where injecting tasks is costly. Stable arcs = optimal execution windows.

Multi-agent coordination

Overlapping Cooper fields reveal contention zones; divergence indicates specialization. Coordination as vector field alignment.

RL reward shaping

Cooper-derived metrics define reward signals: stability up → reward; fragmentation up → penalty; sustained intensity → nonlinear reward curve.

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.

Task lifecycle
  • ww task 2 start→ F START + B task:2
  • ww task 3 start→ F SWITCH + B task:3
Stream primitives
  • ww emit D 0.5 0.7 0.2
  • ww emit F START
  • ww emit T "note"
Observation (read-only)
  • ww view dey
  • ww view frick
  • ww view bundy
  • ww view cooper
Replay
  • ww replay --full
  • ww replay --at 10:30
  • ww replay --task 2
Agent interface
  • ww agent run optimizer
  • ww agent handoff task:2→ F HANDOFF
System
  • ww sync taskwarrior
  • ww daemon start
  • ww smm start
Industrial Application

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.

One-Line Definitions
Stream format

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).

Replay engine

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.

Cooper

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.

WWSS

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-detail

Complete technical treatment of the Workwarrior Stream System — architecture, lineage, formats, visualization, agentic and industrial applications.

Part I

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.

Dey Layer — Continuous Analog Recording

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.

Frick Layer — Discrete Event Impulses

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.

Bundy Layer — Interval Accumulation

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.

Hollerith Encoding — Compact Machine-Readable Data

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.

Pacioli / Git — Append-Only Reconstruction

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.

The Synthesis

None of these components are novel individually. The technical achievement is collapsing them all into a single unified event stream where:

Bundyintervals (derived)
Frickevents (explicit)
Deycontinuous signal (sampled)
Hollerithencoding (compact schema)
Pacioli/Gitreplay (deterministic reconstruction)
Part II

The Stream Format

The only required persistent artifact is a single append-only log file: ~/.ww/stream.log

Canonical Line Structure
<t> <op> <a> <b> <c>
FieldTypeMeaning
tintTimestamp (epoch minutes or epoch seconds)
opcharOpcode: D, F, T, B, S
afloat/intPrimary payload
bfloat/intSecondary payload
cfloat/intOptional third payload (0 if unused)
Opcodes
CodeNameMeaning
DDeyContinuous state sample: intensity, stability, fragmentation
FFrickState transition: START, STOP, PAUSE, RESUME, SWITCH
TTagSemantic annotation or label
BBindingLink a Taskwarrior ID to the current stream segment
SSystemRegeneration snapshot, system events
Worked Example
480 D 0.6 0.7 0.2 # intensity=0.6, stability=0.7, fragmentation=0.2 482 F 1 0 0 # START 482 B 2 0 0 # bind task:2 540 F 2 0 0 # PAUSE 545 F 4 0 0 # SWITCH 550 D 0.4 0.5 0.3

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.

Part III

The Four Derived Layers

All derived structures are computed during replay. Nothing below is stored authoritatively.

Dey — Continuous Signal Dynamics
DeySample { t: int i: float # intensity — activity density / load s: float # stability — coherence of execution state f: float # fragmentation — context switching frequency }

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 — Discrete State Transitions
FrickEvent { t: int type: enum { START, STOP, PAUSE, RESUME, SWITCH } }

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 — Derived Intervals
Interval { start: int end: int task_id: optional str confidence: float }

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.

Regeneration — Long-Term Adaptive State
RegenerationState { fatigue: float elasticity: float crystallization: dict[str, float] fracture_memory: dict[str, float] }

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.

Part IV

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:

Cooper(t) = F(Dey(t), Bundy(t), Frick(t)) CooperField(x, y, t) = α · Dey(t) + β · IntervalDensity(Bundy, t) + γ · GraphActivity(Frick, t)
DimensionSourceVisual encoding
AngleTime of dayPosition around ring
RadiusDey intensityDistance from center
SmoothnessDey stabilityEdge coherence
DeformationDey fragmentationGeometric 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.

Why This Matters Beyond Visualization
Anomaly detection via geometry divergence

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.

Geometry-driven agent scheduling

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.

Multi-agent coordination as vector field alignment

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.

Reinforcement learning reward shaping

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.

Temporal clustering and archetype discovery

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."

Debugging agent failures geometrically

Looping arcs indicate stuck reasoning. Radial collapse indicates overload. Discontinuities indicate context loss. The failure becomes visible in shape before it appears in logs.

Part V

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.

def replay(stream, t_end=None): state = init_state() for e in stream: if t_end and e.t > t_end: break state = apply(state, e) state.cooper = project_cooper(state.dey) state.regeneration = update_regen(state) return state

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.

Determinism Requirements
  • Stream must be ordered by timestamp
  • Reducers must be idempotent
  • No implicit state outside the stream
  • Any randomness must be seeded from stream data
Part VI

System Architecture (WWSS as Kernel)

WWSS is not a feature — it is the runtime substrate everything else depends on.

Position in the Stack
WWSS (Stream Service) Task adapter (Taskwarrior hooks → B and F events) Time adapter (F transitions → Timewarrior start/stop) Agent adapters (agent inferences → T, D, F events) CLI / UI / APIs (read projections, write commands)

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.

Three Core Responsibilities
1. Ingest

Accept events from CLI commands, Taskwarrior hooks, Timewarrior hooks, agent processes, and SMM observers. Normalize inputs, enforce schema, assign timestamps.

2. Append-only storage

Atomic appends to stream.log. No mutation. No updates. No deletes. Idempotent retry handling for duplicate event delivery.

3. Replay + projection API

Deterministic reconstruction of Dey, Frick, Bundy, task bindings, Cooper geometry, and regeneration state. All views are derived endpoints, not stored data.

Failure Model

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.

System Invariants
  • 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
Part VII

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.

SMM observer plugins normalized WW events stream
Observer Plugins
  • TaskObservermonitors Taskwarrior state changes
  • TimeObservermonitors Timewarrior tracking
  • ShellObservermonitors terminal activity
  • FocusObservermonitors application focus
  • IdleObserverdetects idle periods
Normalization Rules
if idle: emit D(i=0.1, s=0.4, f=0.3) if keystroke_rate_high: emit D(i=0.8, s=0.9, f=0.05) if long_idle_gap: emit F(PAUSE)

Sampling is fixed-interval (e.g. 30s) with debounce and thresholds. The SMM can only write events — it can never modify past ones.

Part VIII

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.

Command Taxonomy
Task lifecycle
  • ww task 2 start→ F START + B task:2 + D bump
  • ww task 3 start→ F SWITCH + B task:3
Stream primitives
  • ww emit D 0.5 0.7 0.2
  • ww emit F START
  • ww emit T "note text"
Observation (read-only)
  • ww view dey
  • ww view frick
  • ww view bundy
  • ww view cooper
Replay
  • ww replay --full
  • ww replay --at 10:30
  • ww replay --from 08:00 --to 12:00
  • ww replay --task 2
Agent interface
  • ww agent run optimizer
  • ww agent handoff task:2→ F HANDOFF + B + T
System
  • ww sync taskwarrior
  • ww sync timewarrior
  • ww daemon start
  • ww smm start
The Full Cycle
CLI command event emission stream.log append replay engine derived structures (Dey / Frick / Bundy) Cooper projection CLI views + agent inputs
Part IX

Data Format Specifications

Primary Storage
stream.log ← only required artifact
Derived / Rebuildable Caches
dey.cache ← CSV: t,i,s,f frick.cache ← CSV: t,type bundy.cache ← CSV: start,end,task cooper.cache ← CSV: angle,radius,s,f regen.state ← key=value: fatigue, elasticity, crystallization

All caches are disposable. The stream is canonical.

Dey Cache
t,i,s,f 480,0.6,0.7,0.2 485,0.4,0.6,0.3
Frick Cache
t,type 482,START 540,PAUSE 545,SWITCH
Bundy Intervals
start,end,task 480,540,2 540,600,3
Cooper Points
angle,radius,s,f 0.12,0.6,0.7,0.2 0.18,0.5,0.6,0.3
Regeneration State
fatigue=0.42 elasticity=0.71 build=0.8 debug=0.3
TW Bridge (sync only)
ww_task_id,tw_id,active 2,task.abc123,true 3,task.def456,false
Part X

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.

LayerData typeASCII primitive
DeyContinuous signalHeight / density / block characters
FrickDiscrete eventsMarkers: │ ● S P R ↑ ↓
BundyIntervalsHorizontal bars
TaskIdentityLabels / ANSI color
CooperGeometryRadial / deformed fields
Rendering Examples
# Bundy timeline (simplest) build ███████████████████ email ████ debug █████████████ # Frick event markers build ███████|██|████████ ↑ ↑ pause resume # Combined Bundy + Dey build ███████████████████ ▁▂▃▄▅▆▇███▇▆▅▄▃▂▁ # Cooper ring (time-annotated) 12:00 ██████████ 09:00 ███▓▓▒▒░░ 15:00 ████████▓▓ 18:00 # Multi-layer composite TIME 08:00 09:00 10:00 TASK build███████████ email██ debug████ DEY ▁▂▃▄▅▆▇███▇▆▅▄▃▂▁▂▃▄▅▆▇ FRK S───────P──R───────────S
Part XI

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 as Stream Citizens

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.

# Reading — agent replays a window: ww replay --from 08:00 --to now # Writing — agent appends exactly as a human does: 510 D 0.7 0.9 0.1 512 F SWITCH 512 B task:2 # Handoff as stream event: F HANDOFF agent=optimizer task:2 context=stream:480-520
Self-Regulating Behavior
Fragmentation spike

Reduce concurrency.

Low stability

Pause, request clarification.

Sustained high intensity

Schedule recovery block.

Cooper radial collapse

Trigger overload alert.

Eliminating Sessions

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.

Part XII

Industrial Application

The system maps directly to factory and industrial operations contexts.

WWSS LayerIndustrial Equivalent
DeySensor telemetry: load, vibration, throughput
FrickMachine state transitions: start / stop / fault
BundyProduction runs / shifts
Task bindingsWork orders / maintenance tickets
CooperPlant-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.

Part XIII

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.

Part XIV

Implementation Stack

Minimal Viable Implementation (v1)

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
Reference Technology Stack
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

Encoding Optimizations (high-frequency / industrial)
# Delta compression: ΔD +0.01 +0.01 -0.01 # Bit-packed opcodes: F=0001 D=0010 B=0011 T=0100 # Time quantization: t = delta from previous event
The Daemon / Distributed Decision

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

#visualize

The 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

#midwests