agent-top

agent-top is a local, privacy-first terminal monitor for AI coding agents. Version 0.1 scans Linux /proc directly and recognizes Codex, Claude Code, Gemini CLI, Aider, Kimi CLI, configured generic agents, and trusted third-party providers. For Codex, it also reads the local state database to show every spawned subagent as its own row and preserve nested agent relationships.

It does not send telemetry or network requests and it cannot kill, suspend, or modify processes.

Requirements and installation

• Linux
• Node.js 24 or newer
• pnpm 10 for development

pnpm install
pnpm build
node dist/cli.js

After npm publication, run npx @hhuneidie/agent-top or install it globally with npm install --global @hhuneidie/agent-top and run agent-top.

Usage

agent-top [--config path] [--refresh ms] [--theme name] [--log-level level]
agent-top --version

The dashboard refreshes every second by default. CPU for an individual process follows htop semantics and may exceed 100% when it uses multiple cores; total system CPU remains between 0 and 100%. Metrics stay in memory for 15 minutes and are removed as soon as the pid:startTime process identity disappears.

Codex subagents are logical threads rather than separate operating-system processes. Only subagents whose latest lifecycle event is task_started are shown; completed or aborted threads disappear. They share the parent CLI's PID, CPU, and RAM, so those metric cells are marked shared. Their names, hierarchy, workspace, and lifecycle come from ~/.codex/state_*.sqlite and rollout metadata. No prompts or message contents are retained or displayed.

Each name has a resource indicator: a green ● when CPU or RAM usage is above zero, and a white ○ when both are zero.

The main table is ordered by project. Active subagents appear immediately below their parent session and are ordered alphabetically by name. User and command values remain available in the detail view rather than occupying table columns.

Keys:

• q or Ctrl+C: quit
• arrows, g, G: navigate
• Tab: switch list/tree
• Enter: process, Git, history, environment, and full descendant detail
• /: incremental search across visible text; Esc clears/closes
• f: cycle provider filter
• v: temporarily reveal environment values in the detail view

Environment names and redacted values are shown by default. Revealing them can expose secrets on screen; values are never copied into logs.

Configuration

Configuration is resolved in this order: --config, AGENT_TOP_CONFIG, $XDG_CONFIG_HOME/agent-top/config.yaml, then ~/.config/agent-top/config.yaml. CLI refresh, theme, and log-level flags override YAML. Paths beginning with ~/ are expanded where applicable.

See config.example.yaml for the complete top-level schema. Supported sections are refreshInterval, colors, aliases, providers, plugins, sorting, filters, theme, history, and logging. Invalid keys and values produce an actionable error instead of being ignored.

Aliases are normalized through real paths. When aliases overlap, the longest ancestor match wins. Naming precedence is provider name, alias, Git repository, then directory/executable.

Plugins

Plugins may be installed npm package names or local paths already present on disk; agent-top never downloads them. Add their specifiers under plugins.

import type { AgentTopPlugin } from '@hhuneidie/agent-top/plugin-api';

const plugin: AgentTopPlugin = {
  apiVersion: 1,
  name: 'my-agent-plugin',
  version: '1.0.0',
  createProvider() {
    return {
      name: 'My Agent',
      matches(process) {
        return process.executable.endsWith('/my-agent');
      },
      resolve(process) {
        return { name: 'My Agent', suggestedWorkspace: process.cwd };
      },
    };
  },
};

export default plugin;

Each external plugin runs in one persistent worker with request timeouts, controlled restarts, and a circuit breaker. This protects UI responsiveness and isolates crashes, but it is not a permission sandbox: plugins are trusted code and run with your user permissions. API versions other than 1 are rejected explicitly. apiVersion: 1 remains compatible throughout the 0.x series.

Privacy and logs

JSON Lines logs are written under $XDG_STATE_HOME/agent-top/ (or ~/.local/state/agent-top/) with mode 0600. They contain lifecycle errors, crashes, plugin events, and detected provider names. Commands, arguments, environment variables, tokens, and secrets are filtered out. There is no telemetry, daemon, persisted metrics, remote API, or marketplace.

Development

pnpm typecheck
pnpm lint
pnpm format:check
pnpm test:coverage
pnpm build
pnpm benchmark
pnpm smoke
pnpm pack

The core depends on ports for process scanning, workspace/Git lookup, metrics, plugins, logging, and rendering. Neo-Blessed is contained behind DashboardRenderer, leaving room for another renderer. A future macOS ProcessSource can reuse the core; macOS and Windows scanning are not implemented in v0.1.

Known limitations

• Linux only; /proc access restrictions can produce partial rows.
• Process CPU needs two samples before it becomes non-zero.
• Git commands are cached and time-limited, but very large or unusual repositories can initially resolve slowly.
• Plugin workers isolate failures, not permissions.

Licensed under Apache-2.0.