https://github.com/chquandogong/qmonster
Observe-first TUI for multi-CLI tmux work — alerts, token-pressure, recommendations across Claude / Codex / Gemini panes. 멀티-CLI 세션 관측·권고 Rust TUI.
https://github.com/chquandogong/qmonster
ai-cli ai-observability claude-code codex gemini-cli github-packages observability ratatui rust rust-tui terminal-ui tmux tui
Last synced: 17 days ago
JSON representation
Observe-first TUI for multi-CLI tmux work — alerts, token-pressure, recommendations across Claude / Codex / Gemini panes. 멀티-CLI 세션 관측·권고 Rust TUI.
- Host: GitHub
- URL: https://github.com/chquandogong/qmonster
- Owner: chquandogong
- License: mit
- Created: 2026-04-20T09:04:08.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-05-08T05:15:58.000Z (23 days ago)
- Last Synced: 2026-05-08T05:39:38.220Z (23 days ago)
- Topics: ai-cli, ai-observability, claude-code, codex, gemini-cli, github-packages, observability, ratatui, rust, rust-tui, terminal-ui, tmux, tui
- Language: Rust
- Homepage: https://github.com/chquandogong/qmonster#readme
- Size: 9.2 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
- Support: SUPPORT.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
Qmonster
Observe-first Rust TUI for multi-CLI tmux development.
Quick Start
· What It Shows
· Data Contracts
· Releases
· Discussions
· UI Manual
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.3.5` |
| npm | `qmonster@2.3.5` |
| Rust | `1.88+` |
| Runtime version | `git describe --tags --always --dirty` from `build.rs` |
| Cargo crate version | `2.3.5` |
## 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](docs/ai/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.
```bash
# 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
```
**Set the stage** — Qmonster watches a tmux session that already has
your AI CLI panes running. Spin one up however you like, then attach:
```bash
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:
```bash
# 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:
```bash
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:
```bash
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](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](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:
```sh
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](docs/RELEASE_VERIFICATION.md).
## Architecture
```text
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](docs/ai/ARCHITECTURE.md) for module-level detail.
## Repository Layout
```text
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
```bash
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:
```bash
./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](docs/ai/PROJECT_BRIEF.md) — scope and operating principles
- [ARCHITECTURE.md](docs/ai/ARCHITECTURE.md) — module layout and data flow
- [UI_MANUAL.md](docs/ai/UI_MANUAL.md) — TUI keys, badges, and metric meanings
- [VALIDATION.md](docs/ai/VALIDATION.md) — validation gates
- [WORKFLOWS.md](docs/ai/WORKFLOWS.md) — planning and handoff workflow
- [REVIEW_GUIDE.md](docs/ai/REVIEW_GUIDE.md) — reviewer contract
- [docs/RELEASING.md](docs/RELEASING.md) — release and package mirror flow
- [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md) — tested runtime and provider surfaces
- [docs/RELEASE_VERIFICATION.md](docs/RELEASE_VERIFICATION.md) — checksums, build provenance, and SBOM verification
- [docs/GITHUB_POLISH.md](docs/GITHUB_POLISH.md) — repo polish checklist and next steps
- [SECURITY.md](SECURITY.md) / [SUPPORT.md](SUPPORT.md) / [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) — reporting and community routing
- [VERSION.md](VERSION.md) — version surface map
## Community
- Contributors: [CONTRIBUTORS.md](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](LICENSE).