# rylero/claudescope architecture

> Architecture diagram of the GitHub repository rylero/claudescope, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rylero/claudescope
- Repository: https://github.com/rylero/claudescope

## Overview

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: [`ClaudeScope/main.go`](https://github.com/rylero/claudescope/blob/main/ClaudeScope/main.go) (Entry point), [`.claude-plugin/marketplace.json`](https://github.com/rylero/claudescope/blob/main/.claude-plugin/marketplace.json) (Plugin meta), [`skills/scope/SKILL.md`](https://github.com/rylero/claudescope/blob/main/skills/scope/SKILL.md) (Scope skill), [`skills/simulate/SKILL.md`](https://github.com/rylero/claudescope/blob/main/skills/simulate/SKILL.md) (Simulate skill)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_skills["Claude Code skills"]
  node_node_marketplace["Plugin meta<br/>[marketplace.json]"]
  node_node_skill_scope["Scope skill<br/>skill orchestration<br/>[SKILL.md]"]
  node_node_skill_simulate["Simulate skill<br/>skill orchestration<br/>[SKILL.md]"]
  node_node_skill_replay["Replay skill<br/>skill orchestration<br/>[SKILL.md]"]
end

subgraph group_group_cli["ClaudeScope CLI"]
  node_node_main["Entry point<br/>go main<br/>[main.go]"]
  node_node_commands["Command router<br/>cli dispatch<br/>[commands.go]"]
  node_node_client["Daemon client<br/>rpc client<br/>[client.go]"]
  node_node_spawn["Process spawn<br/>os launcher"]
end

subgraph group_group_runtime["Daemon runtime"]
  node_node_daemon_server["Daemon server<br/>local service<br/>[server.go]"]
  node_node_daemon_handlers["Request handlers<br/>service api<br/>[handlers.go]"]
  node_node_registry["Session registry<br/>resource registry<br/>[registry.go]"]
  node_node_session_iface["Session contract<br/>session interface<br/>[interface.go]"]
  node_node_log_session["Log session<br/>[log_session.go]"]
  node_node_nt_session["NT session<br/>networktables session<br/>[nt_session.go]"]
end

subgraph group_group_support["Support assets"]
  node_node_release["Release workflow<br/>build pipeline<br/>[release.yml]"]
  node_node_docs["Design docs<br/>architecture docs"]
end

node_node_wpilog[("WPI log<br/>external input")]
node_node_networktables[("NetworkTables<br/>external live state")]
node_node_simulation(("Robot sim<br/>external runtime"))
node_node_replaymode(("Replay mode<br/>external runtime"))

node_node_marketplace -->|"exposes"| node_node_skill_scope
node_node_marketplace -->|"exposes"| node_node_skill_simulate
node_node_marketplace -->|"exposes"| node_node_skill_replay
node_node_skill_scope -->|"invokes"| node_node_main
node_node_skill_simulate -->|"invokes"| node_node_main
node_node_skill_replay -->|"invokes"| node_node_main
node_node_main -->|"dispatches"| node_node_commands
node_node_commands -->|"calls"| node_node_client
node_node_client -->|"starts"| node_node_spawn
node_node_spawn -->|"boots"| node_node_daemon_server
node_node_daemon_server -->|"serves"| node_node_daemon_handlers
node_node_daemon_handlers -->|"uses"| node_node_registry
node_node_daemon_handlers -->|"routes to"| node_node_session_iface
node_node_session_iface -->|"implements"| node_node_log_session
node_node_session_iface -->|"implements"| node_node_nt_session
node_node_log_session -->|"reads"| node_node_wpilog
node_node_nt_session -->|"connects to"| node_node_networktables
node_node_skill_simulate -->|"orchestrates"| node_node_simulation
node_node_skill_replay -->|"orchestrates"| node_node_replaymode
node_node_skill_scope -.->|"guided by"| node_node_docs
node_node_main -.->|"distributed by"| node_node_release

click node_node_marketplace "https://github.com/rylero/claudescope/blob/main/.claude-plugin/marketplace.json"
click node_node_skill_scope "https://github.com/rylero/claudescope/blob/main/skills/scope/SKILL.md"
click node_node_skill_simulate "https://github.com/rylero/claudescope/blob/main/skills/simulate/SKILL.md"
click node_node_skill_replay "https://github.com/rylero/claudescope/blob/main/skills/replay/SKILL.md"
click node_node_main "https://github.com/rylero/claudescope/blob/main/ClaudeScope/main.go"
click node_node_commands "https://github.com/rylero/claudescope/blob/main/ClaudeScope/cli/commands.go"
click node_node_client "https://github.com/rylero/claudescope/blob/main/ClaudeScope/cli/client.go"
click node_node_daemon_server "https://github.com/rylero/claudescope/blob/main/ClaudeScope/daemon/server.go"
click node_node_daemon_handlers "https://github.com/rylero/claudescope/blob/main/ClaudeScope/daemon/handlers.go"
click node_node_registry "https://github.com/rylero/claudescope/blob/main/ClaudeScope/daemon/registry.go"
click node_node_session_iface "https://github.com/rylero/claudescope/blob/main/ClaudeScope/session/interface.go"
click node_node_log_session "https://github.com/rylero/claudescope/blob/main/ClaudeScope/session/log_session.go"
click node_node_nt_session "https://github.com/rylero/claudescope/blob/main/ClaudeScope/session/nt_session.go"
click node_node_release "https://github.com/rylero/claudescope/blob/main/.github/workflows/release.yml"
click node_node_docs "https://github.com/rylero/claudescope/tree/main/docs/superpowers"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_marketplace,node_node_skill_scope,node_node_skill_simulate,node_node_skill_replay toneBlue
class node_node_main,node_node_commands,node_node_client,node_node_spawn toneAmber
class node_node_daemon_server,node_node_daemon_handlers,node_node_registry,node_node_session_iface,node_node_log_session,node_node_nt_session toneMint
class node_node_release,node_node_docs toneRose
class node_node_wpilog,node_node_networktables,node_node_simulation,node_node_replaymode toneNeutral
```

## Components

### Claude Code skills

User-facing orchestration assets exposed inside Claude Code.

- [Plugin meta](https://github.com/rylero/claudescope/blob/main/.claude-plugin/marketplace.json): claude plugin metadata · Marketplace metadata that registers the Claude Code plugin. · `.claude-plugin/marketplace.json`
- [Scope skill](https://github.com/rylero/claudescope/blob/main/skills/scope/SKILL.md): skill orchestration · Workflow for analyzing wpilog logs and live NetworkTables state. · `skills/scope/SKILL.md`
- [Simulate skill](https://github.com/rylero/claudescope/blob/main/skills/simulate/SKILL.md): skill orchestration · Workflow for launching robot simulation and connecting ClaudeScope. · `skills/simulate/SKILL.md`
- [Replay skill](https://github.com/rylero/claudescope/blob/main/skills/replay/SKILL.md): skill orchestration · 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](https://github.com/rylero/claudescope/blob/main/ClaudeScope/main.go): go main · Executable entry for the ClaudeScope binary. · `ClaudeScope/main.go`
- [Command router](https://github.com/rylero/claudescope/blob/main/ClaudeScope/cli/commands.go): cli dispatch · Parses commands and subcommands for user actions. · `ClaudeScope/cli/commands.go`
- [Daemon client](https://github.com/rylero/claudescope/blob/main/ClaudeScope/cli/client.go): rpc client · Connects the CLI to the local daemon and forwards requests. · `ClaudeScope/cli/client.go`
- **Process spawn**: os launcher · Platform-specific daemon launch logic for Unix and Windows.

### Daemon runtime

Local backend service and session abstractions.

- [Daemon server](https://github.com/rylero/claudescope/blob/main/ClaudeScope/daemon/server.go): local service · Starts the local backend process. · `ClaudeScope/daemon/server.go`
- [Request handlers](https://github.com/rylero/claudescope/blob/main/ClaudeScope/daemon/handlers.go): service api · Handles daemon requests from the CLI client. · `ClaudeScope/daemon/handlers.go`
- [Session registry](https://github.com/rylero/claudescope/blob/main/ClaudeScope/daemon/registry.go): resource registry · Tracks available sessions and runtime resources. · `ClaudeScope/daemon/registry.go`
- [Session contract](https://github.com/rylero/claudescope/blob/main/ClaudeScope/session/interface.go): session interface · Shared abstraction for log-backed and live sessions. · `ClaudeScope/session/interface.go`
- [Log session](https://github.com/rylero/claudescope/blob/main/ClaudeScope/session/log_session.go): wpilog session · Implements analysis over recorded wpilog data. · `ClaudeScope/session/log_session.go`
- [NT session](https://github.com/rylero/claudescope/blob/main/ClaudeScope/session/nt_session.go): networktables session · Implements live NetworkTables access for connected robots. · `ClaudeScope/session/nt_session.go`

### Support assets

Documentation, release packaging, and distribution metadata.

- [Release workflow](https://github.com/rylero/claudescope/blob/main/.github/workflows/release.yml): build pipeline · Multi-platform packaging and release automation. · `.github/workflows/release.yml`
- [Design docs](https://github.com/rylero/claudescope/tree/main/docs/superpowers): architecture docs · Specs and plans that define intended skills and runtime behavior. · `docs/superpowers`

### Other components

- **WPI log**: external input · Recorded robot log file format analyzed by Scope and Replay.
- **NetworkTables**: external live state · Live robot telemetry and state transport used by Scope.
- **Robot sim**: external runtime · Robot simulation environment launched by the Simulate workflow.
- **Replay mode**: external runtime · Robot-code replay execution used to recompute signals from logs.

## Connections

- 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.