The canonical technical reference for Workwarrior — a profile-based productivity system that wraps TaskWarrior, TimeWarrior, JRNL, Hledger, and Bugwarrior into a single CLI and browser UI.
This repository ships with Workwarrior as its technical documentation. It is also the standard against which conformance is measured and the place where changes to the system are proposed and ratified.
| Path | What It Is |
|---|---|
WORKWARRIOR-STANDARD.md |
Normative technical standard — 24 sections, fully spec'd |
whyworkwarrior.md |
The design philosophy — why this exists and what it's for |
summary.md |
Full document index with links to every guide and reference |
docs/ |
Human-readable overviews for each major subsystem |
guides/ |
Walkthrough guides for installation, profiles, sync, and more |
reference/ |
Per-file technical documentation for every lib, service, and binary |
If you just installed Workwarrior:
→ guides/starting/getting-started.md
If you want to understand the system architecture:
→ docs/architecture.md for the overview
→ WORKWARRIOR-STANDARD.md §2–§8 for the full spec
If you want to build a service or extension:
→ guides/services/service-development.md
If you want to understand the GitHub sync engine:
→ guides/github/github-sync-guide.md
→ WORKWARRIOR-STANDARD.md §14 for the normative spec
If you're looking for a specific file:
→ reference/source-map.yaml maps every doc to its source
WORKWARRIOR-STANDARD.md is the single authoritative technical description of how Workwarrior is built. It covers:
- Overview and architecture
- Complete directory structure with every file annotated
- Environment variables — what they are, who sets them, who reads them
- Profile model — structure, lifecycle, isolation guarantees
- Shell bootstrap — ww-init.sh, injected functions, rc file management
- CLI dispatcher — routing, service discovery, security constraints
- All 24 core library files — role, key functions, constraints
- Service architecture — the contract every service must follow
- Full service registry — all 25+ domains
- Browser UI — server implementation, API endpoints, security model
- Heuristic engine — 627 rules, 19 domains, compiler, self-improvement loop
- AI integration — modes, provider registry, per-profile override
- GitHub sync engine — both engines, field mapping, conflict resolution
- Weapons system — Sword, Gun, Next, Schedule
- UDA system — types, source classification, sync permissions
- Extensions, questions, export
- Fragility register — HIGH/SERIALIZED/NEVER COMMIT classifications
- Shell coding standards — enforced at Gate B
- Testing policy
- Install policy and dependency table
Workwarrior is as open source as it gets. A CLI layer and browser layer on top of tools that are already excellent:
taskwarrior → task management, UDAs, urgency engine, hooks
timewarrior → time tracking, intervals, reports
jrnl → journal entries, multi-journal, date search
hledger → double-entry accounting, balance sheets
bugwarrior → issue pull from GitHub, GitLab, Jira, and 20+ more
↓
ww
↓
profile isolation + unified CLI + browser UI
natural language + GitHub sync + weapons + extensions
The integration layer adds what didn't exist between the tools. The tools themselves are unchanged.
Formal-cause framing: Composable Local Service Architecture.
A profile is a directory. Activating it sets five environment variables. Every tool reads those variables. No tool knows Workwarrior exists.
ww profile create work
p-work # exports TASKRC, TASKDATA, TIMEWARRIORDB, etc.
task add "Ship API" due:friday # writes to profiles/work/.task/
j "Sprint 12 kicked off" # writes to profiles/work/journals/
l balance # reads profiles/work/ledgers/Switching contexts: p-personal. Switching back: p-work. No reconfiguration. No data overlap.
627 compiled heuristic rules handle routine commands without a network call:
"add a task to review the budget due friday" → task add review the budget due:friday
"start tracking time on code review" → timew start code review
"finish task 5 and stop tracking" → task 5 done
timew stop
AI is optional. It adds flexibility for phrasings the heuristics don't cover. The heuristic engine gets better over time — every AI hit can be compiled into a new rule.
ww browser # localhost:7777, no npm, Python 3 stdlib only15+ panels. Tasks, time, journals, ledgers, CMD, GitHub sync, weapons, AI controls. Server-Sent Events for real-time updates. Security boundary: ALLOWED_SUBCOMMANDS frozenset validates every command execution.
| Document | Description |
|---|---|
| Getting Started | Install, first profile, first commands |
| Installation | Platform notes, dependency management, ww deps |
| Commands | Full command surface and shell functions |
| Usage Examples | Practical workflows |
| Document | Description |
|---|---|
| Architecture | Data flow, environment variables, fragility register |
| Profiles | Isolation, multiple resources, UDAs, backup/restore |
| Services | All 25+ service domains, service contract, building new services |
| Weapons | Sword, Gun, Next, Schedule — task manipulation tools |
| Document | Description |
|---|---|
| Heuristic Engine | 627 rules, 6 phrasing variations, compiler, self-improvement |
| Browser UI | Panels, CMD routing, REST API, SSE, security |
| GitHub Sync | Bugwarrior pull + bidirectional task↔issue sync |
| AI Integration | Modes, providers, per-profile override |
| UDA System | Types, source badges, sync permissions, urgency tuning |
| Document | Description |
|---|---|
| Sync Guide | Full walkthrough |
| Configuration | Setup and config reference |
| Troubleshooting | Common issues and fixes |
| Testing | Test procedures for sync changes |
| Tool | Guide |
|---|---|
| Tasks | guides/search/task.md |
| Time | guides/search/time.md |
| Journals | guides/search/journal.md |
| Ledgers | guides/search/ledger.md |
| Lists | guides/search/list.md |
| Document | Description |
|---|---|
| Service Development | Build and register new services |
| Release Checklist | Production readiness gates |
| Issues Troubleshooting | Bugwarrior debugging |
| Section | Description |
|---|---|
reference/bin/ |
ww dispatcher and ww-init.sh bootstrap |
reference/lib/ |
All 24 core library files |
reference/services/ |
Every service directory documented |
reference/cross-cutting/ |
Sync engine, config loader, error handler, installer |
The standard explicitly classifies the highest-risk parts of the codebase. Changes to these files require an extended risk brief and adversarial verification before merge:
| Classification | Files |
|---|---|
| HIGH FRAGILITY | lib/github-api.sh, lib/sync-pull.sh, lib/sync-push.sh, lib/sync-bidirectional.sh, lib/field-mapper.sh, lib/sync-detector.sh, lib/conflict-resolver.sh, lib/annotation-sync.sh, lib/github-sync-state.sh, services/custom/github-sync.sh |
| SERIALIZED | bin/ww, lib/shell-integration.sh |
| NEVER COMMIT | profiles/*/ data files, *.sqlite3 |
The sync engine operates on data in two external systems simultaneously. Getting it wrong means irreversible data loss. The fragility classification is not bureaucracy — it's proportionate to the failure modes.
Every script in the project starts with:
#!/usr/bin/env bash
set -euo pipefailNo exceptions. Violations are Gate B failures. Full standards in WORKWARRIOR-STANDARD.md §21.
This repository is the standard. Changes to how Workwarrior works — architecture, service contracts, sync behavior, shell standards — are proposed here.
- Open an issue with the
proposallabel describing the change, its rationale, and known implementation implications - Reference the specific section of
WORKWARRIOR-STANDARD.mdaffected - If applicable, include a draft of the updated normative text
- Babb reviews and either accepts, requests revision, or declines with reasoning
Changes to HIGH FRAGILITY components require a trial implementation with documented results before ratification.
Workwarrior wraps these projects. They do the work. We wire them together.
- TaskWarrior — Göteborg Bit Factory
- TimeWarrior — Göteborg Bit Factory
- JRNL — open source
- Hledger — Simon Michael
- Bugwarrior — Göteborg Bit Factory
- taskgun — Hamza Mohd Zubair
- taskwarrior-tui — Dheepak Krishnamurthy
- taskwarrior-mcp — hnsstrk
Workwarrior · Made by Babb · workwarrior.org · ww@babb.tel