waiting-on
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@waiting-on what's waiting on me from my emails and agent sessions?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Ledgerfacade), 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. TheLedgerfacade raisesTenantWallErrorwhen a caller reaches for a domain outside its profile, andAmbiguousDomainErrorwhen a bareline_idexists 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 raisesLeadWriteBusy(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 aGmailMcpErrorrather 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.
Related MCP server: agent-inbox-mcp
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 boardThe 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.htmlTo 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.mdanddocs/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_mecalls 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.
Available Tools
12 toolswaiting_on_draft_replyC
Preview or create a Gmail draft. Never sends.
Inputs: thread_key.
waiting_on_exportD
Export waiting-on data.
Inputs: format.
waiting_on_healthC
Show waiting-on health.
Inputs: no named parameters.
waiting_on_lead_addC
Add one manual lead. Requires name, channel, and ball.
Inputs: ball (required), name (required), channel (required), due, +6 more.
waiting_on_lead_bumpC
Set who has the ball and record a note. Transactional; returns a structured conflict on a lost race.
Inputs: ball (required), note (required), line_id (required), domain.
waiting_on_lead_listC
List manual leads (our ball first). Filters: status/ball/org/match/domain.
Inputs: org, ball, limit, match, +2 more.
waiting_on_listB
List tracked threads by ball or state (alias of loops).
Inputs: no named parameters.
waiting_on_loopsC
Open loops across all allowed domains and channels.
Inputs: no named parameters.
waiting_on_refreshB
Refresh waiting-on from Gmail_multi or a fixture.
Inputs: no named parameters.
waiting_on_refresh_agentsB
Refresh agent-thread open loops (Claude Code + Codex sessions).
Inputs: no named parameters.
waiting_on_refresh_voiceA
Refresh voice-queue open loops (JSONL event log; observe-only).
Inputs: no named parameters.
waiting_on_showC
Show one thread with evidence snippets.
Inputs: thread_key.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
The alias between waiting_on_loops and waiting_on_list creates direct ambiguity, as they are the same operation. The three refresh tools are distinct but share the same verb prefix, which could cause misselection. Other tools are sufficiently differentiated.
All tools share the consistent 'waiting_on_' prefix, but the suffixes are a mix of nouns (loops, health, export) and verb phrases (draft_reply, lead_add, lead_bump), with no clear pattern. The alias also undermines naming distinctness.
With 12 tools, the server covers its domain without being overwhelming or insufficient. Each tool serves a distinct function except for the alias, and the count supports a focused scope.
The toolset covers listing, showing, refreshing, and basic lead management, but lacks operations to close or delete threads, send drafts, or remove leads. This leaves obvious gaps for a tracking system, limiting agent autonomy.
Maintenance
Related MCP Connectors
MCP server for OnceAsk, the AI-native current-address layer for people and agents.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Hosted MCP memory and agent control plane for durable conversations, jobs, and operations.
Project tracker for AI agents and teams: file, claim, update and hand off tickets over MCP.
Related MCP Servers
- FlicenseNot gradedqualityBmaintenanceAn MCP server that provides persistent memory for AI agents, enabling context retention across sessions and supporting vibe-loop workflows where agent promises and deliverables are tracked and validated.2-
- AlicenseNot gradedqualityDmaintenanceMCP server that lets AI agents manage an Agent Inbox queue via natural language. It supports listing pending items, adding new URLs with notes, and marking items as reviewed or deleted.4MIT
- AlicenseNot gradedqualityCmaintenanceMCP server for tracking decision logs and open questions in AI-assisted projects, offering tools to fetch context, list decisions and open items, and draft new decisions.7 npmMIT
- AlicenseNot gradedqualityBmaintenanceMCP server for agentic task orchestration and management, enabling AI agents to create goals, plan tasks with acceptance criteria, track dependencies, request human input, and provide proof of completion.16 npm3MIT