waiting-on

A local-first, tenant-separated open-loops ledger for agentic workflows: it tracks who has the ball, per domain, across email, agent sessions, and other channels.

An "open loop" is anything waiting on a decision or a reply. waiting-on reads the places those loops accumulate (an email account, your Claude Code and Codex session transcripts, a voice queue, manually entered leads), normalizes each one to a single record type, and stores it in a per-domain local SQLite database. It then answers one question from several surfaces: what is still waiting on you, and what are you waiting on someone else for.

The ledger core reads and tunes your data; it never sends anything. The one write it can make to an outside system is an explicit, opt-in draft-creation tool: waiting_on_draft_reply (and its draft --create-gmail-draft CLI equivalent) can create a Gmail draft through an external Gmail MCP server, and that is the only write path off the local store. There is no send path anywhere in the code. waiting-on holds no credentials of its own and stores snippets rather than full message bodies.

Why it is built this way

The interesting parts are the guarantees, not the CRUD.

• Fail-closed tenant walls. Each domain maps to its own SQLite database file, with a fail-closed profile allow-list enforced in application code (the Ledger facade), not an OS-level sandbox. A session runs under a profile that names the domains it may open; an unknown or unmapped profile resolves to no domains rather than to everything. The Ledger facade raises TenantWallError when a caller reaches for a domain outside its profile, and AmbiguousDomainError when a bare line_id exists in more than one allowed domain, so it refuses to guess which tenant you meant instead of silently writing the wrong one.

• Optimistic-concurrency writes with named failure modes. Lead writes are versioned compare-and-swap operations against a WAL-mode database. A losing write raises LeadWriteConflict, and a lock-contention retry-exhaustion raises LeadWriteBusy (a subclass). The failure each one guards against is spelled out in its docstring, for example a completed lead being silently reopened by a stale writer.

• Pluggable adapters over one contract. Email, agent-threads, voice, and manual-lead collectors each normalize their source into a single LineObservation. Adding a channel means writing one adapter, not touching the ledger. The deterministic file-based collectors (agent-threads, voice, manual leads) degrade to empty results when their source is absent: they yield nothing rather than raising. The email path is the exception: it shells out to an external Gmail MCP server, and a failure of that subprocess surfaces as a GmailMcpError rather than being swallowed.

• Deterministic core, zero-LLM collectors. The agent-threads and voice adapters classify state with deterministic heuristics and replay, not a model call, so their output is reproducible and testable. An injected clock makes all age math deterministic under test.

• Four surfaces over one ledger. An MCP server (for agent tool use), a CLI, an fzf-driven tuning TUI, and a static self-contained HTML board all read the same store.

The test suite covers the tenant walls, the concurrency failure modes, each adapter's normalization and fail-soft behavior, and the render surfaces. Run it with python3 -m pytest from the repo root; it is 156 tests today.

Architecture

email account         -> GmailMcpClient       -+
Claude/Codex sessions -> AgentThreadsAdapter   -+-> LineObservation -> per-domain
voice queue (JSONL)   -> VoiceAdapter          -+     (one contract)     SQLite DB
manual leads (JSON)   -> ManualLeadAdapter     -+                            |
                                                                            v
                                        MCP server | CLI | TUI | HTML board

The tenant boundary is enforced where roots and accounts resolve to a domain, so an adapter can only ever read the sources authorized for the domain it is collecting.

Install

Requires Python 3.11 or newer. No required third-party dependencies for the core.

python3 -m pip install -e .

Optional extras: .[mcp] for the MCP server, .[parquet] for Parquet export. The tuning TUI additionally needs textual, and the fzf TUI needs fzf.

You can also run straight from a checkout without installing, via the launchers in bin/.

Quickstart

The repository ships a synthetic examples/demo-leads.json so you can see the shape without any configuration. With no config file, waiting-on uses a single default domain.

# Import the demo leads into the local ledger
bin/waiting-on lead seed examples/demo-leads.json

# See who has the ball (your side first)
bin/waiting-on lead list

# A compact open-loops pane, suitable for a terminal or a cmux column
bin/waiting-on pane

# Render a static, self-contained HTML board from the current leads
python3 scripts/render_lead_board.py --out board.html

To wire up real sources (email accounts, agent-session roots, domains, and profiles), copy config.example.toml to ~/.config/waiting-on/config.toml and edit it. The example file documents the tenant-wall and profile model inline.

Documentation

• docs/open-loops-ledger-design.md: the design and phased plan, including the tenant-wall model.
• docs/agent-threads-adapter-spec.md: how the agent-session collector decides a session is a forgotten open loop.
• docs/cli-contract.md: the machine-readable CLI contract and exit codes.
• docs/security.md: what is and is not stored, and why there is no send path.
• docs/studio-spec.md and docs/calibration-and-panes.md: the TUI and the live-tuning panes.
• docs/agent-integration.md: driving waiting-on from an agent.

Status

Early and actively developed: this repository was extracted from a working personal deployment, so the interfaces are real but may still shift, and the demo leads shipped here are synthetic.

Known rough edges:

• The agent-threads classifier is a deterministic tail heuristic over transcript events. It is conservative and tunable (idle-hours and max-age dials), but it can still misjudge an unusual session; treat its waiting_on_me calls as strong hints, not verdicts.
• The email adapter expects an external Gmail MCP server to be configured (its command is set in config). waiting-on deliberately does not hold Gmail credentials itself, so email refresh does nothing until that is wired up.
• Additional channels (for example iMessage) and an optional LLM enrichment pass are described in the design doc but not yet built. Today the collectors are deterministic and zero-LLM.
• The config example is intentionally minimal. Multi-domain setups work, but you configure the domains, accounts, and profiles by hand.

License

MIT. See LICENSE.