tmux-amq/README.md

tmux-amq

Tmux Agentic Message Queueing (tamq) is a local, durable message queue for agent workers running in gita-registered repositories.

The initial implementation is being bootstrapped from the standalone queue and CLI contract. It will provide tmux endpoint lifecycle, local SQLite history and leases, direct @repo: routing, JSONL export/replay, and a Unix-socket attach protocol for a later coordination-engine adapter.

Development

uv run pytest
uv run tamq --help
uv run tamq --version
uv run tamq start --cmd codex net-kingdom railiance-platform
uv run tamq attach

The bootstrap currently includes the local SQLite queue and a tmux endpoint manager, strict gita target validation, and a control-mode client for tmux operations/injection, and the PTY tap for full-duplex input observation. The control-mode client alone does not expose arbitrary pane input; tamq tap is the supported input-broker hook. tamq send remains available as an explicit fallback. coordination-engine integration remains a later phase.

Terminal architecture

tamq separates terminal coordination into three layers:

1. tmux control mode is the topology and output/control stream;
2. the local broker assigns endpoint/source identity and durably queues intent;
3. tamq tap is a full-duplex PTY proxy around the agent process. It forwards bytes unchanged while observing complete input lines for @repo: routing.

This keeps tmux-specific topology concerns separate from reusable terminal I/O observation and message identity.

Pending messages are delivered through the control-mode client as #sender-repo: body, then marked injected in SQLite. Delivery is endpoint-scoped and uses the same message ID for retry/deduplication. The visible endpoint label is tmux-amq-<PID>; each boot also receives an instance nonce so PID reuse cannot collide with prior leases or receipts.

Configuration

Configuration is read from ${XDG_CONFIG_HOME:-~/.config}/tamq/config.toml (or $TAMQ_CONFIG). Environment variables such as TAMQ_SOCKET and TAMQ_STATE_DIR take precedence. The purge and startup advisory defaults can be tuned without changing command lines:

[tamq]
state_dir = "/run/user/1000/tamq"
purge_before = "365d"
purge_max_size = "100MB"
history_max_size = "100MB"
delivery_poll_interval = "0.5"

[policy.profiles.diagnostics]
safety_gated_max_attempts = 2
delivery_ack_mode = "acknowledged"

Retries remain safety-gated and capped at nine attempts. Use --policy-profile to select a profile; --orwell enables explicitly unsafe local diagnostics.

The Unix socket service now supports structured ping, register, send, and history operations. Endpoint registrations and messages are persisted in the same local SQLite database; delivery remains delegated to the control-mode adapter.