Repository Guidelines

tmact is a Go CLI for local tmux automation, mainly for people running AI agents in terminal panes. It can list and inspect panes, detect idle/running or asking states, send guarded input, create/reuse agent sessions, run scheduled loops, answer narrow allowlisted prompts, and publish pane status for a local web UI.

CLI

The entrypoint is cmd/tmact/main.go; most behavior lives under internal/. Common commands:

• tmact ls lists tmux panes and caches numbered targets like -t 0.
• tmact inspect --all classifies panes by runtime and activity state.
• tmact wait --target session:0.0 --until input-ready --timeout 5m waits read-only for a bounded pane state transition or terminal blocker.
• tmact -t 0 send --text "status?" --enter previews input; --execute actually sends it.
• tmact detect --target session:0.0 --json detects directory-access prompts.
• tmact status, inbox, summarize, broadcast, and panels use an agent YAML config.
• tmact loop and tmact watch run pane automation with dry-run support. tmact loop example [--quota] prints a complete self-contained YAML template. Loops accept an optional quota block that skips cycles when the target agent lacks the configured 5-hour reserve or positive weekly pace headroom (see examples/quota-aware-loop.yaml). An optional top-level calendar block (IANA timezone, weekdays, windows of HH:MM start-inclusive/end-exclusive) limits when actions and flows may start (see examples/workday-loop.yaml).
• tmact dispatch-work starts or reuses a tmux session, launches an agent CLI, and sends it a prompt. For a configured remote machine, use tmact dispatch-work SESSION --peer NAME ...; this creates or reuses the session on that peer. Do not SSH to the peer to invoke tmact unless the operator explicitly requests SSH.
• tmact statusd maintains the cached pane snapshot used by status lines and the browser UI.
• tmact feedback "message" --category ux|bug|feature|docs|perf --command NAME appends local usage feedback to ~/.tmact/feedback.jsonl.

Feedback

Whenever tmact gets in your way (a confusing command, missing flag, unparseable output, or unhelpful error), record it in the moment with tmact feedback "<what was awkward + what you expected>" --category ux|bug|feature|docs|perf --command <cmd>. The entry stays local and is never uploaded.

Web Interface

statusd can serve a local browser UI, bound to 127.0.0.1 by default. The UI shows sessions and panes, streams selected pane output, sends text or keys back to panes, offers quick prompt buttons, uploads files or clipboard images and pastes their saved paths, and can use configured speech-to-text for voice input. It also owns same-origin PWA Web Push: /sw.js handles push and notificationclick, focuses an existing same-origin vibe window when possible, and only opens same-origin paths. Configure VAPID with TMACT_WEBPUSH_VAPID_PRIVATE_KEY, TMACT_WEBPUSH_VAPID_PUBLIC_KEY, TMACT_WEBPUSH_VAPID_SUBJECT or the matching webpush_* keys in ~/.tmact/statusd.json; do not commit private keys. Subscriptions default to ~/.tmact/webpush_subscriptions.json.

Development

The browser UI is a Vite + React + TypeScript app under internal/web/frontend/. Its production build is emitted into internal/web/static/ (embedded via go:embed) and is not committed — internal/web/static/ holds only .gitkeep in git. Build it before building/testing the Go binary.

• Build everything: make build (runs the frontend build, then go build ./...).
• Build just the UI: make web (Vite → internal/web/static/). Requires Node (the repo was set up with Node 22 + npm 10).
• Run tests: make test (frontend Vitest + go test ./...). For Go-only after a build, go test ./... works; the build-dependent web tests t.Skip when the UI has not been built.
• Live UI dev loop: make web-dev runs the Vite dev server on :5234 and proxies /api + /ws to a running statusd (default 127.0.0.1:7890; override with TMACT_STATUSD=host:port). Lets you iterate on the UI without rebuilding the Go binary.
• Run local commands with go run ./cmd/tmact ... (build the UI first if you need the web server).
• Use gofmt on edited Go files; the frontend is TypeScript-strict (make web type-checks via tsc before bundling).
• Keep Go dependencies minimal; current external Go deps are YAML config, websocket packages, and Web Push/VAPID support. The frontend's npm deps live in internal/web/frontend/.

Agent Skills

Canonical tmact-owned skills live under skills/. The matching entries in .agents/skills/, .claude/skills/, ~/.codex/skills/, and ~/.claude/skills/ are symlinks; edit only the canonical directories. After a skill change, run the skill-creator quick_validate.py and scripts/install-skills.sh --check. Keep machine-specific local-* skills ignored unless their host and path configuration has first been externalized.

Safety

This tool presses keys in live tmux panes. Default to dry-runs, keep targets explicit, preserve watcher allowlists, and do not auto-confirm permission, approval, or broad path prompts. Folder trust is the only opt-in exception: it must use --trust-folder, --trust-folders, or trust_folder: true, support only Claude/Codex, and require exact canonical pane-cwd/allowed-dir equality. Keep the web UI on 127.0.0.1 unless the operator explicitly chooses a trusted-network bind.