Sidekick CLI

Full-screen terminal dashboard for monitoring AI agent sessions — standalone, no VS Code required.

Sidekick CLI reads from ~/.config/sidekick/ — the same data files the VS Code extension writes. Browse sessions, tasks, decisions, knowledge notes, mind maps, and more in an interactive terminal UI.

Installation

Note: The npm package is sidekick-agent-hub, but the binary it installs is called sidekick.

npm install -g sidekick-agent-hub

Requires Node.js 20+.

Quick Start

1. cd into your project directory
2. Run sidekick dashboard
3. The dashboard auto-detects your project and session provider
4. Press ? to see all keybindings

OpenCode note: OpenCode session monitoring reads opencode.db and currently expects an executable sqlite3 runtime in the host environment.

OpenCode session data lives in OpenCode's platform-specific data directory:

• Linux: ~/.local/share/opencode/
• macOS: ~/Library/Application Support/opencode/
• Windows: %APPDATA%\\opencode\\

If sqlite3 is missing or not executable in the current shell environment, Sidekick prints an actionable OpenCode-specific notice instead of silently failing session detection.

Usage

sidekick dashboard [options]
sidekick tasks|decisions|notes|stats|quota|status|account|handoff|search|context [options]

The standalone commands open the dashboard directly to a specific panel or run a one-shot query. All accept --project and --provider flags.

| Flag | Description | |------|-------------| | --project <path> | Override project path (default: current working directory) | | --provider <id> | Session provider: claude-code, opencode, codex, or auto (default) | | --session <id> | Follow a specific session by ID | | --replay | Replay existing events from the beginning before streaming live |

Session Dump

sidekick dump [options]

Export session data as text, markdown, or JSON.

| Flag | Description | |------|-------------| | --format <fmt> | Output format: text (default), json, or markdown | | --width <cols> | Terminal width for text output (default: auto-detect) | | --expand | Show all events including noise | | --session <id> | Target a specific session (default: most recent) | | --list | List available sessions and exit |

Global flags --project and --provider also apply.

HTML Report

sidekick report [options]

Generate a self-contained HTML session report and open it in the default browser. Includes full transcript, token/cost stats, model breakdown, and tool-use summary.

| Flag | Description | |------|-------------| | --session <id> | Target a specific session (default: most recent) | | --output <path> | Write to a specific file (default: temp file) | | --theme <theme> | Color theme: dark (default) or light | | --no-open | Write the file without opening the browser | | --no-thinking | Omit thinking blocks from the transcript |

Global flags --project and --provider also apply.

You can also press r in the TUI dashboard to generate a report for the current session.

API Status

sidekick status

Check API health for both Claude (status.claude.com) and OpenAI (status.openai.com). Shows indicators with color coding (green/yellow/red), affected components, and active incident details. Use --json for machine-readable output. In the dashboard, provider-status surfaces are scoped to the monitored provider: Claude for Claude Code sessions, OpenAI for Codex sessions, and hidden for OpenCode.

When the active provider is claude-code, the output also includes a Claude Peak Hours block (see below).

Peak Hours

sidekick peak

Show whether Claude is currently in peak hours (weekdays 13:00–19:00 UTC — when session limits drain faster on Free/Pro/Max/Team subscriptions). Data comes from the public promoclock.co/api/status endpoint (third-party, unaffiliated with Anthropic). Use --json for machine-readable output. The peak-hours summary also appears under the bars in sidekick quota for Claude subscriptions.

Quota & Rate Limits

sidekick quota

Provider-aware quota and rate-limit display. The command auto-detects the active provider:

• Claude Code: Shows Claude Max subscription quota — 5-hour and 7-day windows with color-coded progress bars, projections, and reset countdowns. Includes a peak-hours summary line.
• Codex: Shows rate limits from Codex token_count.rate_limits events — primary and secondary windows with progress bars and reset countdowns. The default path is local-only: current workspace rollout, recent account-level rollouts, then the active account's cached snapshot. Add --refresh to explicitly refresh from Codex's usage API before falling back to local data.
• OpenCode: Prints an informational message (no rate-limit data available).

Subscription Quota
──────────────────────────────────────────────────
  5-Hour   ████████████░░░░░░░░░░░░░░░░░░ 40%   resets in 2h 15m
  7-Day    ██████████████████████░░░░░░░░ 72%   resets in 4d 6h

When quota data is unavailable, sidekick quota shows structured auth, rate-limit, network, server, or unexpected-failure messaging instead of a generic raw error. The dashboard Sessions panel also keeps a compact inline quota/rate-limit state visible instead of hiding the section entirely.

Use --json for machine-readable output. Use --provider codex to explicitly check Codex rate limits, and --refresh to opt in to a Codex usage API refresh. Claude Code requires active credentials (read from the system Keychain on macOS, or ~/.claude/.credentials.json on Linux/Windows). JSON output includes failureKind, httpStatus, and retryAfterMs on unavailable responses.

When multi-account is enabled, sidekick quota shows the active account email above the quota bars.

Quota History

sidekick quota history

Renders a 13-week, GitHub-contributions-style heatmap of quota utilization for the current workspace. Each cell is one day; brightness encodes the peak utilization observed (· ░ ▒ ▓ █ → ≤0% / <25% / <50% / <75% / ≥75%). Days that hit available: false render as a red ×.

Claude  ·  13 weeks  ·  41 day(s) with samples
Sun ·░▒▒▓█░░░ ·░░·· ·▒▒
Mon ··▒▒▓█▒░· ·░░·· ·▒▓
…
Peak 92%  ·  Avg 38%  ·  Samples 612

Flags: --weeks <n> (1-26, default 13), --provider claude|codex (default both, stacked), --workspace <path> (default cwd). --json emits a { workspaceId, weeks, providers: { claude?, codex? }, generatedAt } payload — the same shape consumed by the VS Code dashboard's Quota History panel.

History is stored at ~/.config/sidekick/quota-history/<workspaceId>/<provider>.jsonl (mode 0600, 60-second debounce, 91-day retention). The workspace id is sha256(realpath)[0..16], so the same folder yields the same store whether sampled from the CLI or VS Code.

Account Management

sidekick account [options]

Manage accounts across providers — save, list, switch, and remove without manual login/logout cycles. Supports Claude Code and Codex profiles. Account data is stored in ~/.config/sidekick/accounts/ with strict file permissions and atomic writes with rollback on failure.

On first CLI startup, Sidekick auto-registers the active system Claude Code and Codex credentials as a "Default" account (when no saved account exists for that provider yet). Existing manually saved accounts are never overwritten — the flags below are only needed to add additional accounts or switch between them.

| Flag | Description | |------|-------------| | --provider <id> | Provider: claude-code (default) or codex | | --add | Save the currently signed-in account | | --label <name> | Label for the account (use with --add; required for Codex) | | --switch | Switch to the next saved account | | --switch-to <id> | Switch to a specific account by email, label, or ID | | --remove <id> | Remove a saved account by email, label, or ID |

With no flags, lists all saved accounts and marks the active one. Use --json for machine-readable output.

Dashboard Panels

The dashboard is a two-pane terminal UI. The left side shows a navigable list, the right side shows details for the selected item.

| # | Panel | Description | |---|-------|-------------| | 1 | Sessions | Browse recent sessions with detail tabs: Summary, Timeline, Mind Map, Tools, Files, Agents, AI Summary | | 2 | Tasks | View persisted tasks filtered by status | | 3 | Kanban | Task board with status columns | | 4 | Notes | Knowledge notes attached to files | | 5 | Decisions | Architectural decisions from sessions | | 6 | Plans | Discovered agent plans from ~/.claude/plans/ | | 7 | Events | Live event stream with type badges, timestamps, and keyword-highlighted summaries | | 8 | Charts | Tool frequency bars, event distribution, activity heatmap, and pattern analysis |

Layout Modes

Press z to cycle through layout modes:

| Mode | Description | |------|-------------| | Normal | Default two-pane split | | Expanded | Side list hidden, detail pane fills the screen | | Wide Side | Wider side list for longer item labels |

Keybindings

Navigation

| Key | Action | |-----|--------| | 1–8 | Switch panel | | Tab | Toggle focus between side list and detail pane | | j / ↓ | Next item (side) or scroll down (detail) | | k / ↑ | Previous item (side) or scroll up (detail) | | g | Jump to first item / scroll to top | | G | Jump to last item / scroll to bottom | | h / ← | Return focus to side list (from detail) | | Enter | Move focus to detail pane (from side list) |

Detail Tabs

| Key | Action | |-----|--------| | [ | Previous detail tab | | ] | Next detail tab |

Session Management

| Key | Action | |-----|--------| | p | Pin session (prevent auto-switching to newest) | | s | Switch to pending session | | f | Toggle session filter |

Session Panel — Mind Map Tab

| Key | Action | |-----|--------| | v | Cycle mind map view: tree → boxed → flow | | f | Cycle node filter: all → file → tool → task → subagent → command → plan → knowledge-note |

Session Panel — AI Summary Tab

| Key | Action | |-----|--------| | n | Generate / retry AI narrative |

General

| Key | Action | |-----|--------| | z | Cycle layout mode | | / | Open filter overlay (supports substring, fuzzy, regex, and date modes — Tab cycles modes) | | x | Open context menu for selected item | | ? | Show help | | r | Generate HTML report for the current session | | V | Show version / changelog | | q / Ctrl+C | Quit |

Mouse Support

The dashboard supports mouse input in terminals with SGR 1006 extended mouse encoding:

• Click side list items to select them
• Click panel tabs or detail tabs to switch
• Scroll wheel in either pane to navigate
• Click anywhere to dismiss overlays

Multi-Provider Support

Auto-detects the most recently active session provider:

• Claude Code — ~/.claude/projects/
• OpenCode — OpenCode's data directory: Linux ~/.local/share/opencode/, macOS ~/Library/Application Support/opencode/, Windows %APPDATA%\\opencode\\
• Codex — ~/.codex/

Override with --provider claude-code, --provider opencode, or --provider codex.

See Also

sidekick-shared — the shared data access library used by this CLI. Published as a standalone npm package for building custom tools on Sidekick session data — types, parsers, providers, event aggregation, model pricing, and more. Install with npm install sidekick-shared.

Sidekick Docker — the same TUI dashboard experience for Docker management. Monitor containers, Compose projects, images, and volumes from a keyboard-driven terminal. Install with npm install -g sidekick-docker.

Documentation

Full documentation at cesarandreslopez.github.io/sidekick-agent-hub.

License

MIT