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 local alpha provides tmux endpoint lifecycle, local SQLite history and leases, direct @repo: routing, JSONL export/replay, and a Unix-socket protocol for a later coordination-engine adapter.

Install and start a local session

Prerequisites must be available on PATH: Python 3.11+, uv, tmux, gita, and the agent command you want to run (codex by default). Each repository must already have an exact gita slug and path.

Install or upgrade tamq as an isolated user tool:

make install
command -v tamq
tamq --version

Start an attached two-repository Codex session:

tamq start --command codex railiance-platform activity-core

This creates or reuses the managed tamq session, opens same-named windows in the exact gita paths for railiance-platform and activity-core, launches Codex behind tamq tap in each new window, and attaches to the first window. Codex is the default, so this is equivalent:

tamq start railiance-platform activity-core

Set up the session without attaching, then attach later:

tamq start --detach --command codex railiance-platform activity-core
tamq status
tamq attach

Repeated starts reuse existing windows and do not launch a second agent in them. --cmd remains an alias for --command. A quoted command may include arguments, for example --command 'codex --profile local'.

An already-running pane keeps the tamq tap code that launched it. After upgrading from an earlier alpha, recreate the managed session once so terminal mode and resize fixes take effect:

tamq stop
tmux kill-session -t tamq
tamq start --command codex railiance-platform activity-core

For degraded tmux-only use, tamq start --no-service ... launches the selected agent directly, without tamq tap, socket endpoint registration, or message delivery. Stop the broker and remove the managed tmux session explicitly when finished:

tamq stop
tmux kill-session -t tamq

Uninstall the user tool from the checkout with make uninstall, or from anywhere with uv tool uninstall tmux-amq.

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 alpha 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 in raw terminal mode, propagates terminal resize and lifecycle signals, and observes 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"

Policy profiles accept a safety-gated retry cap of at most nine attempts, but the alpha delivery path does not enforce attempt counting yet. Explicit acknowledgement exists, while delivery_ack_mode enforcement and bounded retry state are tracked in TAMQ-WP-0003. Use --policy-profile to select a profile; --orwell enables explicitly unsafe local diagnostics.

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