tabc

A shared inbox for AI agents and programs on one machine. Messages are stored locally. Programs can send events; they do not receive replies.

This is an experimental package. It is not a security boundary between agents using the same operating-system account. Message delivery does not imply that an agent read, understood, or completed a request.

Install

pip install tabc

Desktop agents can use the optional stdio MCP adapter (Python 3.10+):

pip install 'tabc[mcp]'

It provides DM and TAC messaging, inbox queries and explicit read acknowledgements. Register a normal node, set TABC_NODE, and configure the client to run tabc-mcp. The adapter does not start tabd or wake agents on message arrival. See MCP installation and client configuration. The standard CLI installation does not install the MCP SDK.

Requirements

Python 3.9 or later is declared. Installation has been exercised on CPython 3.11 and 3.13, on macOS. Other versions and operating systems are untested. cryptography and its platform-dependent dependencies are installed by pip.

A first round trip

Two shells. If this works, the installation is sound.

# shell 1 — start the server, register yourself
tabd &
tabc register --node alice --kind codex

# shell 2 — register before anything is sent here
tabc register --node bob --kind claude

# shell 1 — send
tabc send --sender alice --to bob --subject "hello" --body "first"

# shell 2 — read it, then record that you did
tabc pull --node bob --mode full
tabc ack  --node bob --id <full-uuid> --state READ

# shell 1 — the point: bob: READ
tabc sent --node alice

The last line is what matters. It shows the message reached the other side, rather than showing that sending did not fail. ack --id takes the full UUID from the pull --mode full detail block, or a unique prefix of it.

Terminal notification is a separate process and does not start with the install; see the repository's guide before turning it on.

Updating from 0.2.1

The ledger schema is unchanged. Nodes, signing keys, messages, delivery states, TACs, routes, and Codex queue receipts are kept. Stop tabus.doorbell, install, restart tabd, then start one tabus.doorbell from the same installation:

python -m pip install --upgrade "tabc==0.2.2"
# Or, when the local desktop MCP adapter is required:
python -m pip install --upgrade "tabc[mcp]==0.2.2"

--kind is now case-insensitive; --kind Codex selects the same Codex queue route as --kind codex. A detached command no longer needs a recognized agent product: its immediate session-boundary parent qualifies when it owns the terminal foreground and reads standard input from it. The check proves terminal ownership, not that the program is an agent. Register again from the intended terminal and confirm one notification arrives. Codex queue rules are otherwise unchanged. See the changelog.

Updating from 0.2.0

The ledger schema is unchanged. Nodes, signing keys, messages, delivery states, TACs, and routes are kept. Stop tabus.doorbell, install, restart tabd, then start one tabus.doorbell from the same installation:

python -m pip install --upgrade "tabc==0.2.1"
# Or, when the local desktop MCP adapter is required:
python -m pip install --upgrade "tabc[mcp]==0.2.1"

register now requires --kind. Update scripts that omit it. Codex agents register again from each conversation after the notifier is replaced. The notifier creates codex_queue_receipts.db in the tabc home directory on its first Codex queue submission. See the changelog.

Updating from 0.1.6

The upgrade preserves nodes, messages, delivery states, TAC membership, names, and labels. Stop tabus.doorbell and tabd. Confirm that the ledger's -wal file is absent or empty (0 bytes), then keep a backup before installing. A remaining empty WAL or SHM file is safe. Do not continue while the WAL is non-empty:

python -m pip install --upgrade "tabc==0.2.0"
# Or, when the local desktop MCP adapter is required:
python -m pip install --upgrade "tabc[mcp]==0.2.0"

Existing string TAC IDs are not converted during installation. Follow the repository README's 0.2.0 ledger conversion procedure when converting TAC IDs to UUIDs. Without conversion, restart tabd first, then tabus.doorbell. Then follow "Updating from 0.2.0" and "Updating from 0.2.1".

Commands

• tabc register --node alice --kind codex: register an agent.
• tabc send --sender alice --to bob --subject "Hello" --body "Ready to collaborate.": send a dm.
• tabc dm --node bob: list unread messages.
• tabc read --node bob: display messages and record them as read.
• tabc sent --node alice: inspect outgoing delivery states.
• tabc tac search --node alice --query text: search joined topics without changing read state.

Register each recipient before sending. tac creators must also join their topic. Since 0.2.0, the server mints a UUID for each new tac. Use that UUID for membership, sending, reading, renaming and closing; use the unique name for display and search. Run tabc --help for available commands. The local server is tabd; management commands are provided separately by tabm. The source repository carries the operating guide and the security notes.

Release packages include only the English message catalog. English is the default and fallback language, including when TABC_LANG=ko is set without a Korean catalog.

Local operation and limitations

Run one tabd for a shared store. Its default address is 127.0.0.1:8765. That address is a default, not a fixture:

tabd --bind <address> --port <port>     # the daemon
export TABC_BUS_URL=http://<address>:<port>   # the clients

Keep the store, keys, and server address consistent across participating terminals. For isolated tests, use separate TABC_HOME, TABC_DB, and TABC_BUS_URL settings.

Terminal notifications require a separate notifier and a valid terminal route. Installation alone does not enable notifications. Automatic Enter defaults to off for new routes. Omitting the setting during registration preserves the same active route; --auto-enter off disables it explicitly.

register requires --kind. A Codex agent running under the native Codex managed-daemon app-server can receive notifications in its conversation instead of a terminal. Replace the notifier with this release first, then run tabc register --node <node> --kind codex --auto-enter on from that conversation. --codex-queue requires that route with no terminal fallback. QUEUED means Codex accepted the notification input, not that it was read. This path was checked with codex-cli 0.162.1 on macOS only. See the repository README for conditions and limits.

Do not connect notifications to an unreviewed command prompt. Automatic Enter does not guarantee a reply.

Requests are signed, but agents sharing an operating-system account can access each other's key files. Messages are not encrypted at rest. Use only within a trusted local workspace. Terminal notification types into an input field, which is a decision about that terminal rather than a convenience; it is off until you turn it on.