{"id":49457042,"url":"https://github.com/chquandogong/qmonster","last_synced_at":"2026-05-14T07:04:16.232Z","repository":{"id":352613104,"uuid":"1215794208","full_name":"chquandogong/qmonster","owner":"chquandogong","description":"Observe-first TUI for multi-CLI tmux work — alerts, token-pressure, recommendations across Claude / Codex / Gemini panes. 멀티-CLI 세션 관측·권고 Rust TUI.","archived":false,"fork":false,"pushed_at":"2026-05-08T05:15:58.000Z","size":9650,"stargazers_count":0,"open_issues_count":6,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-08T05:39:38.220Z","etag":null,"topics":["ai-cli","ai-observability","claude-code","codex","gemini-cli","github-packages","observability","ratatui","rust","rust-tui","terminal-ui","tmux","tui"],"latest_commit_sha":null,"homepage":"https://github.com/chquandogong/qmonster#readme","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chquandogong.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-20T09:04:08.000Z","updated_at":"2026-05-08T05:16:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/chquandogong/qmonster","commit_stats":null,"previous_names":["chquandogong/qmonster"],"tags_count":154,"template":false,"template_full_name":null,"purl":"pkg:github/chquandogong/qmonster","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chquandogong%2Fqmonster","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chquandogong%2Fqmonster/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chquandogong%2Fqmonster/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chquandogong%2Fqmonster/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chquandogong","download_url":"https://codeload.github.com/chquandogong/qmonster/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chquandogong%2Fqmonster/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33012815,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T13:14:54.681Z","status":"online","status_checked_at":"2026-05-14T02:00:06.663Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-cli","ai-observability","claude-code","codex","gemini-cli","github-packages","observability","ratatui","rust","rust-tui","terminal-ui","tmux","tui"],"created_at":"2026-04-30T07:02:30.091Z","updated_at":"2026-05-14T07:04:16.214Z","avatar_url":"https://github.com/chquandogong.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/qmonster-banner.svg\" alt=\"Qmonster: observe-first TUI for Claude, Codex, and Gemini tmux panes\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eQmonster\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eObserve-first Rust TUI for multi-CLI tmux development.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/chquandogong/qmonster/actions/workflows/ci.yml\"\u003e\u003cimg alt=\"CI\" src=\"https://github.com/chquandogong/qmonster/actions/workflows/ci.yml/badge.svg\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/chquandogong/qmonster/releases\"\u003e\u003cimg alt=\"GitHub release\" src=\"https://img.shields.io/github/v/release/chquandogong/qmonster?display_name=tag\u0026sort=semver\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/qmonster\"\u003e\u003cimg alt=\"npm version\" src=\"https://img.shields.io/npm/v/qmonster?label=npm\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/chquandogong/qmonster/pkgs/npm/qmonster\"\u003e\u003cimg alt=\"GitHub Packages mirror\" src=\"https://img.shields.io/badge/GitHub%20Packages-%40chquandogong%2Fqmonster-2f81f7?logo=github\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg alt=\"License\" src=\"https://img.shields.io/github/license/chquandogong/qmonster\"\u003e\u003c/a\u003e\n  \u003cimg alt=\"Rust 1.88+\" src=\"https://img.shields.io/badge/Rust-1.88%2B-b7410e?logo=rust\"\u003e\n  \u003cimg alt=\"tmux\" src=\"https://img.shields.io/badge/tmux-observe--first-1bb91f\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#quick-start\"\u003eQuick Start\u003c/a\u003e\n  · \u003ca href=\"#what-it-shows\"\u003eWhat It Shows\u003c/a\u003e\n  · \u003ca href=\"#data-contracts\"\u003eData Contracts\u003c/a\u003e\n  · \u003ca href=\"https://github.com/chquandogong/qmonster/releases\"\u003eReleases\u003c/a\u003e\n  · \u003ca href=\"https://github.com/chquandogong/qmonster/discussions\"\u003eDiscussions\u003c/a\u003e\n  · \u003ca href=\"docs/ai/UI_MANUAL.md\"\u003eUI Manual\u003c/a\u003e\n\u003c/p\u003e\n\nQmonster watches a tmux workspace that runs Claude Code, Codex, Gemini,\nand Qmonster side by side. It surfaces pane state, token pressure,\nprovider facts, reset timing, safety alerts, and recommendations without\ntaking destructive action by default.\n\n| Surface             | Current                                                |\n| ------------------- | ------------------------------------------------------ |\n| Release             | `v2.3.5`                                               |\n| npm                 | `qmonster@2.3.5`                                       |\n| Rust                | `1.88+`                                                |\n| Runtime version     | `git describe --tags --always --dirty` from `build.rs` |\n| Cargo crate version | `2.3.5`                                                |\n\n## Why\n\nMulti-agent tmux work is powerful, but easy to lose track of. Qmonster\nanswers the operational questions that usually require constant manual\nchecking:\n\n- Which pane is waiting, blocked, stale, or still working?\n- Which session is approaching context or quota pressure?\n- Which provider facts are official, estimated, or heuristic?\n- Which reset window is close enough to wait or snapshot first?\n- Which recommendation is worth acting on now?\n\nThe design contract is intentionally conservative:\n\n1. Observe first.\n2. Alert first.\n3. Recommend first.\n4. No destructive automation by default.\n\nSee [PROJECT_BRIEF.md](docs/ai/PROJECT_BRIEF.md) for the full project\nintent.\n\n## Quick Start\n\n**Install** — pick one. Either path needs a working Rust toolchain\n(`rustc 1.88+`) because the npm package compiles the binary on first run.\n\n```bash\n# 1) From npmjs (recommended for operators)\nnpm install -g qmonster\nqmonster --help\n\n# 2) From source (recommended for contributors)\ngit clone https://github.com/chquandogong/qmonster\ncd qmonster\ncargo build --release\n```\n\n**Set the stage** — Qmonster watches a tmux session that already has\nyour AI CLI panes running. Spin one up however you like, then attach:\n\n```bash\ntmux new -s ai\n# inside tmux: split into panes for claude / codex / gemini / qmonster\n# (or copy the four-pane layout from Provider Setup → Tmux tab → installer)\n```\n\n**Run it** — from another shell or pane:\n\n```bash\n# Creates ~/.qmonster/config/qmonster.toml + pricing.toml from templates\n# when missing, then launches the TUI bound to that config path.\n./scripts/run-qmonster.sh\n```\n\n**First launch** — Qmonster opens to the split dashboard:\n\n- **Top: Alerts** — notices, recommendations, cross-pane findings.\n  Press `/` (v1.59.0) to filter by case-insensitive substring.\n- **Bottom: Panes** — one card per attached AI CLI pane with state,\n  context, quota, tokens, cache, cost, and reset ETA.\n- **Footer** — current target, key cluster, version badge. Click the\n  badge to inspect Git status.\n\nThe most useful first keys:\n\n| Key | Action                                                                                            |\n| --- | ------------------------------------------------------------------------------------------------- |\n| `?` | Help overlay with the full key map and badge legend                                               |\n| `t` | Pick which tmux session/window to observe                                                         |\n| `S` | Settings overlay (`/` filters parameters by label)                                                |\n| `P` | Provider Setup overlay (sidefile + tmux installers)                                               |\n| `i` | Insights overlay (recent operator-affecting actions)                                              |\n| `n` | Anomaly events overlay (`f` cycles severity filter)                                               |\n| `Q` | Open the decorative fx overlay (banner / confetti / matrix / snow / fireworks / plasma / sampler) |\n\n**Smoke checks** if anything looks off:\n\n```bash\ncargo run -- --once                                              # one-pass scan, no UI\n./scripts/check-tmux-source-parity.sh --all-targets --repeat 3   # polling vs control-mode parity\n./scripts/run-qmonster-control-mode-once.sh --root /tmp/qmonster-smoke\n```\n\nGitHub Packages mirrors the npm source package:\n\n```bash\nnpm config set @chquandogong:registry https://npm.pkg.github.com\nnpm install -g @chquandogong/qmonster\n```\n\n## What It Shows\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/qmonster-dashboard.png\" alt=\"Qmonster TUI dashboard: alert queue at the top, per-pane cards below\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n| Area            | Operator-visible result                                              |\n| --------------- | -------------------------------------------------------------------- |\n| Pane state      | Work complete, active, stale, input wait, permission wait, limit hit |\n| Metrics         | CTX, quota, tokens, cache, memory, cost, reset ETA                   |\n| Runtime facts   | Session IDs, transcript paths, tool calls, model reset rows          |\n| Recommendations | Alert/advisory queue with source-labeled reasons and commands        |\n| Settings        | Thresholds, integrations, parameters, rules, badge glossary          |\n| Git status      | Click the footer version badge to inspect local repo state           |\n\nSanitized provider tails for demos and screenshots live in\n[examples/demo](examples/demo/).\n\nPrimary keys:\n\n| Key         | Action                                                     |\n| ----------- | ---------------------------------------------------------- |\n| `q` / `Esc` | Quit or close overlay                                      |\n| `Tab`       | Switch alert/pane focus                                    |\n| `t`         | Choose tmux session/window target                          |\n| `s`         | Write runtime snapshot                                     |\n| `u`         | Refresh provider runtime surfaces                          |\n| `P`         | Provider Setup overlay                                     |\n| `S`         | Settings overlay                                           |\n| `?`         | Help / legend                                              |\n| Mouse       | Scroll, select, double-click alert hide, footer Git status |\n\nFor a matching four-pane tmux layout, open Provider Setup with `P`,\nselect the `Tmux` tab, and copy the installer. It writes:\n\n- `~/ts.sh`\n- `~/.tmux/qmonster.tmux.conf`\n\n## Data Contracts\n\nQmonster labels every provider-derived value by authority:\n\n| Label        | Meaning                                                           |\n| ------------ | ----------------------------------------------------------------- |\n| `[Official]` | Emitted by the provider or a provider-owned config/status surface |\n| `[Project]`  | Qmonster policy or project-canonical rule                         |\n| `[Heur]`     | Local heuristic, such as process RSS or memory-file scan          |\n| `[Estimate]` | Derived from local pricing or non-provider calculation            |\n\nMetric contract:\n\n| Metric   | Claude                             | Codex                       | Gemini                     |\n| -------- | ---------------------------------- | --------------------------- | -------------------------- |\n| `CTX`    | statusline context used            | bottom status context       | status table context       |\n| `QUOTA`  | statusline 5h / weekly             | bottom status or app-server | status table quota         |\n| `RESET`  | sidefile timestamps                | app-server timestamps       | `/model` display rows only |\n| `TOKENS` | statusline + sidefile              | bottom status / usage line  | `/stats model`             |\n| `CACHE`  | statusline ratio or sidefile reads | cached input tokens         | cache reads when exposed   |\n| `COST`   | sidefile total cost                | pricing estimate            | unset today                |\n\nGemini `/model` reset rows are display-only runtime facts. Policy-grade\nreset advisories still require machine-readable timestamps, currently\navailable from Claude sidefiles and Codex app-server only.\n\n## Releases\n\nThe operator-facing version is the Git tag, npm version, and Cargo crate\nversion kept in lockstep. Release automation publishes:\n\n- GitHub Release with Linux x86_64 binary tarball, npm tarball, and checksums\n- npmjs package: `qmonster`\n- GitHub Packages mirror: `@chquandogong/qmonster`\n\nRelease flow lives in [docs/RELEASING.md](docs/RELEASING.md). Long-form\nhistory lives in `mission-history.yaml`; the README only tracks the\ncurrent operator surface.\n\n**Verifying a download** — the released npm tarball and Linux binary\nboth carry SLSA build provenance and SBOM attestations. After\n`npm install -g qmonster`, run:\n\n```sh\nnpm audit signatures                                           # npm registry signature + provenance chain\ngh attestation verify qmonster-X.Y.Z.tgz --owner chquandogong  # GitHub attestation against this repo\n```\n\nThese prove the _tarball_ came from this repository's release\nworkflow. The `qmonster` binary itself is compiled by `cargo` on your\nmachine on first run, so end-to-end trust also depends on your Rust\ntoolchain and the crates.io packages it fetches. Full command set\n(Linux binary tarball, SBOM, scope notes) lives in\n[docs/RELEASE_VERIFICATION.md](docs/RELEASE_VERIFICATION.md).\n\n## Architecture\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/qmonster-architecture.svg\" alt=\"Qmonster observe-first architecture diagram\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n```text\ntmux::RawPaneSnapshot\n   |\ndomain::IdentityResolver\n   |\nadapters::ProviderParser\n   |\ndomain::SignalSet\n   |\npolicy::Engine\n   |\napp::EffectRunner\n   |\\\nui::ViewModel   store::EventSink\n```\n\nBoundaries:\n\n- Identity resolution happens before provider parsing.\n- `policy/` performs no IO.\n- Runtime writes stay under `~/.qmonster/` by default.\n- Raw tmux tails are archived as files, not stored in SQLite.\n- Provider values must keep honest source labels.\n\nSee [ARCHITECTURE.md](docs/ai/ARCHITECTURE.md) for module-level detail.\n\n## Repository Layout\n\n```text\nsrc/\n  app/        bootstrap, config, event loop, effects, overlays\n  adapters/   claude / codex / gemini / qmonster parsers\n  domain/     identity, origin, signal, recommendation, audit types\n  policy/     pure recommendation engine and rules\n  store/      sqlite, audit, archive, snapshots, token samples\n  tmux/       polling and control-mode pane sources\n  ui/         ratatui dashboard, alerts, panels, settings\n\nconfig/       operator config templates\ndocs/ai/      canonical project docs\ndocs/assets/  README and social-preview artwork\n.github/      CI, release, issue, PR, and discussion templates\nnpm/          npm source-package wrapper\nscripts/      local run and validation helpers\ntests/        integration tests\n```\n\n## Development\n\n```bash\ncargo fmt --all --check\ngit diff --check\ncargo test --all-targets\ncargo clippy --all-targets -- -D warnings\nnpm pack --dry-run\n```\n\nFor tmux transport work:\n\n```bash\n./scripts/check-tmux-source-parity.sh --all-targets --repeat 3\n```\n\nThe integration tests use fixture pane sources and do not require a live\ntmux session.\n\n## Documentation\n\n- [PROJECT_BRIEF.md](docs/ai/PROJECT_BRIEF.md) — scope and operating principles\n- [ARCHITECTURE.md](docs/ai/ARCHITECTURE.md) — module layout and data flow\n- [UI_MANUAL.md](docs/ai/UI_MANUAL.md) — TUI keys, badges, and metric meanings\n- [VALIDATION.md](docs/ai/VALIDATION.md) — validation gates\n- [WORKFLOWS.md](docs/ai/WORKFLOWS.md) — planning and handoff workflow\n- [REVIEW_GUIDE.md](docs/ai/REVIEW_GUIDE.md) — reviewer contract\n- [docs/RELEASING.md](docs/RELEASING.md) — release and package mirror flow\n- [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md) — tested runtime and provider surfaces\n- [docs/RELEASE_VERIFICATION.md](docs/RELEASE_VERIFICATION.md) — checksums, build provenance, and SBOM verification\n- [docs/GITHUB_POLISH.md](docs/GITHUB_POLISH.md) — repo polish checklist and next steps\n- [SECURITY.md](SECURITY.md) / [SUPPORT.md](SUPPORT.md) / [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) — reporting and community routing\n- [VERSION.md](VERSION.md) — version surface map\n\n## Community\n\n- Contributors: [CONTRIBUTORS.md](CONTRIBUTORS.md)\n- Discussions: setup help, tmux layouts, provider behavior, and workflow ideas\n- Issues: reproducible bugs and scoped feature requests\n- Security: private vulnerability reports through GitHub Security Advisories\n- Social preview asset: `docs/assets/qmonster-social-preview.png`\n\n## Scope\n\nQmonster is not a provider orchestrator, not a destructive automator, and\nnot a cloud service. It is a single-user local operating console. Default\naction mode is `recommend_only`; refresh policy is `manual_only`; logging\nsensitivity is `balanced`.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchquandogong%2Fqmonster","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchquandogong%2Fqmonster","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchquandogong%2Fqmonster/lists"}