{
  "markdown": "# Stallhunt\n\nStallhunt is a Linux-first command-line performance triage tool.\n\nRepository: https://github.com/guillem/stallhunt\n\nTraditional tools such as `top`, `htop`, `iotop`, `vmstat`, and `iostat` expose measurements. They are excellent tools, but the human operator still has to answer the harder question:\n\n> **What is actually constraining useful work right now, who is suffering, and who is probably responsible?**\n\nStallhunt aims to automate that reasoning.\n\n## Install\n\nRequirements:\n\n- Linux 4.20 or newer with procfs mounted; readable PSI files under `/proc/pressure` are required for pressure verdicts,\n- Rust 1.85 or newer for source builds.\n\nSee [`docs/install.md`](docs/install.md) for `cargo install`, release tarballs, and the support matrix.\n\nFrom a clone:\n\n```bash\ncargo install --path .\nstallhunt\n```\n\nBare `stallhunt` runs a default 10-second hunt. On a terminal it renders a\ncompact, color-coded report; piped or redirected output (`stallhunt | cat`,\n`>file`, CI) is unchanged plain text. Use `--json` for the full structured\nevidence, `--verbose` to expand the compact report's collapsed caveats back\nto full text, or `--no-color` (also `NO_COLOR=1`) to disable color without\nchanging the layout:\n\n```bash\nstallhunt --json\nstallhunt hunt --duration 30s\nstallhunt hunt --verbose\n```\n\nCapture and replay a normalized observation:\n\n```bash\nstallhunt record --duration 10s --output incident.json\nstallhunt replay incident.json\nstallhunt redact incident.json --output incident.redacted.json\n```\n\nFollow finding lifecycle for a bounded number of rolling windows. On a\nterminal this opens a full-screen TUI (`q` quit, arrows/`jk` select,\n`Enter`/`Space` show or hide detail, `PageUp`/`PageDown`/`Home`/`End` scroll,\n`h`/`?` help). At 120×30 or larger it also shows the selected host/cgroup's\nsix process-role lists beside the lifecycle panels; piped output or\n`--json` remain append-only text/JSON and carry the same scoped roles:\n\n```bash\nstallhunt watch --interval 2s --count 3\n```\n\nServe Model Context Protocol tools over stdio so coding agents can query\ndiagnoses directly — a resident sampler keeps a rolling view of recent\npressure for instant answers (for Claude Code: `claude mcp add stallhunt --\nstallhunt mcp`; see [`docs/mcp-server.md`](docs/mcp-server.md)):\n\n```bash\nstallhunt mcp [--interval 2s] [--no-sampler]\n```\n\nSource packaging for an OpenAI local plugin, a Linux MCPB extension for\ncompatible clients, and official MCP Registry metadata lives in the\nrepository. These packages deliberately keep diagnosis local instead of\nhosting Stallhunt on a machine other than the one being investigated. See\n[`docs/directory-distribution.md`](docs/directory-distribution.md).\n\nGenerate shell completions:\n\n```bash\nstallhunt completions bash > ~/.local/share/bash-completion/completions/stallhunt\nstallhunt completions zsh > ~/.local/share/zsh/site-functions/_stallhunt\n```\n\nRecording output paths are not overwritten unless `--force` is supplied. Ten-second hunts are the normal diagnostic path; sub-second observations are telemetry smoke tests and do not receive healthy or pressure verdicts. See [`docs/development.md`](docs/development.md) for validation and opt-in acceptance commands.\n\n## Core idea\n\nThe primary abstraction is **lost time**, not utilization.\n\nHigh utilization is not automatically a problem. A machine using 95% of its RAM may be perfectly healthy. A CPU at 70% utilization may still have latency-sensitive work suffering from scheduler contention. The project therefore focuses on evidence of stalled progress:\n\n- CPU scheduler pressure,\n- I/O stalls,\n- memory pressure/reclaim,\n- lock contention,\n- network-related waits,\n- eventually deeper blocking chains.\n\nExample output shape:\n\n```text\n$ stallhunt\n\nSYSTEM HEALTH: DEGRADED\n\n1. CPU scheduling contention                         SEVERE\n   Impact:    23.4% pressure during observation\n   Victims:   postgres [4812], nginx [5120]\n   Suspects:  rustc [9231], ffmpeg [9401]\n   Confidence: high\n\n   Evidence:\n     CPU PSI some avg10:          23.4%\n     run queue latency estimate:  elevated\n     rustc CPU consumption:       735%\n     postgres runnable delay:     3.8s / 10s\n\n2. Block I/O contention                              MODERATE\n   Device:    nvme0n1\n   Victim:    postgres [4812]\n   Suspect:   restic [7712]\n   Confidence: medium\n\nMemory: no significant pressure detected.\nHigh memory occupancy alone is not treated as a bottleneck.\n```\n\nThis output is aspirational; the project will reach it incrementally.\n\n## Product principles\n\n1. **Diagnose, do not merely display.**\n2. **Measure stalled progress whenever possible.**\n3. **Separate observation from inference.**\n4. **Show evidence for every diagnosis.**\n5. **Express uncertainty explicitly.**\n6. **Remain useful without eBPF.**\n7. **Stay cheap enough to run on a stressed system.**\n8. **Treat Git as the complete project memory.**\n\n## Initial scope\n\nThe first useful release targets Linux and focuses on:\n\n- CPU scheduling contention,\n- memory pressure,\n- block I/O pressure,\n- per-process attribution where Linux exposes enough evidence,\n- cgroup/systemd-aware grouping when practical,\n- human-readable terminal output,\n- versioned machine-readable JSON (the pre-1.0 shape may evolve),\n- bounded observation windows,\n- deterministic offline fixture/replay analysis.\n\nLater releases may add:\n\n- eBPF-based off-CPU analysis,\n- futex/lock contention,\n- syscall/blocking attribution,\n- network queue/socket diagnosis,\n- dependency/wait graphs,\n- richer cgroup/container analysis.\n\n## Repository map\n\n```text\n.\n├── AGENTS.md\n├── CHANGELOG.md\n├── Cargo.toml\n├── LICENSE-APACHE\n├── LICENSE-MIT\n├── README.md\n├── src/\n│   ├── analysis.rs\n│   ├── cgroup.rs\n│   ├── cli.rs\n│   ├── cpu.rs\n│   ├── duration_us.rs\n│   ├── io.rs\n│   ├── main.rs\n│   ├── mcp/\n│   ├── memory.rs\n│   ├── observe.rs\n│   ├── psi.rs\n│   ├── record.rs\n│   ├── render.rs\n│   ├── report.rs\n│   ├── style.rs\n│   ├── tui/\n│   └── watch.rs\n├── tests/\n│   ├── cgroup_acceptance.rs\n│   ├── cli.rs\n│   ├── cpu_acceptance.rs\n│   ├── io_acceptance.rs\n│   ├── mcp.rs\n│   ├── memory_acceptance.rs\n│   └── fixtures/\n│       ├── cpu/\n│       └── proc-*\n└── docs/\n    ├── README.md\n    ├── install.md\n    ├── product.md\n    ├── architecture.md\n    ├── data-model.md\n    ├── telemetry.md\n    ├── inference-engine.md\n    ├── cli-ux.md\n    ├── security-privileges.md\n    ├── testing.md\n    ├── development.md\n    ├── codex-workflow.md\n    ├── experiments.md\n    ├── references.md\n    ├── roadmap.md\n    ├── status.md\n    ├── glossary.md\n    └── decisions/\n```\n\nStart with [`AGENTS.md`](AGENTS.md), then [`docs/README.md`](docs/README.md).\n\n## Privacy Policy\n\nStallhunt reads bounded local Linux telemetry and does not independently send\nit over the network. MCP clients may transmit tool results according to their\nown data policies. See the full [Stallhunt privacy policy](PRIVACY.md) for the\ndata, storage, sharing, retention, and contact disclosures.\n\n## License\n\nDual-licensed under [MIT](LICENSE-MIT) or [Apache-2.0](LICENSE-APACHE), at your option.\n\n## Current state\n\nFor the current milestone, implemented capabilities, validation, known limits,\nand the next recommended task, see [`docs/status.md`](docs/status.md). Planned\nsequencing remains in [`docs/roadmap.md`](docs/roadmap.md).\n",
  "bytes": 7301,
  "sha": "cba48282c765c19a4e7d112028134c39f50e5b8575c669d51be1033052c01cba",
  "repo_slug": "guillem/stallhunt",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_guillem_stallhunt_111b2437/readme"
}