GO — Healthy across the board

• Last commit 3d ago
• 7 active contributors
• Distributed ownership (top contributor 41% of recent commits)
• MIT licensed
• CI configured
• ⚠ No test directory detected

_{Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests}

procs is a modern Rust-based replacement for the Unix ps command that displays running processes with colored, human-readable output, multi-column keyword search, and advanced features like Docker container names, TCP/UDP port tracking, I/O throughput, and tree-view process hierarchies. It runs on Linux, macOS, Windows, and FreeBSD, automatically detecting terminal themes and supporting watch mode for real-time monitoring. Single Rust binary organized as a modular column system: src/columns/ contains ~50 specialized column type implementations (arch.rs, docker.rs, cpu_time.rs, etc.), src/column.rs and src/columns.rs orchestrate them, with build.rs handling version/man page generation. No monorepo; config/ holds theme presets (large.toml, small.toml).

Systems administrators and developers who run ps or top regularly on Linux/Unix systems and want richer process information (ports, Docker containers, I/O metrics) with better UX—particularly those working in containerized or multi-process environments where the standard ps output is insufficient.

Production-ready and actively maintained: v0.14.11 (released recently), available via Homebrew, Arch, Fedora, snapcraft, and cargo with multi-platform CI/CD (GitHub Actions workflows for regression, release, winget, dependabot automation). Single maintainer (dalance) but with established release infrastructure and wide packaging distribution.

Low risk for stability but single-maintainer project with optional dependencies (dockworker + tokio for Docker support, feature-gated). Risk: if maintainer steps back, community adoption is moderate; requires libc bindings for platform-specific /proc parsing, so changes to Linux /proc format could require updates. No visible breaking changes in recent history.

Active maintenance with dependabot-driven updates (dependabot_merge.yml workflow auto-merges patches), periodic regression testing, release automation, and winget distribution support. Recent work appears focused on dependency updates and platform stability rather than major feature additions.

git clone https://github.com/dalance/procs.git
cd procs
cargo build --release
./target/release/procs

Or install via your package manager: brew install procs, sudo pacman -S procs, cargo install procs.

Daily commands:

cargo build
cargo run -- --help
cargo run -- ps           # show all processes
cargo run -- -p 1234      # filter by PID
cargo run -- --watch      # watch mode (like top)

See Makefile for test/lint targets: make test, make check.

• src/columns.rs: Central registry and orchestrator for all 50+ column types; defines which columns are available and how they're instantiated
• src/column.rs: Core Column trait definition that all metric columns (docker.rs, cpu_time.rs, etc.) implement; handles rendering, sorting, filtering
• src/columns/docker.rs: Optional Docker container name resolution via dockworker API; demonstrates async feature-gated code
• build.rs: Build script that generates man page (man/procs.1.adoc) and embeds version info at compile time
• src/main.rs: Entry point with clap argument parsing, watch/pager/tree mode logic, and multi-platform initialization
• Cargo.toml: Feature flags (docker enabled by default), MSRV 1.88, release automation metadata

To add a new process column metric: create src/columns/your_metric.rs implementing the Column trait (see src/columns/cpu_time.rs as template), register in src/columns.rs. To change output formatting: edit src/column.rs and theme logic. To support a new platform: add conditional compilation blocks in platform-specific parsing code (grep for #[cfg(target_os)]). To fix Docker integration: see src/columns/docker.rs and the dockworker crate integration.

Platform-specific gotchas: Linux /proc filesystem parsing assumes Linux 5.x+ format; macOS and FreeBSD support is experimental and may lag behind Linux features. Docker feature: requires daemon socket access (/var/run/docker.sock on Unix or Docker Desktop named pipe on Windows); Docker column silently fails if socket unavailable—no error message. Watch mode: uses getch 0.3 which may hang on some terminal emulators; tested mainly on Linux. Config files: search path is $XDG_CONFIG_HOME/procs/ (or ~/.config/procs/ on Linux), ~/Library/Application Support/procs/ on macOS; config must be TOML matching schema in config/large.toml. Rust edition 2024: requires rustc 1.88+, not 2021 edition.

• /proc filesystem pseudo-filesystem — procs reads /proc/[pid]/ on Linux for CPU, memory, I/O, cgroup data; understanding /proc structure is essential for adding columns or debugging platform-specific issues
• Feature gating (Cargo features) — Docker support is optional via docker feature flag (enabled by default, gated with dockworker + tokio); understanding Rust's feature system is critical for maintaining platform-specific code without bloat
• Terminal capability detection (ANSI colors, themes) — procs uses termbg 0.6 to auto-detect terminal background (dark/light) and adjust color schemes accordingly; essential for readable colored output across heterogeneous terminals
• Trait-based polymorphism (Column trait) — All 50+ column implementations share a common Column trait in src/column.rs allowing dynamic dispatch; central design pattern for extensibility without enum explosion
• Docker API socket communication — The dockworker crate handles async HTTP over Unix socket (/var/run/docker.sock) to fetch container metadata; optional but enables Docker container name resolution without spawning docker CLI
• Conditional compilation (#[cfg]) — Platform-specific code (Linux /proc vs. macOS /libproc vs. Windows API) uses cfg attributes; critical for maintaining cross-platform codebase without runtime overhead
• Pager interaction (minus crate) — procs pipes output to minus 5.6 with search support; understanding terminal pager protocols matters for output formatting and interactive features

• BenJeau/sysinfo — Cross-platform system information library (processes, CPU, memory) often used to build process tools; complementary to procs' UI focus
• sharkdp/bat — Rust CLI replacing cat with syntax highlighting; same ethos of 'modern replacement for Unix tools' with similar terminal UX polish (colors, paging)
• google/procfs — Go library for /proc filesystem parsing; procs uses similar hand-coded logic in Rust, so relevant for cross-language process monitoring patterns
• nicolargo/glances — Python cross-platform system monitoring (alternative to top/htop); procs' watch mode competes with glances' real-time features
• atoptool/atop — C-based advanced performance monitoring tool; procs' I/O throughput and Docker integration aim to cover overlapping use cases

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for column implementations in src/columns/

The repo has 40+ column type implementations (arch.rs, docker.rs, cgroup.rs, etc.) but there are no visible test files for these core modules. Each column module parses and formats process data, making them critical for correctness. Adding targeted tests would catch regressions early and document expected behavior for each column type.

• [ ] Create src/columns/tests/ directory with test modules
• [ ] Add unit tests for at least 5 high-value columns: docker.rs, cgroup.rs, env.rs, command.rs, and cpu_time.rs
• [ ] Test edge cases: empty values, special characters, multi-slot scenarios (see multi_slot.rs)
• [ ] Add integration tests in tests/ directory that verify column output formatting across different process states
• [ ] Update CI workflow in .github/workflows/regression.yml to ensure tests run on all platforms (Linux, macOS, FreeBSD, Windows)

Implement macOS and FreeBSD column parity documentation with tests

The codebase has OS-specific implementations (os_macos.rs, os_freebsd.rs, os_linux.rs, os_windows.rs) but the README only documents Linux/Docker features. There's no test coverage visible for platform-specific columns. This creates risk that macOS/FreeBSD functionality silently breaks. Document which columns are available per-platform and add platform-specific regression tests.

• [ ] Create a PLATFORMS.md document listing which columns work on each OS (Linux, macOS, FreeBSD, Windows)
• [ ] Review src/columns/os_*.rs files and add #[cfg(target_os = "...")] test cases for platform-specific columns
• [ ] Add GitHub Actions workflow (.github/workflows/platform_parity.yml) to test on macOS and FreeBSD (leverage cross-compilation)
• [ ] Document any columns that have different behavior per-platform (e.g., policy.rs, rt_priority.rs)

Add configuration schema validation and example configs with tests

The config/ directory has large.toml and small.toml but no schema documentation, JSON schema file, or validation tests. Users cannot easily understand valid configuration options. The Cargo.toml shows toml is a dependency but there's no visible validation logic. Adding schema validation would prevent silent config failures and improve UX.

• [ ] Create CONFIG_SCHEMA.md documenting all valid top-level keys and column configuration options with examples
• [ ] Add src/config_validation.rs module with struct-based schema validation using serde
• [ ] Create tests/config_integration_tests.rs with tests for: valid configs (large.toml, small.toml), invalid configs (bad column names, missing required fields), and edge cases
• [ ] Add a --validate-config flag to the CLI (modify src/main.rs and clap args) for users to test configs before use
• [ ] Update README.md Configuration section with examples and link to CONFIG_SCHEMA.md

• Add a new column type for tracking process CPU affinity (cpuset.rs) following the pattern in src/columns/cpu_time.rs—would require reading from /proc/[pid]/status CPU_affinity_list on Linux
• Expand Windows support by implementing memory page fault counters (src/columns/maj_flt.rs currently Linux-only) using Windows API via winapi or windows crate
• Add integration tests in tests/ directory that validate column output correctness across platforms—currently no visible test directory in repo structure, only CI regression workflows

The procs codebase demonstrates generally good security practices with minimal hardcoded secrets or injection risks visible in the file structure. The primary concerns are configuration issues in Cargo.toml: an incomplete dependency declaration, use of non-existent Rust edition/version identifiers, and limited documentation of security implications for optional Docker features. The codebase appears well-maintained with CI/CD workflows and dependency management via Dependabot. No obvious SQL injection, XSS, or credential exposure risks were identified in the provided file structure. Fixing the Cargo.toml configuration issues would improve the score to 90+.

• Medium · Incomplete Dependency Declaration in Cargo.toml — Cargo.toml (dependencies section). The toml dependency is declared in Cargo.toml without a version specifier. This is truncated and incomplete in the provided file. Without a version constraint, this could lead to unpredictable builds if the dependency maintainer introduces breaking changes or security issues. Fix: Specify a complete version constraint for the toml dependency, e.g., toml = "0.8" with appropriate semantic versioning constraints.
• Medium · Edition 2024 Not Yet Stable — Cargo.toml (package.edition). The Cargo.toml specifies edition = "2024", which is not a stable/released Rust edition as of current knowledge. Valid editions are 2015, 2018, and 2021. This may cause build failures or undefined behavior. Fix: Use a stable edition like edition = "2021" instead of edition = "2024".
• Low · Outdated Rust Version Requirement — Cargo.toml (rust-version). The package specifies rust-version = "1.88", which appears to be a future or non-existent version. Current stable Rust versions are significantly lower. This may indicate a typo or misconfiguration that could prevent users from building the package. Fix: Verify and update the rust-version to match actual stable Rust versions (e.g., 1.70 or similar). Document the minimum supported Rust version (MSRV) accurately.
• Low · Optional Dependencies Without Clear Security Boundaries — Cargo.toml (features section, dockworker dependency). The docker feature enables dockworker and tokio dependencies which interact with Docker APIs. While optional, there's no clear documentation about security implications of enabling this feature, such as Docker socket access controls. Fix: Document security considerations for the docker feature, including required permissions and potential attack surface when enabled. Consider adding security warnings in README.
• Low · Deprecated chrono Configuration — Cargo.toml (chrono dependency). The chrono dependency is configured with default-features = false but only enables clock feature. While this reduces attack surface, ensure that the minimal feature set doesn't introduce time-related security issues. Fix: Regularly audit chrono for security updates. Consider documenting why default features were disabled and which specific security concerns this addresses.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/dalance/procs shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live dalance/procs repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/dalance/procs.

What it runs against: a local clone of dalance/procs — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in dalance/procs | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | Last commit ≤ 33 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of dalance/procs. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/dalance/procs.git
#   cd procs
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of dalance/procs and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "dalance/procs(\\.git)?\\b" \\
  && ok "origin remote is dalance/procs" \\
  || miss "origin remote is not dalance/procs (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 33 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~3d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/dalance/procs"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.