How rylero/claudescope works
1. Repository shape
This repo has two main layers: a Claude Code plugin layer for user-facing skills, and a Go runtime layer that powers the ClaudeScope CLI/daemon used by those skills.
2. Claude Code plugin / skills layer
The .claude-plugin metadata plus skills/scope, skills/simulate, and skills/replay define the three user workflows exposed in Claude Code:
- /scope for analyzing .wpilog files and live NetworkTables
- /simulate for launching robot simulation and connecting ClaudeScope
- /replay for replaying logs through robot code and comparing outputs
These skills are orchestration and prompt assets, not the core data-processing engine.
3. ClaudeScope CLI as the user entry point
The ClaudeScope/ Go module builds the actual binary users install from releases. It is the executable boundary between Claude-driven workflows and the underlying robot-log / NetworkTables inspection logic.
4. Command dispatch and client boundary
main.go, cli/commands.go, and cli/client.go form the CLI front end:
- parse commands and subcommands
- connect to the backend service
- forward requests/responses for analysis operations
This separates the interactive shell command from the service that actually performs work.
5. Local daemon architecture
The daemon/ package is a local service layer:
- server.go starts the daemon process
- handlers.go exposes request handlers
- registry.go tracks available sessions/resources
The CLI talks to this daemon through the client layer, so analysis logic lives behind a local process boundary rather than directly inside the command runner.
6. Session abstraction: log vs live data
The session/ package is the key domain boundary:
- interface.go defines the shared contract
- log_session.go handles .wpilog-backed analysis
- nt_session.go handles live NetworkTables access
This abstraction is what lets the same tooling answer questions from either recorded logs or live robot state.
7. Platform-specific process spawning
cli/spawn_unix.go and cli/spawn_windows.go indicate the CLI can launch the daemon differently depending on OS. That makes the tool cross-platform while keeping the backend service model consistent.
8. Primary data flows
- /scope: Claude Code skill → ClaudeScope CLI → local daemon → log session or live NT session → summarized diagnostics back to Claude
- /simulate: Claude Code skill → CLI → external robot simulation environment + ClaudeScope connection → live inspection loop
- /replay: Claude Code skill → replay pipeline using robot code/AdvantageKit replay mode → ClaudeScope compares recorded vs recomputed signals
9. External ecosystem boundaries
The repo is tightly centered on FRC tooling:
- .wpilog files
- NetworkTables
- robot simulation
- AdvantageKit replay mode
Those are the important external integration points that define the architecture.
10. Build and distribution
.github/workflows/release.yml suggests the repo produces multi-platform binaries, and the README lists Windows/macOS/Linux artifacts. The release pipeline is therefore part of the architecture, because it packages the CLI for local use inside Claude Code workflows.
11. Documentation as design source
docs/superpowers/specs and docs/superpowers/plans capture design intent for the skills and tool behavior. They are not runtime components, but they explain how the user-facing workflows are intended to operate.
12. How to diagram it
A useful architecture diagram should show:
- Claude Code plugin/skills at the top
- the ClaudeScope CLI as the user entry point
- a local daemon behind the CLI
- session adapters beneath the daemon for log and NetworkTables access
- external FRC inputs/outputs on the side: .wpilog, live robot NT, simulation, and replay tooling
Main entry points: main.go Entry point · marketplace.json Plugin meta · scope/SKILL.md Scope skill · simulate/SKILL.md Simulate skill
Components 20
Claude Code skills
User-facing orchestration assets exposed inside Claude Code.
- Plugin meta · Marketplace metadata that registers the Claude Code plugin.
.claude-plugin/marketplace.json - Scope skill · Workflow for analyzing wpilog logs and live NetworkTables state.
skills/scope/SKILL.md - Simulate skill · Workflow for launching robot simulation and connecting ClaudeScope.
skills/simulate/SKILL.md - Replay skill · Workflow for replaying logs through robot code and comparing outputs.
skills/replay/SKILL.md
ClaudeScope CLI
Go executable boundary and command/client front end.
- Entry point · Executable entry for the ClaudeScope binary.
ClaudeScope/main.go - Command router · Parses commands and subcommands for user actions.
ClaudeScope/cli/commands.go - Daemon client · Connects the CLI to the local daemon and forwards requests.
ClaudeScope/cli/client.go - Process spawn · Platform-specific daemon launch logic for Unix and Windows.
Daemon runtime
Local backend service and session abstractions.
- Daemon server · Starts the local backend process.
ClaudeScope/daemon/server.go - Request handlers · Handles daemon requests from the CLI client.
ClaudeScope/daemon/handlers.go - Session registry · Tracks available sessions and runtime resources.
ClaudeScope/daemon/registry.go - Session contract · Shared abstraction for log-backed and live sessions.
ClaudeScope/session/interface.go - Log session · Implements analysis over recorded wpilog data.
ClaudeScope/session/log_session.go - NT session · Implements live NetworkTables access for connected robots.
ClaudeScope/session/nt_session.go
Support assets
Documentation, release packaging, and distribution metadata.
- Release workflow · Multi-platform packaging and release automation.
.github/workflows/release.yml - Design docs · Specs and plans that define intended skills and runtime behavior.
docs/superpowers
Other components
- WPI log · Recorded robot log file format analyzed by Scope and Replay.
- NetworkTables · Live robot telemetry and state transport used by Scope.
- Robot sim · Robot simulation environment launched by the Simulate workflow.
- Replay mode · Robot-code replay execution used to recompute signals from logs.
Connections 21
- Plugin meta → Scope skill: exposes · Registers the Scope workflow in Claude Code.
- Plugin meta → Simulate skill: exposes · Registers the Simulate workflow in Claude Code.
- Plugin meta → Replay skill: exposes · Registers the Replay workflow in Claude Code.
- Scope skill → Entry point: invokes · Scope skill drives the ClaudeScope binary.
- Simulate skill → Entry point: invokes · Simulate skill launches the ClaudeScope CLI.
- Replay skill → Entry point: invokes · Replay skill uses the ClaudeScope CLI.
- Entry point → Command router: dispatches · Binary entry routes into command parsing.
- Command router → Daemon client: calls · Command handlers forward work to the daemon client.
- Daemon client → Process spawn: starts · Client launches the daemon using OS-specific logic.
- Process spawn → Daemon server: boots · Platform launcher starts the local daemon process.
- Daemon server → Request handlers: serves · Server exposes request handlers.
- Request handlers → Session registry: uses · Handlers consult the registry for sessions and resources.
- Request handlers → Session contract: routes to · Handlers operate through the shared session contract.
- Session contract → Log session: implements · Log session provides the recorded-data implementation.
- Session contract → NT session: implements · NT session provides the live-robot implementation.
- Log session → WPI log: reads · Log session analyzes wpilog files.
- NT session → NetworkTables: connects to · NT session reads live NetworkTables state.
- Simulate skill → Robot sim: orchestrates · Simulate skill coordinates robot simulation.
- Replay skill → Replay mode: orchestrates · Replay skill coordinates replay execution.
- Scope skill → Design docs: guided by · Scope behavior is described by design docs and plans.
- Entry point → Release workflow: distributed by · Release workflow packages the CLI for users.