Configuration

claude-dashboard is configured through a JSON file and the /claude-dashboard:setup command.

Setup Command

The fastest way to configure is via the setup command:

# Preset modes
/claude-dashboard:setup compact             # 1 line (default)
/claude-dashboard:setup normal en pro       # 2 lines, English, Pro plan
/claude-dashboard:setup detailed ko max     # 6 lines, Korean, Max plan

# Custom mode: control widget order and line composition
# Format: "widget1,widget2,...|widget3,widget4,..." (| separates lines)
/claude-dashboard:setup custom auto max "model,context,cost|projectInfo,todoProgress"

Running /claude-dashboard:setup without arguments launches interactive mode, which guides you through each option.

Plan Differences

Feature	Max	Pro
5h rate limit + countdown	Yes	Yes
7d all models	Yes	Yes

The 7-day Sonnet rate limit widget (rateLimit7dSonnet) is deprecated as of ~2026-06: at the Sonnet 5 launch Anthropic merged the separate Sonnet weekly limit into the unified all-models weekly bucket, so the usage API no longer returns a Sonnet-specific value and the widget stays hidden on all plans. Use rateLimit7d (available on both Pro and Max) for your unified weekly usage. The separate rateLimit7dFable widget remains active: it tracks a Fable-only weekly cap (Max plan) and appears only when your account has one, which the usage API exposes through its generic limits[] array.

Configuration File

The configuration is stored at ~/.claude/claude-dashboard.local.json. You can edit this file directly or use the setup command.

Full Example

{
  "language": "auto",
  "plan": "max",
  "displayMode": "custom",
  "lines": [
    ["model", "context", "cost", "rateLimit5h"],
    ["projectInfo", "todoProgress"]
  ],
  "theme": "default",
  "separator": "pipe",
  "dailyBudget": 15,
  "disabledWidgets": [],
  "cache": {
    "ttlSeconds": 300
  }
}

Preset Shorthand

For quick configuration, you can use a preset string instead of specifying lines manually:

{
  "preset": "MC$R|BDO",
  "theme": "tokyoNight",
  "separator": "dot"
}

When preset is set, it overrides displayMode with custom and generates the line layout from the shorthand string. See Preset Shortcuts for the character mapping.

Budget Tracking

Set a daily budget limit in USD to track your spending:

{
  "dailyBudget": 15
}

The budget widget shows daily spending versus your configured limit. Warning indicators appear at 80% usage and critical alerts at 95%.

Tag Status Patterns

The tagStatus widget shows commits ahead of each matched git tag. Configure which tags to track via tagPatterns:

{
  "tagPatterns": ["v*", "release-*"]
}

Each glob pattern resolves to at most one tag — the most recent one reachable from HEAD. The default is ["v*"]. The widget auto-hides when no pattern matches a reachable tag.

Widget Toggle

Add widget IDs to disabledWidgets to hide specific widgets from any display mode (including presets and custom layouts):

{
  "disabledWidgets": ["codexUsage", "geminiUsage"]
}

Empty lines that result from disabling widgets are automatically removed.

Color Legend

Widgets that show utilization percentages use a consistent color scheme:

• Green (0-50%): Safe range
• Yellow (51-80%): Warning range
• Red (81-100%): Critical range

This applies to context usage, rate limits, cache hit rate, budget utilization, and similar percentage-based widgets.