---
id: TAMQ-WP-0004
type: workplan
title: "Operator-installable local alpha session"
domain: communication
repo: tmux-amq
status: ready
owner: codex
topic_slug: coulomb-social
planning_priority: P0
planning_order: 10
created: "2026-08-24"
updated: "2026-08-24"
---

# Operator-installable local alpha session

Make tmux-amq directly usable by the operator from a normal local shell without
running it from the source checkout or manually assembling service, tmux, and
agent commands.

## Alpha user journey

The completed workflow must be:

```bash
git clone <tmux-amq-remote>
cd tmux-amq
make install

tamq --version
tamq start tmux-amq
```

`tamq start tmux-amq` starts or reuses the local service and managed `tamq`
session, opens the `tmux-amq` gita repository in its registered path, launches
Codex behind `tamq tap`, and attaches the operator to the session. The detached
workflow must also work:

```bash
tamq start --detach tmux-amq
tamq status
tamq attach
```

## Acceptance gates

- `make install` is documented, repeatable, and installs an isolated `tamq`
  command into the invoking user's normal executable path.
- Installation and upgrade do not require activating the repository `.venv`.
- Missing `uv`, tmux, gita, Codex, PATH configuration, or repository
  registration produces a direct actionable error before a partial session is
  left behind.
- The first and subsequent windows start in their exact `gita freeze` paths.
- Default `tamq start` attaches; `--detach` returns to the caller and prints a
  useful endpoint/session summary; `tamq attach` attaches later.
- Repeating `tamq start` safely reuses the service/session and does not create
  duplicate repository windows or agent processes.
- A real installed-package smoke test proves start, attach/detach, status,
  message routing, history visibility, stop, and bounded cleanup on this local
  environment.
- The README contains a short install/start/stop/uninstall quickstart and states
  the alpha reliability boundaries from `SCOPE.md`.

## Add the user-level install target

```task
id: TAMQ-WP-0004-T01
status: todo
priority: high
```

Add a phony `make install` target using uv's isolated tool installation flow,
with an explicit upgrade/reinstall behavior suitable for repeated development
installs. Verify `command -v tamq`, `tamq --version`, and invocation from outside
the checkout. Document the corresponding uninstall command and executable-path
expectation.

## Make session startup match the CLI contract

```task
id: TAMQ-WP-0004-T02
status: todo
priority: high
```

Implement the currently unused `--detach` flag. Make non-detached `tamq start`
attach to the managed session after successful endpoint registration and pending
delivery. Ensure the first boot window uses the selected repository's registered
path rather than the caller's current directory, and preserve idempotent reuse of
existing windows.

## Add installation and startup preflight

```task
id: TAMQ-WP-0004-T03
status: todo
priority: high
```

Before mutating tmux or service state, check the required commands, exact gita
targets and paths, writable runtime/state locations, agent command availability,
and session conflicts. Return concise remediation for every failure and avoid
leaving boot windows, sockets, pidfiles, or processes behind after a failed
start.

## Prove the installed local session end to end

```task
id: TAMQ-WP-0004-T04
status: wait
priority: high
```

Add automated coverage using an isolated uv tool directory, state directory,
socket, and tmux server. Use a deterministic benign agent fixture in automation,
then perform the operator acceptance with the installed `tamq` command and Codex.
Prove attach/detach semantics, correct pane directories, idempotent reuse,
message injection/history, shutdown, and cleanup. This task follows T01-T03.

## Publish the alpha quickstart and evidence

```task
id: TAMQ-WP-0004-T05
status: wait
priority: medium
```

Update README and agent workflow documentation with prerequisites, install,
upgrade, start, attach, status, stop, and uninstall commands. Record the exact
local acceptance commands and results. Clearly retain the reliability caveats
owned by `TAMQ-WP-0003` and do not claim coordination-engine integration from
`TAMQ-WP-0002`. This task follows T04.