claude-scope

Real-time statusline for Claude Code CLI

Track context, cost, git, docker, and more — right in your terminal

Quick Start · Features · Themes · Configuration · Docs

🚀 Quick Start

npx -y claude-scope@latest install

This single command:

1. ✅ Adds statusLine to ~/.claude/settings.json
2. ✅ Opens interactive configurator to choose layout, theme, and style

Restart Claude Code — done!

💡 Why claude-scope?

claude-scope transforms your Claude Code CLI into a powerful command center. See everything you need at a glance:

| What you get | Why it matters | |--------------|----------------| | 📊 Context usage | Know when you're running low before it's too late | | 💰 Session cost | Track spending in real-time | | 🔀 Git status | Branch, changes, tags — no switching windows | | 🐳 Docker containers | Monitor your stack without leaving the terminal | | 🔧 Active tools | See what Claude is doing right now | | 💻 System metrics | CPU, RAM, disk, network — all in one place |

✨ Highlights

• 🪶 Zero runtime dependencies — pure TypeScript, native Node.js only
• 🧩 15 customizable widgets — model, context, cost, git, docker, sysmon, and more
• 🎨 17 built-in themes — from Dracula to Nord to Cyberpunk
• 🎭 12 display styles — balanced, playful, compact, verbose, technical...
• 🤖 AI-friendly configuration — just ask Claude to customize it!
• ⚡ Instant setup — one command, works immediately

🧩 Features

Available Widgets

| Widget | Description | Example | |--------|-------------|---------| | model | Current Claude model | Opus 4.5 | | context | Context usage with progress bar | 42% [████████░░░░░░░░░] | | cost | Session cost | $33.05 | | duration | Session time | 2h 10m 20s | | lines | Lines added/removed | +382/-112 | | git | Branch and tracking | main...origin/main | | git-tag | Latest tag | v0.8.49 | | cache-metrics | Cache statistics | 81k cache | | config-count | Config files count | CLAUDE.md:1 │ MCPs:5 | | active-tools | Running/completed tools | Bash (1 running, 10 done) | | dev-server | Dev server status | ⚡ Nuxt (running) | | docker | Docker containers | Docker: 1 🟢 | | sysmon | System metrics | CPU 45% │ RAM 19GB │ Disk 2% | | poker | Easter egg | 🃏 A♠ K♠ | | cwd | Current directory | ~/projects/app |

📐 Layout Presets

| Preset | Lines | Best for | |--------|-------|----------| | Rich | 4 | Full information, large terminals | | Balanced | 2 | Most users, good balance | | Compact | 1 | Minimal footprint |

🎨 Themes

17 Built-in Themes

| Category | Themes | |----------|--------| | 🔥 Popular | dracula, tokyo-night, nord, monokai | | 💻 IDE | vscode-dark-plus, one-dark-pro, github-dark-dimmed | | 🌸 Pastel | catppuccin-mocha, rose-pine | | ⚡ Vibrant | cyberpunk-neon | | 👔 Professional | professional-blue, solarized-dark | | 🌫️ Minimal | gray, muted-gray, slate-blue, dusty-sage | | 🎯 Semantic | semantic-classic |

Switch themes instantly:

npx -y claude-scope@latest quick-config

⚙️ Configuration

🤖 /scope — AI-Powered Configuration

claude-scope includes a built-in Claude Code skill for effortless configuration. Just type /scope or ask naturally:

Use the /scope command:

/scope swap line 0 and line 1
/scope add docker widget to line 2
/scope change theme to dracula
/scope make all widgets compact

Or just ask Claude naturally:

"Move git widget to the first line"
"Switch to nord theme"
"Show me current config"
"Remove the cost widget"

The skill is installed automatically with the package — no setup required!

Changes apply instantly on the next status line update.

📝 Manual Configuration

Edit ~/.claude-scope/config.json directly:

{
  "version": "1.0.0",
  "$aiDocs": "https://github.com/YuriNachos/claude-scope/blob/main/AI-CONFIG-GUIDE.md",
  "lines": {
    "0": [
      { "id": "model", "style": "balanced", "colors": { ... } },
      { "id": "context", "style": "balanced", "colors": { ... } }
    ],
    "1": [
      { "id": "git", "style": "balanced", "colors": { ... } }
    ]
  }
}

See AI-CONFIG-GUIDE.md for complete reference.

📚 Documentation

| Topic | Description | |-------|-------------| | AI-CONFIG-GUIDE.md | Complete configuration reference for AI | | ARCHITECTURE.md | System architecture, data flow | | WIDGETS.md | All widgets, styles, examples | | THEME-SYSTEM.md | Theme system, customization | | CHANGELOG.md | Version history, roadmap |

📋 Requirements

• Node.js 18+
• Claude Code CLI

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

📄 License

MIT — use freely in your projects.

Made with ❤️ by YuriNachos

GitHub · Issues · npm

If you find claude-scope useful, consider giving it a ⭐