<p align="center">
<img src="assets/argus_logo.png" alt="Argus Logo" width="240">
</p>
<h1 align="center">Argus</h1>
<p align="center">
<a href="https://github.com/rlaope/Argus/actions/workflows/ci.yml"><img src="https://github.com/rlaope/Argus/actions/workflows/ci.yml/badge.svg" alt="Build"></a>
<a href="LICENSE"><img src="https://img.shields.io/github/license/rlaope/Argus" alt="License"></a>
<a href="https://openjdk.org"><img src="https://img.shields.io/badge/Java-11%2B-blue" alt="Java"></a>
<a href="https://github.com/rlaope/Argus/stargazers"><img src="https://img.shields.io/github/stars/rlaope/Argus" alt="GitHub stars"></a>
</p>
> **One CLI for all JVM diagnostics.** 71 commands, zero agent required, works on Java 11+.
> The free alternative to GCEasy + jcmd + VisualVM + Arthas + Eclipse MAT combined โ GC analysis, health diagnosis, flame graphs, async-profiler integration, MAT-class heap leak analysis, continuous profiling, distributed-tracing correlation, opt-in live method instrumentation, ZGC live monitoring, and CI/CD profile gates.
---
## Quick Start
```bash
# Install (macOS / Linux)
curl -fsSL https://raw.githubusercontent.com/rlaope/argus/master/install.sh | bash
# Windows (PowerShell)
irm https://raw.githubusercontent.com/rlaope/argus/master/install.ps1 | iex
```
```bash
argus doctor <pid> # One-click JVM health diagnosis
argus zgc <pid> # ZGC live diagnosis (30s JFR capture + verdict)
argus profile <pid> --duration=30 # CPU/allocation profiling via async-profiler
```
Shell completions (bash, zsh, fish, PowerShell) are installed automatically.
---
## JVM Harness
Continuous JVM monitoring + optimization + troubleshooting on top of Argus, available as a Claude Code plugin.
```
/plugin marketplace add https://github.com/rlaope/Argus
/plugin install argus-jvm-harness
```
CLI equivalent (no Claude Code required):
```bash
argus harness <pid> # 30-min trend-aware health watch
argus harness <pid> --profile=quick --duration=1m
argus harness <pid> --out=session.json --format=json
```
The harness samples on a fixed interval, runs the doctor rule set plus four trend rules (heap-leak regression, GC overhead trend, thread growth, pause-time regression), and produces a single session report with severity-ranked findings and JVM-flag suggestions.
Full reference: [docs/harness.md](docs/harness.md)
---
## Why Argus?
One CLI to diagnose a live JVM and watch a fleet โ no agent, no restart, no `-javaagent`. It attaches externally over `jcmd`/JMX and reads the JVM right where it runs.
- **Zero-install live attach** โ point it at a PID; the target needs no restart and no agent flag.
- **One-command health verdict** โ `argus doctor` returns HEALTHY / WARN / CRITICAL with machine-readable exit codes for CI gates.
- **MAT-class heap analysis, offline** โ dominator tree, retained sizes, and automated leak suspects on multi-GB dumps within a bounded heap.
- **Continuous profiling, no TSDB** โ disk-backed per-pod CPU/alloc flamegraphs with time-window merges and differential views.
- **GC โ trace correlation** โ see which traces a GC pause stalled, exported as OTel spans and Prometheus exemplars.
- **Opt-in live instrumentation** โ watch/trace/monitor method args, returns, and timing via dynamic attach; default OFF, auto-detach, zero residual bytecode.
- **JVM right-sizing for FinOps** โ `argus rightsize` recommends `-Xmx` and container memory from observed heap high-water-mark and GC headroom.
- **GC-aware verdicts & Loom** โ `argus g1` / `argus zgc` flag allocation stalls, cycle overlap, and SoftMax breaches; virtual-thread pinning detection on Java 21+.
- **OpenTelemetry-native** โ OpenMetrics `/prometheus`, OTLP export, and a shipped Grafana dashboard.
> 71 commands in total โ full reference: [docs/cli-commands.md](docs/cli-commands.md)
---
## Roadmap At A Glance
<p align="center">
<img src="assets/argus-roadmap.png" alt="Argus roadmap showing CLI and TUI, APM Core, Micrometer, Observability, Profiling, Heap and GC, Fleet and Kubernetes, and Automation lanes">
</p>
Argus keeps the fast single-PID JVM workflow at the center, then layers standard metrics, traces, profiles, dashboards, fleet views, and APM-grade service workflows around it.
---
## Example: `argus doctor <pid>`
```
$ argus doctor 39113
โญโ Health Diagnosis โโ pid:39113 โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฎ
โ โ
โ โ
Heap usage normal 41M / 256M (16%) โ
โ โ
GC overhead acceptable 0.3% โ
โ โ
No deadlocks detected โ
โ โ
Thread count normal 29 threads โ
โ โ Metaspace near limit 96.5% โ consider -XX:MaxMetaspaceSize โ
โ โ Old Gen elevated 41.8% โ monitor for promotion pressure โ
โ โ
โ Overall: WARN โ 2 recommendations โ
โ โ
โ Tuning Tips โ
โ โ Add -XX:MaxMetaspaceSize=256m to prevent unlimited growth โ
โ โ Run argus gclog <file> to analyze GC pressure over time โ
โ โ
โฐโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฏ
```
Exit codes are machine-readable: `0` = healthy, `1` = warnings, `2` = critical.
---
## Where to Learn More
| Topic | Doc |
|-------|-----|
| Installation, prerequisites, Java version compatibility | [docs/getting-started.md](docs/getting-started.md) |
| All commands with output examples | [docs/cli-commands.md](docs/cli-commands.md) |
| Usage walkthroughs (agent, Spring Boot, ZGC, CI/CD, monitoring stack) | [docs/usage.md](docs/usage.md) |
| Agent properties, flag tables, env vars | [docs/configuration.md](docs/configuration.md) |
| Module layout, SPI patterns, architecture diagrams | [docs/architecture.md](docs/architecture.md) |
| Build, commit, i18n, release procedures | [docs/contributing.md](docs/contributing.md) |
| Common errors and fixes | [docs/troubleshooting.md](docs/troubleshooting.md) |
---
## Building from Source
```bash
./gradlew :argus-cli:fatJar
```
See [docs/contributing.md](docs/contributing.md) for the full build, test, and release workflow.
---
## License & Contributing
MIT License โ see [LICENSE](LICENSE).
Contributions welcome โ bugs, features, docs, tests. See [docs/contributing.md](docs/contributing.md).
Maintainer: [@rlaope](https://github.com/rlaope)