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/pranshuparmar/witr 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.

GO — Healthy across all four use cases

• Last commit 7w ago
• 10 active contributors
• Apache-2.0 licensed
• CI configured
• ⚠ Single-maintainer risk — top contributor 85% of recent commits
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

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

What it runs against: a local clone of pranshuparmar/witr — 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 pranshuparmar/witr | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 81 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of pranshuparmar/witr. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/pranshuparmar/witr.git
#   cd witr
#
# 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 pranshuparmar/witr and re-run."
  exit 2
fi

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

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

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

# 4. Critical files exist
test -f "cmd/witr/main.go" \\
  && ok "cmd/witr/main.go" \\
  || miss "missing critical file: cmd/witr/main.go"
test -f "internal/app/app.go" \\
  && ok "internal/app/app.go" \\
  || miss "missing critical file: internal/app/app.go"
test -f "internal/proc/process_linux.go" \\
  && ok "internal/proc/process_linux.go" \\
  || miss "missing critical file: internal/proc/process_linux.go"
test -f "internal/output/printer.go" \\
  && ok "internal/output/printer.go" \\
  || miss "missing critical file: internal/output/printer.go"
test -f "internal/pipeline/analyze.go" \\
  && ok "internal/pipeline/analyze.go" \\
  || miss "missing critical file: internal/pipeline/analyze.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 81 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~51d)"
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/pranshuparmar/witr"
  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).

witr is a CLI tool and interactive TUI dashboard that traces the causal chain of running processes, services, and port bindings across Linux, macOS, Windows, and FreeBSD. Rather than showing just what is running (like ps or top), it explicitly answers 'why is this running?' by reconstructing the complete ancestry, supervision layer, and system configuration responsible for a process's existence. Single-binary monolithic architecture: cmd/witr/main.go is the entry point, internal/app/app.go orchestrates core logic, internal/pipeline/analyze.go handles process ancestry analysis, and internal/output/* (json.go, tree.go, docker.go, etc.) handles 6+ output formatters. Platform-specific code is isolated in internal/launchd/ for macOS. The TUI layer is built on Charmbracelet's bubbles/bubbletea framework.

Systems administrators, DevOps engineers, and platform engineers who need to debug unexpected processes, understand service dependencies, investigate container startup chains, or trace why something is consuming system resources. Also useful for security-conscious users investigating unknown running processes.

Actively maintained and production-ready. The project has a mature release pipeline (goreleaser configuration, multi-platform builds, packaging across brew/conda/AUR/winget/npm), structured GitHub workflows for CI/CD (pr-check.yml, release.yml, e2e-tests.yml), and clean Go module structure on v1.25. Latest commits appear recent based on the active workflows directory. This is a stable, feature-complete tool with real-world distribution.

Low risk for production use. Single maintainer (pranshuparmar) is the primary concern—there are no visible indicators of a large contributor base. Dependency surface is minimal and focused (Charmbracelet TUI libraries, Cobra CLI framework, standard library heavy). No obvious breaking-change indicators. The main risk is that feature requests or critical bugs depend on one person's availability.

The project is in active development with focus on TUI improvements (evidenced by .agent/workflows/validate-pr-check.md), documentation updates (update-docs.yml workflow), and cross-platform testing (e2e-tests.yml). The recent addition of agent workflows suggests integration with automated validation. Multi-output format support (JSON, tree, short, docker, envonly, children) is being actively maintained.

Clone the repository: git clone https://github.com/pranshuparmar/witr.git && cd witr. Build locally: make build (Makefile present). Or install directly: go install ./cmd/witr@latest. Run: witr <pid> or witr --tui for interactive mode.

Daily commands: Development: make build outputs binary to ./dist/witr or go run ./cmd/witr <pid>. For TUI: go run ./cmd/witr --tui. For e2e testing: .github/workflows/e2e-tests.yml uses standard go test ./....

• cmd/witr/main.go — Entry point for the CLI application; all contributors must understand the command structure and initialization flow.
• internal/app/app.go — Core application logic that orchestrates process analysis; this is the heart of the witr tool's functionality.
• internal/proc/process_linux.go — Cross-platform process introspection is critical; Linux implementation is foundational for the analysis pipeline.
• internal/output/printer.go — Output formatting abstraction that all display modes depend on; changes here affect all output channels.
• internal/pipeline/analyze.go — Pipeline orchestration for data collection and transformation; defines how process information flows through analysis.
• go.mod — Declares dependencies on charmbracelet TUI libraries and cobra CLI framework; understanding these is essential for feature additions.
• .github/workflows/pr-check.yml — Defines CI validation across multiple platforms; contributors must ensure changes pass these checks.

Add a new output format

1. Create new printer implementation in internal/output/yourformat.go implementing the printer.Printer interface (internal/output/printer.go)
2. Register your printer type in app initialization logic (internal/app/app.go)
3. Add CLI flag to enable the format in cmd/witr/main.go (cmd/witr/main.go)

Add a new process attribute (e.g., new system metric)

1. Implement platform-specific data collection in internal/proc/resource_PLATFORM.go for each OS (internal/proc/resource_linux.go)
2. Update the common Process struct definition to include new field (internal/proc/command.go)
3. Add field to relevant output formatters to display the new attribute (internal/output/standard.go)

Add support for a new platform

1. Create process_PLATFORM.go in internal/proc/ implementing process list and info retrieval (internal/proc/process_linux.go)
2. Implement platform-specific boot time detection in internal/proc/boot_PLATFORM.go (internal/proc/boot_linux.go)
3. Add platform extended attributes files (net, fd, resource, socketstate, etc.) following existing patterns (internal/proc/net_linux.go)
4. Update .github/workflows/pr-check.yml to run tests on the new platform (.github/workflows/pr-check.yml)
5. Update .goreleaser.yml with new platform build target (.goreleaser.yml)

Add a new CLI command or flag

1. Define new cobra command or flag in cmd/witr/main.go with appropriate help text (cmd/witr/main.go)
2. Pass flag value through to internal/app/app.go configuration (internal/app/app.go)
3. Implement feature logic in the appropriate layer (usually internal/pipeline/ or internal/proc/) (internal/pipeline/analyze.go)

• Go 1.25 — Cross-platform compilation, native binary execution, and direct system API access without runtime overhead; critical for introspecting OS-level process details across Linux, macOS, Windows, FreeBSD.
• Cobra CLI framework — Structured command definition, automatic help generation, and flag parsing for a tool with multiple output modes and configuration options.
• Charmbracelet (bubbletea, bubbles, lipgloss) — Provides interactive TUI capabilities (terminal UI mode) and cross-platform terminal styling/color support for modern user experience.
• CGO (for libproc on macOS) — Enables access to macOS-specific system libraries (libproc) for detailed process introspection; conditional compilation avoids overhead on other platforms.
• /proc filesystem (Linux), kqueue (BSD), WMI/PEB (Windows) — Direct OS kernel interfaces provide authoritative process metadata without relying on third-party tools; most efficient and reliable data source per platform.

• Platform-specific implementations rather than abstraction layer

  • Why: Each OS provides fundamentally different APIs and data sources; unifying abstraction would hide platform capabilities and limit detail.
  • Consequence: More code duplication (process_linux.go, process_darwin.go, etc.) but maximum platform-specific feature richness; maintainers must test on all platforms.

• Multiple output modes (standard, JSON, tree, Docker, interactive) vs. single format

  • Why: Different use cases require different presentation (automation via JSON, human inspection via tree/interactive, container-aware output).
  • Consequence: Increased complexity in output layer; all formatting logic must be duplicated across modes, but users get optimized presentation per context.

• Interactive TUI mode using BubbleTea framework

  • Why: Provides rich interactive experience for exploration; distinguishes witr from static CLI tools like ps.
  • Consequence: Adds charmbracelet dependency and increases binary size; TUI development/debugging requires terminal emulation environment.

• Eager process introspection (collect all data upfront) vs. lazy on-demand collection

  • Why: Process tree changes rapidly
  • Consequence: undefined

Platform-specific behavior: process ancestry lookup differs significantly between Linux (procfs), macOS (launchd + plist), Windows (WMI), and FreeBSD (kqueue). The code uses build tags to handle this. TUI mode requires a TTY and terminal capability detection (handled by Charmbracelet internally, but may fail in CI environments). When running with elevated privileges, some process information becomes available that isn't accessible to unprivileged users—output differs accordingly. Docker output format requires the Docker socket to be accessible; fails silently if unavailable.

• Process Ancestry / Parent Chain Reconstruction — witr's core value proposition is reconstructing the causal chain from a running process back to its root cause (systemd, init, container runtime, etc.); you need to understand how PPID (parent process ID) lookup works across platforms and how supervisors break traditional parent-child links
• launchd and macOS Service Supervision — macOS uses launchd instead of systemd; witr includes internal/launchd/plist.go specifically to parse launchd property list configs and trace service dependencies; this is non-obvious compared to Linux
• procfs (Linux Process Filesystem) — On Linux, witr reads /proc/<pid>/ entries to extract process metadata, parent PIDs, and environment; understanding the structure of /proc/[pid]/status, /proc/[pid]/cgroup, and /proc/[pid]/environ is critical for understanding how the tool gathers data
• Pluggable Output Formatters / Strategy Pattern — witr has 6+ output formats (tree, JSON, docker, short, envonly, children) implemented as swappable strategies in internal/output/; the architecture pattern here is how you'd extend the tool for new output types
• Charmbracelet TUI Framework Stack — Interactive mode depends on bubbletea (Elm-inspired state machine for TUIs), bubbles (components), and lipgloss (styling); understanding the model-update-view loop is essential for TUI feature development
• Cgroups (Control Groups) — Linux process tracing via procfs includes cgroup membership; witr may need to read /proc/[pid]/cgroup to understand resource isolation and container boundaries, which is relevant for the docker output formatter
• Build Tags (Go Conditional Compilation) — witr uses Go build tags to include platform-specific code (e.g., //go:build darwin for macOS, //go:build linux for Linux); see cmd/witr/unsupported.go pattern; understanding this is essential for cross-platform contributions

• nicolaka/netshoot — Container debugging toolbox; often used alongside witr to investigate process chains inside Kubernetes pods and Docker containers
• google/gops — Go process inspector; alternative for introspecting running processes, but focused on Go binaries; witr is language-agnostic and shows system-wide causality
• sharkdp/bat — Charmbracelet ecosystem companion; similar philosophy of making CLI output prettier and more human-readable; authors use overlapping TUI frameworks
• mozilla/sccache — Related tool for understanding hidden process chains in build systems; both solve the 'why is this running?' problem in systems contexts
• charmbracelet/bubbletea — Direct dependency and framework underlying witr's TUI mode; understanding this is essential for extending interactive features

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 unit tests for internal/proc/container_detect.go

The container detection logic is critical for accurate process analysis, but container_detect.go lacks test coverage. Given that internal/proc/container_test.go exists but container_detect.go is not tested, and considering the multi-platform importance (Linux/Windows/Darwin detection patterns), adding comprehensive tests would prevent regressions and document expected behavior for container environment detection.

• [ ] Create test cases in internal/proc/container_detect_test.go for Docker, Kubernetes, and other container environment detection
• [ ] Add tests for edge cases like missing environment variables, malformed container IDs, and nested containers
• [ ] Test platform-specific paths (cgroup detection on Linux, Hyper-V detection on Windows)

Add integration tests for internal/launchd/plist.go (macOS-specific)

The launchd plist handling is macOS-specific and critical for launchd process analysis. Currently there's no test file for plist.go. Given that macOS is one of the supported platforms, adding tests would ensure launchd plist parsing works correctly and doesn't break with macOS updates.

• [ ] Create internal/launchd/plist_test.go with test fixtures for typical launchd plist structures
• [ ] Add tests for parsing agent and daemon plist files from ~/Library/LaunchAgents and /Library/LaunchDaemons
• [ ] Test edge cases like malformed plists, missing keys, and various property list formats

Add Windows-specific integration tests for internal/proc/boot_windows.go and cmdline_windows.go

While the repo supports Windows (visible in the file structure with boot_windows.go and cmdline_windows.go), there are no visible test files for Windows-specific process handling. This is a gap given that the codebase handles Windows process command lines and boot time detection, which differ significantly from Unix implementations.

• [ ] Create internal/proc/boot_windows_test.go and internal/proc/cmdline_windows_test.go with Windows-specific test cases
• [ ] Add tests for WMI-based boot time detection and Windows command line parsing (especially for quoted arguments and environment variables)
• [ ] Include CI workflow step to run Windows tests (consider adding Windows runner to .github/workflows/pr-check.yml if not present)

• Add test coverage for sanitize.go: internal/output/sanitize.go and sanitize_test.go exist but the test file is minimal; add comprehensive test cases for edge cases in environment variable and string sanitization used across all output formatters
• Expand docker.go output formatter: internal/output/docker.go is present but underutilized; add support for detecting and displaying container labels, image digests, and multi-container process groups for better container ancestry tracing
• Document TUI keybindings and modes: Interactive TUI mode is mentioned heavily in the README but docs/cli/witr.md likely lacks detailed keybinding documentation; audit the Charmbracelet bubbles integration in main.go and add comprehensive TUI interaction guide

The 'witr' codebase demonstrates generally good security practices with proper separation of concerns, platform-specific implementations, and responsive security policy. However, there are minor concerns: an unusual Go version specification (1.25), incomplete SECURITY.md documentation, platform support inconsistencies between documentation and code, and CGO usage on Darwin. No critical vulnerabilities or hardcoded secrets were detected. Dependencies are from reputable sources (charmbracelet, spf13). Recommend addressing the Go version specification and completing security documentation.

• Medium · Outdated Go Version — go.mod. The project specifies 'go 1.25' in go.mod, which appears to be a future or non-existent version. Current stable Go versions are 1.22.x or earlier. This may indicate a configuration error or inability to build/verify the project properly. Fix: Update go.mod to specify a stable, released Go version (e.g., 'go 1.22' or current LTS). Verify the project builds and passes tests with the specified version.
• Low · Windows Support Inconsistency — SECURITY.md and internal/proc/ directory. SECURITY.md indicates Windows is not supported (:x:), but the codebase includes Windows-specific implementations (boot_windows.go, cmdline_windows.go, children_windows.go, etc.). This creates confusion about actual Windows security support and potential untested code paths. Fix: Either: (1) Clearly document Windows support status and security testing, or (2) Remove Windows-specific code if unsupported. Update SECURITY.md to match actual support level.
• Low · Incomplete SECURITY.md — SECURITY.md. The SECURITY.md file appears truncated, ending abruptly with 'Any suggested mitigations or fixes. ## O'. This incomplete documentation may leave security guidance incomplete for contributors. Fix: Complete the SECURITY.md file with all security policy sections (acknowledgments, security best practices, etc.). Ensure the file is well-formed and complete.
• Low · CGO Usage in Darwin Build — internal/proc/libproc_darwin_cgo.go. The project uses CGO for Darwin (libproc_darwin_cgo.go) to call C library functions. CGO introduces complexity and potential memory safety issues if not carefully managed. Fix: Ensure CGO code is reviewed for memory leaks, buffer overflows, and proper error handling. Consider maintaining the CGO stub alternative for easier auditing. Document CGO security considerations.

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

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

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