Skip to content

About

Claude Code plugin for DevScope — real-time developer session monitoring

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

DevScope Plugin

License: MIT Cloud GitHub

Claude Code plugin for DevScope — real-time developer session monitoring.

This plugin hooks into Claude Code lifecycle events (session start/end, tool use, prompts, agents, etc.) and sends them to a DevScope server for real-time visualization and team insights.

Quick Start

One-liner install:

curl -fsSL https://raw.githubusercontent.com/DowLucas/devscope-plugin/main/install.sh | bash

The interactive installer handles plugin installation, server selection, and connection testing.

Using the cloud? Select https://devscope.sh during setup — no server to run. Sign up at devscope.sh to get your API key.

Manual install:

# Add the marketplace (one-time)
claude plugin marketplace add DowLucas/devscope-plugin

# Install the plugin
claude plugin install devscope

Setup

Type /devscope:setup in Claude Code to interactively configure your server URL and API key.

Or manually create ~/.config/devscope/config:

mkdir -p ~/.config/devscope
cat > ~/.config/devscope/config <<EOF
DEVSCOPE_URL=https://devscope.sh
DEVSCOPE_API_KEY=your-api-key-here
EOF

Server Options

Option URL Description
Cloud (recommended) https://devscope.sh Hosted for you — sign up, get an API key, done
Self-hosted (Docker) https://your-domain.com Run your own instance with Docker
Local development http://localhost:6767 For contributors working on DevScope itself

Configuration

The plugin reads configuration in this priority order:

  1. Environment variables: DEVSCOPE_URL, DEVSCOPE_API_KEY
  2. Config file: ~/.config/devscope/config (or $XDG_CONFIG_HOME/devscope/config)
  3. Default: http://localhost:6767

Prerequisites

Privacy Modes

Control what data is sent to the server with the DEVSCOPE_PRIVACY setting in ~/.config/devscope/config:

Mode What's sent Use when
private Tool names, file paths, durations only Maximum privacy — no prompt or response content
standard Everything in private + prompt text + full tool inputs Default — good balance for team insights
open Everything in standard + Claude's response text Full session replay in the dashboard

Set your privacy mode:

# In ~/.config/devscope/config
DEVSCOPE_PRIVACY=standard   # default
DEVSCOPE_PRIVACY=private    # metadata only
DEVSCOPE_PRIVACY=open       # include response text

Or run /devscope:setup in Claude Code to reconfigure interactively.

Backwards compatibility: Old values redacted and full are automatically mapped to private and open respectively — no config changes needed.

"You've asked this before"

When you send a prompt that closely matches one from an earlier session of yours, Claude gets a short note on how it went last time: tool calls, failures, and how it ended. You see a one-line notice:

DevScope: you've asked this before (2026-09-12, 2026-09-03). Claude has the notes.

It only fires on strong matches (similarity 0.9 or higher, 4+ words, from your own sessions), so most prompts get nothing. From the third separate day, Claude may suggest turning the ask into a skill. It waits at most 2 seconds and never runs in private mode.

# In ~/.config/devscope/config
DEVSCOPE_PREFLIGHT=off   # turn it off (default: on)

Requires a DevScope server with semantic retrieval enabled.

"You've hit this error before"

When a tool call fails with an error close to one from an earlier session of yours, Claude gets the past occurrences: whether the same tool succeeded soon after, and how Claude's reply ended that time. That is often the fix. You see one line:

DevScope: you've hit this error before (2x, 1 resolved). Claude has the notes.

Paths, ids and long numbers are masked before matching, so the same failure in another file or run still matches. It asks once per distinct error per session (a retry loop costs one lookup), waits at most 2 seconds, and never runs in private mode.

# In ~/.config/devscope/config
DEVSCOPE_ERROR_RECALL=off   # turn it off (default: on)

Requires a DevScope server with semantic retrieval enabled.

Next-step hints

DevScope noticed that opening a pull request is the strongest signal that a code review comes next. After Claude opens a PR with gh pr create, the plugin shows you one line:

DevScope: PR opened. Review it next with /code-review?

The same goes for skills: DevScope learns which skill you usually run after another (from your own history: seen 3+ times, and at least a quarter of the time) and hints it after the first one runs:

DevScope: after /ship you usually run /code-review next.

By default hints are only shown to you. With DEVSCOPE_HINTS=claude, Claude sees them too and offers the step at the end of its reply ("Want me to run /code-review on it?"). Either way nothing runs until you agree. Each hint appears once per PR or skill per session and uses no network on the tool call: your skill sequences are fetched at session start (at most every 6 hours) and cached in ~/.cache/devscope/skill-chains.json.

# In ~/.config/devscope/config (environment variables take precedence)
DEVSCOPE_HINTS=on                    # default: shown to you only
DEVSCOPE_HINTS=claude                # also tell Claude, which offers the next step
DEVSCOPE_HINTS=off                   # no hints
DEVSCOPE_HINT_AFTER_PR=/review-pr    # suggest a different command (default: /code-review)

New model check

The first time you use a model (at session start or after /model), DevScope shows DevScope: first time on <model>. and asks Claude to offer, in one question, to check your CLAUDE.md and memory files for instructions about model selection and usage, such as rules that name an older model, and update them. Nothing is read or changed unless you say yes. Models already seen are listed in ~/.cache/devscope/models-seen; the model you are on when the plugin first runs counts as seen. A model.first_use event appears in the dashboard's live feed. DEVSCOPE_HINTS=off turns the question off.

Token usage and cost

DevScope shows each session's tokens and its API-equivalent cost: what those tokens would cost at Anthropic's API list prices, which is not what a Claude subscription plan charges you. The Stop and SessionEnd hooks sum every API call in the session transcript and its subagent transcripts, per model, and send the totals. Only token counts and model ids are sent, never transcript content.

Plugins before 0.23.0 counted only the last API call of each session, so their figures were far too low. The server replaces those with an estimate. To replace the estimate with exact numbers for sessions whose transcripts are still on your machine, run:

/devscope:backfill-usage

Claude Code deletes transcripts after cleanupPeriodDays (30 days by default, set in ~/.claude/settings.json); older sessions keep the estimate.

Search past sessions

/devscope:search <terms> finds turns from your earlier Claude Code sessions (your prompts and Claude's replies) and links each one to the exact turn in the dashboard. It matches exact terms (identifiers, file names, error strings; "exact phrase", OR, -exclude all work) and meaning, so /devscope:search fixing the DNS outage finds the right session even if it used other words. It covers your own sessions plus teammates who share theirs; private sessions are never searched. The same search, with filters, is in the dashboard under Search.

DevScope Live (in-session mod)

devscope-live is a second, optional plugin in this marketplace. It is a Claude Code mod (function hooks, early access, Claude Code 2.1.291 or newer) that brings DevScope into the live session:

  • Team prompts: after a turn in which Claude did work, a short next step (a few words, like commit and push or /code-review high) that worked in several similar sessions (yours, and teammates who share theirs) appears as ghost text in the prompt box. Tab takes it. It stays quiet when Claude asked you something, and pauses for 30 minutes after you type over three in a row.

  • Team skills: when a prompt matches one of your team's approved skills, you're asked whether to use it. Choosing it attaches the skill to that prompt.

  • Stuck band: when Claude keeps failing the same way, a band above the prompt offers Step back (interrupt and ask Claude to reassess), Stop or Keep going.

  • Outcome labels: replies like "that didn't work" or "thanks" label the previous turn, and a long turn ends with "Did that work?". This tells DevScope which work actually succeeded.

  • Commit and PR links: commits and PRs a session makes are recorded against it, and whether its PRs merged is checked with your own gh. An optional DevScope-Session: trailer (off by default) marks Claude's commits and PRs.

  • Voice progress bar: while DevScope voice summarizes, creates or speaks audio, a colored 6-dot braille bar above the prompt shows how far along it is, with a Stop button.

/plugin install devscope-live@devscope

It reads the same DEVSCOPE_URL, DEVSCOPE_API_KEY and DEVSCOPE_PRIVACY settings. In private mode it sends no content or repository data. Each feature can be turned off in /config under the plugin's options. The devscope plugin is still what records your sessions; the mod only adds to it.

Voice announcements

Running several sessions, or working in another window? /devscope:voice on makes DevScope tell you out loud when a session has been waiting on you for a while:

"devscope-cloud, rate limiter fix. It wants to run the database migration and is waiting for your approval."

  • Only when you've lost track. It speaks after a grace delay (30 s for permission prompts and questions, 10 s for failed turns). Answer in time and it stays silent. If you don't, it reminds you every 5 minutes, up to 3 times.
  • Says which session. Every announcement and reply summary starts with the session's name: the project plus what it is working on, from the session's title or its git branch ("devscope-cloud, rate limiter fix"). A session keeps the same name for its whole life, so with several running you know which one is talking.
  • Across all sessions. Announcements play one at a time, and three or more at once become one sentence ("three sessions need you: rate limiter fix in devscope-cloud, oauth login in web and docs").
  • Summaries follow your privacy mode. Sentences are written by DevScope's AI from what your privacy mode already sends. private sessions never leave your machine and use a local template, named from the local git branch.
  • Natural voice, nothing to install. Speech is voiced by your DevScope server. Which voices it offers is up to the server; the homelab offers Chatterbox Turbo (the default, on its GPU) and Kokoro (on its CPU, also the fallback when the GPU is busy). /devscope:voice model lists them, /devscope:voice model kokoro picks one for you, model default goes back to the server's choice.
  • Local mode, for Macs. /devscope:voice model local speaks with this computer's own voice instead (say on macOS), with no audio from the server. It uses your System voice, so to hear a Siri voice pick one in System Settings → Accessibility → Spoken Content → System voice. The DevScope server still writes the auto voice summaries; only the voice is local. model chatterbox (or another server voice) switches back. Speed with /devscope:voice speed, volume with volume in voice.json (how loud the server makes the speech) and playback_volume (how loud this computer plays it, without turning up its other sounds). private sessions, and any time the server can't be reached, use a local voice instead: Piper if you ran /devscope:voice setup (Linux; pipx install piper-tts on macOS), otherwise the system voice (say, spd-say, espeak).

Other commands: off, mute 1h, unmute, test, status, finished on (also announce finished turns after 2 min), speed slow|normal|fast (1.0×, 1.2× or 1.5×, for every voice; or any number from 0.5 to 2, e.g. speed 1.35), stop (end speech in progress). Settings live in ~/.config/devscope/voice.json.

How detailed

/devscope:voice verbosity short|normal|long sets how detailed spoken responses are, for explanations and auto voice together; name one to set only that (verbosity auto short, verbosity explain long). Plain verbosity shows both.

short normal (default) long
Auto voice one sentence, the outcome two or three sentences four to six: what changed, why, what's next
Explain about 40 seconds about a minute and a half about three minutes

/devscope:voice explain --short <topic> (or --long) overrides it for one explanation.

Locked screen

DevScope only talks to someone at the computer. While the screen is locked:

What happens
Announcements ("a session is waiting") held, then said a few seconds after you unlock if the session still waits; no reminder is used up
Auto voice skipped; the reply is on screen when you are back
An explanation stops after the piece that is playing

It is detected locally, with nothing to install: on macOS from ioreg (CGSSessionScreenIsLocked) and the screensaver, on Linux from logind's LockedHint for your graphical session (GNOME, KDE and most lockers set it). Where it cannot tell (an SSH session, a server, a locker that does not set LockedHint, such as a bare i3lock) speech plays as before. An announcement held for more than 30 minutes is dropped, as any other that old is. /devscope:voice when-locked play turns this off; when-locked quiet (the default) turns it back on, and status shows whether the screen reads as locked.

Long speech is voiced in as few pieces as possible: text that fits one request (440 characters, so every normal summary) is one piece, and longer text is split only between sentences, so there is no pause mid-sentence.

Auto voice

Auto voice is a short spoken summary whenever Claude finishes a reply: the outcome first, then anything you need to decide, in two or three sentences. It works with the announcer on or off, and it is per session:

  • /devscope:voice auto turns it on or off for the session you type it in (auto on, auto off; plain auto toggles). It lasts as long as that Claude Code window, /clear included.
  • /devscope:voice auto-default on|off is the setting for every session where you have not used auto (off unless you turn it on).

It stays quiet on noise. Turns you did not start yourself, such as a monitor expiring or a task notification, are only spoken when they bring news: finished work, a failure, or a new question. A reply that just repeats what the last summary told you is skipped too. Turns you started are still summarized, and failures are never skipped. Set "auto_skip": false in voice.json to hear every reply.

/devscope:voice status shows both. The reply is sent to your DevScope server to summarize and is not stored; in private mode you only hear which project finished, voiced locally.

Explain it out loud

/devscope:voice explain [topic] talks a topic through like a colleague at a whiteboard: the question, a concrete scenario with real names and values, the options weighed out loud, where it leans, and a question back to you. A short written card stays in the chat. It speaks once, only when you run it; turn on auto voice to hear later replies too. With no topic it explains whatever you were just working on.

/devscope:voice explain why reminders sometimes come twice

What's Tracked

Event Data Sent
Session start/end Session duration, permission mode
Tool use Tool name, duration, success/failure
Prompt submit Prompt length
Subagent start/stop Agent type, task description (not in private mode) and model
Response complete Tools used, response length
Task completed Task details
And more... Notifications, compaction, config changes

All tracking hooks are async and non-blocking, so they won't slow down your Claude Code sessions. The one exception is the next-step hint, which has to be synchronous to show its message; it only reacts to gh pr create and returns in a few milliseconds otherwise.

Platform Support

Works on Linux and macOS. Cross-platform compatibility is handled automatically for:

  • SHA256 hashing (sha256sum / shasum / openssl)
  • Nanosecond timestamps (GNU date / python3 / perl fallback)
  • UUID generation (/proc/sys/kernel/random/uuid / uuidgen)

Links

Troubleshooting

Events not appearing in dashboard

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"

The installer checks for this, but if you skipped the warning, set them now.

Config not loaded — verify your config:

cat ~/.config/devscope/config
# Should show DEVSCOPE_URL and DEVSCOPE_API_KEY

Server unreachable — test the connection:

curl -sf "$(grep DEVSCOPE_URL ~/.config/devscope/config | cut -d= -f2)/api/health"

Invalid API key — generate a new key from Dashboard > Settings > API Keys.

Plugin not running

Check that the plugin is installed and enabled:

claude plugin list

If missing, reinstall:

claude plugin marketplace add DowLucas/devscope-plugin
claude plugin install devscope

Update not taking effect

Claude Code caches plugins by version. After updating:

claude plugin update devscope
# Restart Claude Code for changes to take effect

Contributing

For plugin-specific changes, open a PR here. For server/dashboard changes, see the main DevScope repo.

See CONTRIBUTING.md for guidelines.

License

MIT

About

Claude Code plugin for DevScope — real-time developer session monitoring

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages