The Ledger + BULWORK MODE

The problem: project decay and session drift

Creative projects rarely die with a dramatic failure; they quietly fade away when un-touched ideas sit in forgotten repositories. Even when a creator decides to re-engage, secondary friction takes over: opening the workspace requires manual setup, and focus during a work session easily drifts into passive web browsing.

To solve this dual challenge, I designed an integrated two-pillar ADHD Project-OS: The Ledger (a multi-platform hub that makes project neglect visible through touch tracking) and BULWORK MODE (a Manifest V3 Chrome extension and background daemon that enforces active focus using local context and AI adjudication).

The Ledger: Visible project health & touch tracking

The Ledger serves as the central state hub. Built as a cross-platform application spanning macOS desktop (Tauri 2), web (Vite SPA), and mobile (Capacitor 6), it provides frictionless project tracking with zero fluff.

A project’s health is evaluated continuously using a smooth Red-Yellow-Green (RdYlGn) status dot gradient calculated from days since its lastTouched timestamp (green for 0–4 days, yellow for 5–9 days, and red for 10+ days). Each project maintains a rolling 8-entry touch history with categorized reasons (such as progress, research, blocked, or automated GitHub push events), alongside explicit nextAction fields with review flagging.

To support desktop environments without relying on broken webview popup dialogs, the app incorporates a native Rust TCP loopback server (127.0.0.1:53682) to capture Google and GitHub OAuth redirects safely. It also features an embedded AI side panel (powered by OpenRouter) equipped with 11 security-confined tools for searching local files, querying project state, and launching focus sessions.

BULWORK MODE: Contextual focus enforcement

While The Ledger manages project state, BULWORK MODE acts as the focus enforcement pillar. Architected as a decoupled background daemon (running at http://localhost:7373), it enforces focus without polluting client UI bundles or requiring intrusive macOS Accessibility API permissions.

At the core of BULWORK is an AI Adjudicator Engine powered by Claude Haiku 4.5. When a user navigates the web or switches applications during a focus session, target destinations are evaluated against the session’s focus task using a two-phase guard: an instant URL pattern check at document_start, followed by a deeper re-check of the page’s <title> and meta tags once loaded.

The policy operates on a charitable stance: adjacent professional tools and documentation (e.g. StackOverflow or technical RFCs) are allowed, while clear distractors are blocked. On low-confidence evaluations, the system safely defaults to a conservative-allow to preserve user trust. Frontmost application telemetry is captured every 5 seconds via native macOS lsappinfo polling, and workspace app layouts are automated via Bunches (x-bunch://open).

The Chrome Extension: Frontline browser enforcement

The primary surface used during day-to-day work is the BULWORK Chrome Extension (Manifest V3). Serving as the frontline enforcement layer, the extension contains zero API keys or LLM prompt logic; instead, it delegates all intelligence to the local daemon (localhost:7373).

The extension organizes web traffic into a three-tiered domain architecture:

Tier 1 (Hard Block): High-distraction domains (e.g. Reddit, TikTok, Netflix) are intercepted at the network level using Chrome’s declarativeNetRequest API. Navigations are instantly redirected to a local block page without incurring network latency or API costs.

Tier 2 (AI Adjudicated): Ambiguous sites (news, YouTube, Twitter) trigger a background IPC request to the local daemon. Content scripts monitor SPA navigation events—evaluating individual YouTube videos rather than blocking the domain wholesale. If a site is deemed off-task, a soft overlay (“Back to BULWORK MODE”) appears with a “Just 1 more minute” grace button that pauses the work clock with a subtle vignette cue.

Tier 3 (Whitelist): Developer documentation, GitHub, StackOverflow, and localhost endpoints pass through completely untouched.

Beyond domain blocking, the extension includes a Pomodoro timer engine with real-time toolbar badge indicators (red for work blocks, green for breaks), day-plan block queues with automated stop triggers (advancing when a git push or Ledger touch is detected), and a Floating AI Chat Pill. When visiting AI tools like Claude.ai, ChatGPT, or Gemini, a bottom-right pill allows inserting a soft-nudge focus header directly into the prompt composer with a single click (“↳ prepend focus”).

System synthesis: The focused work loop

The Ledger, BULWORK daemon, and Chrome Extension operate independently but lock together during active work sessions to create a complete feedback loop:

1. Selection & Launch: The user picks a project in The Ledger (or selects a project directly from the Chrome Extension popup). Starting a session sends the project’s defined nextAction as the focus task to BULWORK via POST /session/start, automatically deploying Chrome’s declarativeNetRequest rules and opening the project’s .bunch workspace layout.

2. Active Enforcement & State Mirroring: While a session is active, The Ledger polls BULWORK’s status endpoint (GET /session every 5 seconds) and renders a glowing yellow ambient border (#FFD60A) across the application shell. The Chrome Extension badge displays a live minute-by-minute countdown, while BULWORK queries a local vector Memory Hub (mem query) to semantically ground what counts as on-topic research for that specific project’s technical docs.

3. Session Completion & Admin Sync: When the session ends or a Pomodoro break begins, Tier 1 block rules dynamically lift. Completed focus metrics, grace pauses, and adjudication logs are written directly to Cloud Firestore (focus_sessions) using the Firebase Admin SDK stamped with BULWORK_USER_ID, automatically populating timeline views inside The Ledger UI via real-time onSnapshot listeners.

Design constraints & trade-offs

Architecting this constellation required balancing system capability against security and user experience:

Zero-secret extension architecture: Moving all AI keys and rule compilation into the local daemon ensures the browser extension context holds no sensitive credentials and cannot be exploited by malicious scripts.

Decoupled daemon vs. monolithic app: Keeping BULWORK as a separate background process ensures enforcement survives when the UI window is closed, while keeping OS-level process management code out of cross-platform React web builds.

Friction vs. fortress philosophy: The threat model targets outlasting short-term impulse browsing rather than stopping a malicious user. Permissive fallback rules, grace pauses, and soft-nudge headers prioritize habit building over punitive locking.

Visual walkthrough

This page will later carry an interactive system topology diagram, a two-phase adjudication decision flow, and a video walkthrough of the Chrome Extension and focused work session loop.