Qmonster watches a tmux workspace that runs Claude Code, Codex, Gemini, and Qmonster side by side. It surfaces pane state, token pressure, provider facts, reset timing, safety alerts, and recommendations without taking destructive action by default.

| Surface | Current | | ------------------- | ------------------------------------------------------ | | Release | v2.4.1 | | npm | [email protected] | | Rust | 1.88+ | | Runtime version | git describe --tags --always --dirty from build.rs | | Cargo crate version | 2.4.1 |

Why

Multi-agent tmux work is powerful, but easy to lose track of. Qmonster answers the operational questions that usually require constant manual checking:

• Which pane is waiting, blocked, stale, or still working?
• Which session is approaching context or quota pressure?
• Which provider facts are official, estimated, or heuristic?
• Which reset window is close enough to wait or snapshot first?
• Which recommendation is worth acting on now?

The design contract is intentionally conservative:

1. Observe first.
2. Alert first.
3. Recommend first.
4. No destructive automation by default.

See PROJECT_BRIEF.md for the full project intent.

Quick Start

Install — pick one. Either path needs a working Rust toolchain (rustc 1.88+) because the npm package compiles the binary on first run.

# 1) From npmjs (recommended for operators)
npm install -g qmonster
qmonster --help

# 2) From source (recommended for contributors)
git clone https://github.com/chquandogong/qmonster
cd qmonster
cargo build --release

Notice — the npm package is a source distribution, not a prebuilt binary. npm install qmonster downloads a tarball that wraps Cargo.toml + Cargo.lock + src/; first invocation runs cargo build --release locally and compiles ~270 transitive crates, each of which may execute a build.rs at compile time. Trust extends to your local Rust toolchain and the crates.io packages it fetches.

If you would rather run the maintainer-built binary (with SLSA build provenance) instead of compiling locally:

gh release download v2.4.1 --pattern '*-linux-x86_64.tar.gz' --repo chquandogong/qmonster
gh attestation verify qmonster-v2.4.1-linux-x86_64.tar.gz --owner chquandogong
tar -xzf qmonster-v2.4.1-linux-x86_64.tar.gz
./qmonster-v2.4.1-linux-x86_64/qmonster --help

Set the stage — Qmonster watches a tmux session that already has your AI CLI panes running. Spin one up however you like, then attach:

tmux new -s ai
# inside tmux: split into panes for claude / codex / gemini / qmonster
# (or copy the four-pane layout from Provider Setup → Tmux tab → installer)

Run it — from another shell or pane:

# Creates ~/.qmonster/config/qmonster.toml + pricing.toml from templates
# when missing, then launches the TUI bound to that config path.
./scripts/run-qmonster.sh

First launch — Qmonster opens to the split dashboard:

• Top: Alerts — notices, recommendations, cross-pane findings. Press / (v1.59.0) to filter by case-insensitive substring.
• Bottom: Panes — one card per attached AI CLI pane with state, context, quota, tokens, cache, cost, and reset ETA.
• Footer — current target, key cluster, version badge. Click the badge to inspect Git status.

The most useful first keys:

| Key | Action | | --- | ------------------------------------------------------------------------------------------------- | | ? | Help overlay with the full key map and badge legend | | t | Pick which tmux session/window to observe | | S | Settings overlay (/ filters parameters by label) | | P | Provider Setup overlay (sidefile + tmux installers) | | i | Insights overlay (recent operator-affecting actions) | | n | Anomaly events overlay (f cycles severity filter) | | Q | Open the decorative fx overlay (banner / confetti / matrix / snow / fireworks / plasma / sampler) |

Smoke checks if anything looks off:

cargo run -- --once                                              # one-pass scan, no UI
./scripts/check-tmux-source-parity.sh --all-targets --repeat 3   # polling vs control-mode parity
./scripts/run-qmonster-control-mode-once.sh --root /tmp/qmonster-smoke

GitHub Packages mirrors the npm source package:

npm config set @chquandogong:registry https://npm.pkg.github.com
npm install -g @chquandogong/qmonster

What It Shows

| Area | Operator-visible result | | --------------- | -------------------------------------------------------------------- | | Pane state | Work complete, active, stale, input wait, permission wait, limit hit | | Metrics | CTX, quota, tokens, cache, memory, cost, reset ETA | | Runtime facts | Session IDs, transcript paths, tool calls, model reset rows | | Recommendations | Alert/advisory queue with source-labeled reasons and commands | | Settings | Thresholds, integrations, parameters, rules, badge glossary | | Git status | Click the footer version badge to inspect local repo state |

Sanitized provider tails for demos and screenshots live in examples/demo.

Primary keys:

| Key | Action | | ----------- | ---------------------------------------------------------- | | q / Esc | Quit or close overlay | | Tab | Switch alert/pane focus | | t | Choose tmux session/window target | | s | Write runtime snapshot | | u | Refresh provider runtime surfaces | | P | Provider Setup overlay | | S | Settings overlay | | ? | Help / legend | | Mouse | Scroll, select, double-click alert hide, footer Git status |

For a matching four-pane tmux layout, open Provider Setup with P, select the Tmux tab, and copy the installer. It writes:

• ~/ts.sh
• ~/.tmux/qmonster.tmux.conf

Data Contracts

Qmonster labels every provider-derived value by authority:

| Label | Meaning | | ------------ | ----------------------------------------------------------------- | | [Official] | Emitted by the provider or a provider-owned config/status surface | | [Project] | Qmonster policy or project-canonical rule | | [Heur] | Local heuristic, such as process RSS or memory-file scan | | [Estimate] | Derived from local pricing or non-provider calculation |

Metric contract:

| Metric | Claude | Codex | Gemini | | -------- | ---------------------------------- | --------------------------- | -------------------------- | | CTX | statusline context used | bottom status context | status table context | | QUOTA | statusline 5h / weekly | bottom status or app-server | status table quota | | RESET | sidefile timestamps | app-server timestamps | /model display rows only | | TOKENS | statusline + sidefile | bottom status / usage line | /stats model | | CACHE | statusline ratio or sidefile reads | cached input tokens | cache reads when exposed | | COST | sidefile total cost | pricing estimate | unset today |

Gemini /model reset rows are display-only runtime facts. Policy-grade reset advisories still require machine-readable timestamps, currently available from Claude sidefiles and Codex app-server only.

Releases

The operator-facing version is the Git tag, npm version, and Cargo crate version kept in lockstep. Release automation publishes:

• GitHub Release with Linux x86_64 binary tarball, npm tarball, and checksums
• npmjs package: qmonster
• GitHub Packages mirror: @chquandogong/qmonster

Release flow lives in docs/RELEASING.md. Long-form history lives in mission-history.yaml; the README only tracks the current operator surface.

Verifying a download — the released npm tarball and Linux binary both carry SLSA build provenance and SBOM attestations. After npm install -g qmonster, run:

npm audit signatures                                           # npm registry signature + provenance chain
gh attestation verify qmonster-X.Y.Z.tgz --owner chquandogong  # GitHub attestation against this repo

These prove the tarball came from this repository's release workflow. The qmonster binary itself is compiled by cargo on your machine on first run, so end-to-end trust also depends on your Rust toolchain and the crates.io packages it fetches. Full command set (Linux binary tarball, SBOM, scope notes) lives in docs/RELEASE_VERIFICATION.md.

Architecture

tmux::RawPaneSnapshot
   |
domain::IdentityResolver
   |
adapters::ProviderParser
   |
domain::SignalSet
   |
policy::Engine
   |
app::EffectRunner
   |\
ui::ViewModel   store::EventSink

Boundaries:

• Identity resolution happens before provider parsing.
• policy/ performs no IO.
• Runtime writes stay under ~/.qmonster/ by default.
• Raw tmux tails are archived as files, not stored in SQLite.
• Provider values must keep honest source labels.

See ARCHITECTURE.md for module-level detail.

Repository Layout

src/
  app/        bootstrap, config, event loop, effects, overlays
  adapters/   claude / codex / gemini / qmonster parsers
  domain/     identity, origin, signal, recommendation, audit types
  policy/     pure recommendation engine and rules
  store/      sqlite, audit, archive, snapshots, token samples
  tmux/       polling and control-mode pane sources
  ui/         ratatui dashboard, alerts, panels, settings

config/       operator config templates
docs/ai/      canonical project docs
docs/assets/  README and social-preview artwork
.github/      CI, release, issue, PR, and discussion templates
npm/          npm source-package wrapper
scripts/      local run and validation helpers
tests/        integration tests

Development

cargo fmt --all --check
git diff --check
cargo test --all-targets
cargo clippy --all-targets -- -D warnings
npm pack --dry-run

For tmux transport work:

./scripts/check-tmux-source-parity.sh --all-targets --repeat 3

The integration tests use fixture pane sources and do not require a live tmux session.

Documentation

• PROJECT_BRIEF.md — scope and operating principles
• ARCHITECTURE.md — module layout and data flow
• UI_MANUAL.md — TUI keys, badges, and metric meanings
• VALIDATION.md — validation gates
• WORKFLOWS.md — planning and handoff workflow
• REVIEW_GUIDE.md — reviewer contract
• docs/RELEASING.md — release and package mirror flow
• docs/COMPATIBILITY.md — tested runtime and provider surfaces
• docs/RELEASE_VERIFICATION.md — checksums, build provenance, and SBOM verification
• docs/GITHUB_POLISH.md — repo polish checklist and next steps
• SECURITY.md / SUPPORT.md / CODE_OF_CONDUCT.md — reporting and community routing
• VERSION.md — version surface map

Community

• Contributors: CONTRIBUTORS.md
• Discussions: setup help, tmux layouts, provider behavior, and workflow ideas
• Issues: reproducible bugs and scoped feature requests
• Security: private vulnerability reports through GitHub Security Advisories
• Social preview asset: docs/assets/qmonster-social-preview.png

Scope

Qmonster is not a provider orchestrator, not a destructive automator, and not a cloud service. It is a single-user local operating console. Default action mode is recommend_only; refresh policy is manual_only; logging sensitivity is balanced.

License

MIT. See LICENSE.