Real-time monitoring dashboard for Claude Code developer sessions. Track what your team is building, catch stuck sessions, and understand how AI-assisted development is being used across your organization.
devscope.sh — try the hosted version, no setup required.
- Live activity feed — see every tool call, prompt, and agent action as it happens
- Session topology — visualize agent hierarchies and session flow in real time
- Team insights — compare developer activity, track velocity, and spot patterns
- Stuck session alerts — get notified when a session stalls or loops
- AI-powered reports — executive summaries for engineering leads (CEO, CTO, manager views)
- Multi-tenant — org-scoped teams with invite-based onboarding
- Cloud or self-hosted — use devscope.sh or deploy with Docker
The fastest way to get started — no server to manage.
- Sign up at devscope.sh
- Create a team and generate an API key
- Install the plugin:
curl -fsSL https://raw.githubusercontent.com/DowLucas/devscope-plugin/main/install.sh | bashSelect https://devscope.sh when prompted and enter your API key. That's it.
For teams that want full control over their data.
Prerequisites: Docker with Compose
git clone https://github.com/DowLucas/devscope.git
cd devscope
# 1. Copy the env template
cp .env.production.example .envEdit .env and set at minimum:
BETTER_AUTH_SECRET=<openssl rand -base64 32>
POSTGRES_PASSWORD=<openssl rand -base64 32>
BETTER_AUTH_URL=https://your-domain.com
DOMAIN=your-domain.com
GC_CORS_ORIGIN=https://your-domain.com
# Optional — seed admin account on first startup
DEVSCOPE_ADMIN_EMAIL=admin@your-domain.com
DEVSCOPE_ADMIN_PASSWORD=<strong-password>
DEVSCOPE_ADMIN_NAME=Admin# 2. Start the production stack (Caddy auto-TLS on :80/:443)
docker compose -f docker-compose.yml up --build -dAfter startup, open your domain and sign in with the admin credentials you set. Create an organization, generate an API key, then install the plugin (see below).
See .env.production.example for all configuration options including OAuth, email, and AI features.
curl -fsSL https://raw.githubusercontent.com/DowLucas/devscope-plugin/main/install.sh | bashOr via the marketplace:
claude plugin marketplace add DowLucas/devscope-plugin
claude plugin install devscopeThen run /devscope:setup inside Claude Code to configure your server URL and API key.
For contributors who want to hack on DevScope itself:
git clone https://github.com/DowLucas/devscope.git
cd devscope
bun install
# Start PostgreSQL + backend + dashboard with hot reload
docker compose up --build
# Or without Docker (requires local PostgreSQL)
export DATABASE_URL="postgres://user:pass@localhost:5432/devscope"
bun run dev- Backend runs on
http://localhost:6767 - Dashboard runs on
http://localhost:5173(proxies API/WS to backend) See CONTRIBUTING.md for full development guidelines.
┌─────────────────┐ POST /api/events ┌──────────────┐ WebSocket ┌───────────────┐
│ Claude Code │ ──────────────────────► │ Backend │ ──────────────► │ Dashboard │
│ Plugin (bash) │ │ (Hono/Bun) │ │ (React/Vite) │
└─────────────────┘ └──────┬───────┘ └───────────────┘
│
▼
┌──────────────┐
│ PostgreSQL │
└──────────────┘
| Package | Description |
|---|---|
packages/shared |
TypeScript types — the contract between all packages |
packages/backend |
Hono REST API + WebSocket server (Bun) |
packages/dashboard |
React 19 + Vite + TailwindCSS 4 + Zustand |
devscope-plugin |
Bash hooks for Claude Code (separate repo) |
The plugin reads configuration from (in priority order):
- Environment variables:
DEVSCOPE_URL,DEVSCOPE_API_KEY - Config file:
~/.config/devscope/config - Defaults:
http://localhost:6767
Required:
| Variable | Description |
|---|---|
BETTER_AUTH_SECRET |
Session signing secret — generate with openssl rand -base64 32 |
POSTGRES_PASSWORD |
PostgreSQL password (used by Docker Compose) |
Core (strongly recommended):
| Variable | Description | Default |
|---|---|---|
BETTER_AUTH_URL |
Public URL of the backend — used for OAuth callbacks and email links | http://localhost:6767 |
DOMAIN |
Domain for Caddy auto-TLS (Let's Encrypt) | localhost |
GC_CORS_ORIGIN |
Allowed CORS origins — must match your dashboard URL | http://localhost:5173 |
STALE_SESSION_TIMEOUT_MINUTES |
Auto-close sessions with no activity | 5 |
Admin seed account (created on first startup if no users exist):
| Variable | Description | Default |
|---|---|---|
DEVSCOPE_ADMIN_EMAIL |
Admin email address | — |
DEVSCOPE_ADMIN_PASSWORD |
Admin password | — |
DEVSCOPE_ADMIN_NAME |
Admin display name | Admin |
DEVSCOPE_ORG_NAME |
Default organization name | DevScope |
OAuth providers (optional — email/password login always works):
| Variable | Description |
|---|---|
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET |
Google OAuth app credentials |
GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET |
GitHub OAuth app credentials |
Email — Resend (optional — invite URLs logged to console if not set):
| Variable | Description |
|---|---|
RESEND_API_KEY |
Resend API key for invitation emails |
RESEND_FROM |
From address, e.g. DevScope <noreply@yourdomain.com> |
AI features — Google Gemini (optional):
| Variable | Description | Default |
|---|---|---|
GEMINI_API_KEY |
Google Gemini API key for AI insights and session titles | — |
AI_DAILY_TOKEN_BUDGET |
Max tokens per day across all AI calls | 1000000 |
AI_INSIGHT_SCHEDULE |
Hour (0–23 UTC) for daily AI insight job | 0 (midnight) |
SESSION_TITLE_INTERVAL_MINUTES |
How often to generate session titles | 3 |
PATTERN_ANALYSIS_SCHEDULE |
How often (hours) to run pattern analysis | 1 |
See .env.production.example for an annotated template.
| Endpoint | Method | Description |
|---|---|---|
/api/events |
POST | Ingest event from plugin |
/api/events/recent?limit=N |
GET | Recent events (default 50) |
/api/developers |
GET | All developers + active session counts |
/api/sessions |
GET | All sessions with event counts |
/api/sessions/active |
GET | Active sessions only |
/api/sessions/:id |
GET | Events for a session |
/api/health |
GET | Health check |
/ws |
WS | Real-time event stream |
Missing git identity — the plugin derives your developer ID from git config user.email. If it's not set, events can't be attributed:
git config --global user.email "you@example.com"
git config --global user.name "Your Name"Config not found — verify your config exists and has the right URL:
cat ~/.config/devscope/configServer unreachable — test the connection:
curl -sf https://devscope.sh/api/health # cloud
curl -sf http://localhost:6767/api/health # self-hosted- Check that the plugin is installed and enabled:
claude plugin list - Verify WebSocket connects (browser console should show
wsorwssconnection) - Ensure
GC_CORS_ORIGINincludes your dashboard URL (self-hosted only)
Claude Code caches plugins by version. After updating:
claude plugin update devscope
# Restart Claude Code for changes to take effectContributions are welcome! Whether it's bug reports, feature requests, or pull requests — we appreciate your help.
- Bug reports & feature requests: GitHub Issues
- Security vulnerabilities: See SECURITY.md
- Development setup & guidelines: See CONTRIBUTING.md
DevScope uses a dual license:
- PolyForm Shield 1.0.0 for the backend and dashboard (
packages/backend/,packages/dashboard/) — use it freely, but don't build a competing product - MIT for everything else (plugin, shared types, Docker config, docs) — do whatever you want
See LICENSE for full details.
