scope-skill

A Claude Code skill that teaches Claude to interact with a serial port / UART / COM port or an RTT target using the scope serial monitor in headless mode — connecting, sending text / commands / raw bytes, and reading the device's replies, all without the TUI.

The skill triggers automatically whenever you ask Claude to talk to, read from, send data to, or debug a serial device or RTT target from the terminal.

What's here

scope-skill/
├── SKILL.md               # the skill (instructions Claude loads)
├── scripts/
│   └── scope-drive.sh     # helper: scope_start / scope_send / scope_read / scope_cmd / scope_quit …
└── README.md

Install

This repo is the skill directory — clone it into your skills folder:

# Project-scoped (only in this repo):
git clone git@github.com:matheuswhite/scope-skill.git .claude/skills/scope-headless

# or user-scoped (available everywhere):
git clone git@github.com:matheuswhite/scope-skill.git ~/.claude/skills/scope-headless

Then Claude picks it up when a request matches — or invoke it explicitly with /scope-headless. Verify it's registered with /skills.

Two transports

scope --headless is a raw byte bridge. The helper can drive it two ways, chosen with SCOPE_TRANSPORT:

• pipe (default) — no tmux, no PTY. scope runs in the background reading a FIFO and writing to a file. Simplest for an agent; the session persists across shell commands. Needs a scope with stdin support (recent builds).
• tmux — scope in a tmux pane, driven with send-keys / capture-pane. For a live/human-watchable session, or with an older scope that requires a real terminal. The helper auto-suggests this if a piped scope aborts on startup.

Requirements

• scope on PATH, or built from the scope-rs checkout (cargo build --bin scope, then point SCOPE_BIN at target/debug/scope).
• tmux — only for SCOPE_TRANSPORT=tmux. brew install tmux (or your package manager). The default pipe transport needs neither tmux nor a PTY.

Using the helper directly

You don't need Claude to use the helper — it's a normal shell library:

source scripts/scope-drive.sh                 # SCOPE_TRANSPORT=pipe by default
scope_start serial /dev/ttyUSB0 115200
scope_send 'AT+VERSION?'
scope_wait_for 'OK' 5 && scope_read
scope_quit && scope_cleanup

See the comments in scripts/scope-drive.sh and the full behaviour notes in SKILL.md (transports, line endings, no-local-echo, stdin-EOF quit, which commands work in headless, the macOS virtual-port caveat, etc.).