Roadmap: agent coverage strategy beyond v0.1

[graykode]

Context

abtop v0.1 was intentionally scoped to Claude Code + Codex CLI, with Gemini/Cursor listed as Non-Goals in CLAUDE.md. Since then, the project has grown and several contributors have opened PRs adding support for additional agents:

• ✅ OpenCode — merged via feat: add OpenCode agent support #40
• 🟡 Gemini CLI — feat: add Gemini CLI session discovery and monitoring #41 (currently Draft, pending this decision)
• 🟡 Kiro CLI — feat: add kiro-cli session support #44 (currently Draft, pending this decision)

Evaluating each new agent ad-hoc isn't fair to contributors (they invest significant work before knowing whether it'll land) and isn't good for the project's long-term shape. Time to define a strategy.

Questions to answer

1. What's the inclusion bar? Criteria could include:

   • User base / popularity
   • Stability of the underlying data source (the agent's session files, DB, or API)
   • Maintenance cost — how often does the agent change its format?
   • Whether abtop's UI abstractions (context %, tokens, rate limits) meaningfully apply

2. Should core support more agents, or should there be a plugin mechanism?

   • Pros of in-tree: consistent UX, single binary, easy install
   • Pros of plugins: independent release cadence, lower core maintenance, community can add niche agents without approval
   • A plugin path via the existing AgentCollector trait may be feasible

3. What happens to the Non-Goals (v0.1) list in CLAUDE.md?

   • Update it to reflect whatever is decided
   • Decide whether abtop is moving to a v0.2 with broader scope, or staying focused

4. Release implications — each new agent is a new data source to keep working across CLI version changes. Need a realistic estimate of the maintenance tail.

Proposed next step

Spend some time looking at each pending PR (#41, #44) alongside merged #40, understand how much code surface each adds, and decide:

• Which agents to include in core
• Whether to add a plugin / external collector mechanism
• How to update CLAUDE.md Non-Goals accordingly
• Communicate the outcome on the pending PRs

Target: resolution within 1-2 weeks so contributors aren't blocked indefinitely.

Related

• feat: add OpenCode agent support #40 (merged)
• feat: add Gemini CLI session discovery and monitoring #41 (draft, Gemini)
• feat: add kiro-cli session support #44 (draft, Kiro)

[tbouquet]

Having gone through the OpenCode integration (#40), a few thoughts:

The real cost isn't writing the collector - it's maintaining it when the upstream agent changes its session format. Claude Code and Codex have been stable, OpenCode uses SQLite which is unlikely to break, but newer CLIs (Gemini, Kiro) are still iterating fast. I'd want to see at least a few months of format stability before committing to support.

For the plugin question - AgentCollector is already basically a plugin trait. The pragmatic path is probably keeping the main ones in-tree (Claude, Codex, OpenCode, maybe Gemini once it stabilizes) and adding cargo features so they're opt-in at compile time. External plugins via a subprocess protocol (binary outputs JSON on stdout, abtop polls it) would let anyone add their niche agent without touching Rust, but that's a bigger design effort.

One concrete criterion I'd add: the agent's metrics need to actually map to abtop's UI. If an agent doesn't expose token counts or context size, half the panels show zeros and the UX is worse than not supporting it at all.

Happy to help spec out the external collector protocol if that's the direction.

[tbouquet]

Performance architecture: replacing process spawns with native APIs

Following the work on #60 (replacing Codex's lsof with /proc/pid/fd on Linux), here's a broader proposal for reducing abtop's per-tick overhead as more agents are added.

Current cost per 2s tick

Spawn	What	Cost
ps -ww -eo pid,ppid,rss,%cpu,command	Process list	~500 syscalls, ~15ms
lsof -i -P -n -sTCP:LISTEN	Ports (every 5 ticks)	~400 syscalls, ~30ms
lsof -F pn -p{pid}	Codex JSONL discovery	~400 syscalls, ~10ms
git status --porcelain x N	Git stats (every 5 ticks)	~500 syscalls x N
sqlite3 -readonly -json	OpenCode (every tick)	~300 syscalls

Each new agent collector adds 1+ process spawn. At 10 agents this becomes 10+ fork+exec per tick.

For comparison, btop reads /proc directly and achieves the same data at ~100 syscalls total.

Proposed roadmap

Phase 1 - Linux /proc direct reads (no new deps)

• Codex lsof -> /proc/pid/fd (perf: replace lsof with /proc/pid/fd for Codex JSONL discovery #60)
• ps -> /proc/pid/stat + /proc/pid/cmdline direct reads (~60 lines)
• Port lsof -> /proc/net/tcp + /proc/pid/fd inode matching (~80 lines)
• Estimated reduction: -85% syscalls on Linux, macOS unchanged (lsof fallback)

Phase 2 - Cross-platform native APIs (new dep: libproc)

• Replace ps and lsof on both Linux and macOS with libproc crate
• libproc uses proc_pidinfo / proc_pidfdinfo on macOS (no spawn), /proc on Linux
• Eliminates ALL process spawns except git status
• Trade-off: adds a C FFI dependency, impacts build chain on macOS

Phase 3 - Event-driven discovery

• inotify (Linux) / FSEvents (macOS) to watch session directories
• Sessions appear instantly instead of polling every 2-10s
• Variable tick rate: 500ms when active, 5s when idle
• Eliminates ~80% of wasted polling when sessions are idle

Phase 4 - Replace git spawn

• git2 crate (libgit2 bindings) for in-process git status
• Removes the last remaining fork+exec from the hot path

Impact on AgentCollector trait

Phases 1-2 are transparent - SharedProcessData is populated differently but the trait interface stays the same. Phase 3 would require changing from synchronous collect() to an event/channel model.

Decision needed

The key question for the maintainer: is adding libproc (Phase 2) acceptable? It's the cleanest path to zero-spawn monitoring on both platforms, but it introduces a C FFI dependency. The alternative (Phase 1 only) gives most of the benefit on Linux with zero new deps.

Related: #58 (Claude PID discovery) would also benefit from /proc/pid/fd instead of the proposed lsof approach.

[tbouquet]

Phase 1 update: all three PRs are now submitted as a cascade:

• perf: replace lsof with /proc/pid/fd for Codex JSONL discovery #60 - Codex lsof -> /proc/pid/fd
• perf: replace ps spawn with /proc direct reads on Linux #61 - ps -> /proc/pid/stat + /proc/pid/cmdline (depends on perf: replace lsof with /proc/pid/fd for Codex JSONL discovery #60)
• perf: replace lsof ports with /proc/net/tcp parsing on Linux #62 - Port lsof -> /proc/net/tcp + inode matching (depends on perf: replace lsof with /proc/pid/fd for Codex JSONL discovery #60 + perf: replace ps spawn with /proc direct reads on Linux #61)

Combined result on Linux: ~1500 syscalls/~50ms per tick reduced to ~200 syscalls/~5ms. Zero fork+exec for process list, ports, and Codex discovery. macOS fallbacks preserved.

Also introduces scan_proc_fds(pid) shared helper in process.rs used by both #60 and #62.

[ptahdunbar]

Re: agent coverage — another concrete case: Pi (pi-coding-agent)

#63 adds Pi as a first-class collector (JSONL under ~/.pi/agent/sessions/…), UI labels, demo data, and docs. It also goes beyond “parse files on disk” with idle-session recovery (lsof + cwd → newest JSONL) and pending sessions before the first assistant write lands—i.e. real product work tied to how Pi behaves, not only a new file format.

[tbouquet]

Recommendation: feature flags now, plugin protocol later

After analyzing the options (dynamic linking, IPC, WASM, scripts, feature flags), here's a phased proposal.

Why not plugins today

• AgentSession has 25+ fields and is still evolving (effort, compaction_count, context_history all added recently). A stable plugin API requires a stable data model.
• SharedProcessData is the hard part. Collectors receive pre-fetched /proc tables, port maps, and children maps for free. External plugins would need to either duplicate this scanning or receive it via IPC - both add complexity for 6 agents.
• At 316 stars and 6 agents, the bottleneck is review bandwidth, not architecture.

Phase 1: cargo feature flags (unblocks contributors today)

Each collector behind a feature flag, all enabled by default:

[features]
default = ["claude", "codex", "opencode", "pi", "gemini", "kiro"]
claude = []
codex = []

#[cfg(feature = "pi")]
pub mod pi;

// In MultiCollector::new():
#[cfg(feature = "pi")]
collectors.push(Box::new(PiCollector::new()));

Contributor workflow: PR adds src/collector/agent.rs + one mod line + one feature in Cargo.toml. No other files touched.

User workflow: cargo install abtop gets everything. cargo install abtop --no-default-features --features claude,codex for a slim build.

This is ~30 lines of changes and unblocks #41, #44, #63 immediately.

Phase 2: external plugin protocol (when needed, ~10+ agents)

Stdout JSONL protocol - plugin is any executable that outputs one JSON object per session per tick. abtop spawns and reads it. Any language works. Config in ~/.config/abtop/plugins.toml. Core agents (Claude, Codex) stay in-tree. Niche agents become external.

This can be designed and built independently of Phase 1 since feature flags are purely additive.

What this means for pending PRs

If feature flags are adopted, the inclusion bar becomes: does the collector follow existing patterns, pass CI, and have tests? Each feature is opt-out for users who don't want it. The maintenance cost is bounded because format breakage is caught by CI and only affects users who enabled that feature.