Sidekick CLI¶

The Sidekick CLI provides a full-screen terminal dashboard for monitoring agent sessions — standalone, no VS Code required. It reads from the same ~/.config/sidekick/ data files the VS Code extension writes.

Installation¶

npm install -g sidekick-agent-hub

Requires Node.js 20+.

Or build from source:

bash scripts/build-all.sh

This compiles sidekick-shared (the data access library) and sidekick-cli (the binary). The CLI is output to sidekick-cli/dist/sidekick-cli.mjs.

Quick Start¶

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

If you have sessions from multiple providers, the most recently active one is selected automatically. Override with --provider.

Command Reference¶

sidekick dashboard [options]

Examples¶

# Launch for the current directory
sidekick dashboard

# Monitor a specific project
sidekick dashboard --project ~/code/my-app

# Force Claude Code as the provider
sidekick dashboard --provider claude-code

# Follow a specific session with full replay
sidekick dashboard --session abc123 --replay

Session Dump¶

sidekick dump [options]

Dump session data as a text timeline, JSON metrics, or markdown report for sharing or archiving.

Global flags --project, --provider, and --json also apply (see above).

Examples¶

# Dump the latest session as plain text
sidekick dump

# Export as markdown for sharing
sidekick dump --format markdown > session-report.md

# Full JSON export for tooling
sidekick dump --format json > session.json

HTML Report¶

sidekick report [options]

Generate a self-contained HTML session report and open it in the default browser. Includes full transcript with collapsible thinking blocks and tool detail, token/cost stats, model breakdown, and tool-use summary — zero external dependencies.

Global flags --project and --provider also apply (see above).

Examples¶

# Generate report for the latest session and open in browser
sidekick report

# Light theme, save to a specific file
sidekick report --theme light --output ~/reports/session.html

# Generate without opening browser
sidekick report --no-open --output session.html

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

Data Commands¶

Standalone commands that query Sidekick's persisted project data without launching the TUI dashboard. All accept the global flags --project, --provider, and --json.

Tasks¶

sidekick tasks [options]

List persisted tasks for the current project. Tasks carry over across sessions from ~/.config/sidekick/tasks/.

Examples¶

# List all tasks
sidekick tasks

# Show only pending tasks
sidekick tasks --status pending

# JSON output for scripting
sidekick tasks --json

Decisions¶

sidekick decisions [options]

List architectural decisions extracted from sessions. Stored in ~/.config/sidekick/decisions/.

Examples¶

# List all decisions
sidekick decisions

# Search for decisions about database choices
sidekick decisions --search "database"

# Show the 5 most recent decisions as JSON
sidekick decisions --limit 5 --json

Notes¶

sidekick notes [options]

List knowledge notes (gotchas, patterns, guidelines, tips) attached to files in the current project.

Examples¶

# List all notes
sidekick notes

# Show only gotchas
sidekick notes --type gotcha

# Notes for a specific file
sidekick notes --file src/services/AuthService.ts

# Active tips as JSON
sidekick notes --type tip --status active --json

Stats¶

sidekick stats [options]

Show historical usage statistics — tokens, costs, model breakdown, tool usage, and recent daily activity. Reads from ~/.config/sidekick/historical-data.json.

No command-specific flags. Use --json for machine-readable output.

Examples¶

# Print a formatted stats summary
sidekick stats

# Export raw historical data as JSON
sidekick stats --json

Status¶

sidekick status

Check API health for both Claude (status.claude.com) and OpenAI (status.openai.com). Shows indicator with color coding (green = operational, yellow = minor, red = major/critical), affected components, and active incident details with shortlink.

No command-specific flags. Use --json for machine-readable output.

Examples¶

# Check current API status
sidekick status

# Get raw status data as JSON
sidekick status --json

The dashboard also monitors status automatically, but only for the monitored provider — Claude for Claude Code sessions, OpenAI for Codex sessions, and no provider-status section for OpenCode. When degraded, the status bar shows a colored indicator and the Sessions panel Summary tab shows affected components and incident details.

Quota¶

sidekick quota

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

• Claude Code: Shows Claude Max subscription quota utilization — 5-hour and 7-day windows with color-coded progress bars, elapsed-time projections (e.g., 40% → 100%), and reset countdowns. Requires active Claude Code credentials (read from the system Keychain on macOS, or ~/.claude/.credentials.json on Linux/Windows). JSON output includes projectedFiveHour and projectedSevenDay fields.
• Codex: Shows rate limits extracted from the latest Codex session's token_count events — primary and secondary windows with progress bars and reset countdowns. Requires an active or recent Codex session.
• OpenCode: Prints an informational message — OpenCode does not provide rate-limit data.

When quota data is unavailable, the command emits structured failure output instead of relying on a generic error string. JSON responses can include failureKind, httpStatus, and retryAfterMs so callers can distinguish auth failures, rate limits, transient network/server failures, and unexpected responses. In the CLI dashboard, the Sessions panel keeps a compact inline quota/rate-limit state visible even when data is unavailable, and quota failure toasts only appear when the failure state changes.

No command-specific flags. Use --json for machine-readable output.

Examples¶

# Check current quota utilization (auto-detects provider)
sidekick quota

# Get raw quota data as JSON
sidekick quota --json

# Explicitly check Codex rate limits
sidekick --provider codex quota

Account¶

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 no flags, lists all saved accounts and marks the active one.

Examples¶

# List saved accounts (Claude Code, default)
sidekick account

# Save the current Claude Code account with a label
sidekick account --add --label Work

# Switch to the next account
sidekick account --switch

# Switch to a specific account
sidekick account --switch-to personal@gmail.com

# Remove an account
sidekick account --remove old@example.com

# Codex profile management
sidekick account --provider codex                    # list Codex accounts
sidekick account --provider codex --add --label Dev  # prepare profile + login
sidekick account --provider codex --switch-to Dev    # switch by label, email, or ID
sidekick account --provider codex --remove Dev       # remove a profile

# JSON output for scripting
sidekick account --json

Handoff¶

sidekick handoff [options]

Show the latest session handoff document for the current project. Handoff documents are continuity notes left by an agent at the end of a session.

No command-specific flags. Use --json for machine-readable output.

Examples¶

# Display the latest handoff
sidekick handoff

# Pipe handoff content into another tool
sidekick handoff --json | jq -r '.content'

Search¶

sidekick search <query> [options]

Full-text search across all sessions. Results include matched snippets with highlighted terms, event types, timestamps, and session/project paths.

Examples¶

# Search for mentions of a function
sidekick search "resolveModel"

# Limit results and output as JSON
sidekick search "database migration" --limit 10 --json

# Search within a specific project
sidekick search "auth bug" --project ~/code/my-app

Context¶

sidekick context [options]

Output composite project context — tasks, decisions, notes, handoff, stats, and recent sessions in a single document. Useful for piping into LLM prompts or other tools.

Examples¶

# Full context for the current project
sidekick context

# Compact summary for LLM prompts
sidekick context --fidelity compact

# Brief context as JSON
sidekick context --fidelity brief --json

Dashboard Overview¶

The dashboard is a two-pane Ink-based terminal UI. The left pane shows a navigable list of items (sessions, tasks, notes, etc.), and the right pane shows details for the selected item.

Layout Modes¶

Press z to cycle through three layout modes:

Minimum terminal size: 60 columns wide, 15 rows tall.

Dashboard Panels¶

Switch panels with number keys 1–8.

Sessions (1)¶

Browse and select from recent agent sessions. The detail pane has seven tabs:

Tasks (2)¶

View persisted tasks filtered by status. Tasks carry over across sessions from ~/.config/sidekick/tasks/.

Kanban (3)¶

Task board with status columns — a visual view of the same task data.

Notes (4)¶

Knowledge notes attached to files. Each note has Content and Related detail tabs. Notes persist in ~/.config/sidekick/ and can be injected into agent instruction files.

Decisions (5)¶

Architectural decisions extracted from sessions. Stored in ~/.config/sidekick/decisions/.

Plans (6)¶

Discovered agent plans from ~/.claude/plans/. Shows plan steps with completion status. Plans are matched to the current session via slug cross-reference.

Events (7)¶

Live scrollable stream of session events. Each event shows a timestamp, colored type badge ([USR], [AST], [TOOL], [RES]), and keyword-highlighted summary text. Events are listed in reverse chronological order with auto-tailing.

The detail pane has two tabs:

Charts (8)¶

Session analytics visualized as ASCII charts. The side list shows a single "Session Analytics" item; the detail tabs contain the charts.

Keybindings¶

Navigation¶

Detail Tabs¶

Session Management¶

Session Panel — Mind Map Tab¶

Session Panel — AI Summary Tab¶

Actions¶

General¶

Mouse Support¶

The dashboard supports mouse input in terminals with SGR 1006 extended mouse encoding (most modern terminals):

• Click side list items to select them
• Click panel tabs or detail tabs to switch
• Scroll wheel in either pane to navigate (scrolls 3 items/lines at a time)
• Click anywhere to dismiss overlays (help, filter, context menu)

Session Management¶

Auto-Detection¶

The CLI auto-detects which session provider is most recently active by checking filesystem presence and modification times:

• 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.

For OpenCode, the CLI reads opencode.db via sqlite3. If sqlite3 is missing or not executable in the current shell environment, the dashboard now prints an actionable OpenCode-specific notice.

Session Pinning¶

By default, the dashboard auto-switches to the newest session when one starts. Press p to pin the current session — the dashboard stays on it even when new sessions appear. Press s to switch to a pending session that arrived while pinned.

Session Filter¶

Press f to toggle session filtering, which limits the side list to items from the currently selected session. Useful when you have many sessions and want to focus on one.

Shared Data Layer¶

The CLI reads from the same ~/.config/sidekick/ directory as the VS Code extension:

Any data written by the VS Code extension is immediately visible in the CLI, and vice versa.

VS Code Integration¶

The VS Code extension provides a command to launch the dashboard without leaving the editor:

• Sidekick: Open CLI Dashboard — opens the TUI dashboard in an integrated terminal panel