# 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](https://docs.astral.sh/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:

```bash
make install
command -v tamq
tamq --version
```

Start an attached two-repository Codex session:

```bash
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:

```bash
tamq start railiance-platform activity-core
```

Set up the session without attaching, then attach later:

```bash
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:

```bash
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:

```bash
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

```bash
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:

```toml
[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.