Skip to content
Skills Library
Programming · Testing

logscope

/logscope

Observe and drive a device's serial logs without pasting them into chat. Use whenever the task involves watching firmware/device output, waiting for something to happen on hardware, sending CLI commands to a board, or running a flash/OTA/test flow and checking whether it worked. Triggers on "watch the logs", "did it boot", "is it connected", "send X to the device", "run the firmware update", "what happened on the board".

Repository
logscope ↗
Licence
MIT
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Observe and drive a device's serial logs without pasting them into chat. Use whenever the task involves watching firmware/device output, waiting for something to happen on hardware, sending CLI commands to a board, or running a flash/OTA/test flow and checking whether it worked. Triggers on "watch the logs", "did it boot", "is it connected", "send X to the device", "run the firmware update", "what happened on the board".

Triggers from the description

watch the logsdid it bootis it connectedsend X to the devicerun the firmware updatewhat happened on the board
Original author description

Observe and drive a device's serial logs without pasting them into chat. Use whenever the task involves watching firmware/device output, waiting for something to happen on hardware, sending CLI commands to a board, or running a flash/OTA/test flow and checking whether it worked. Triggers on "watch the logs", "did it boot", "is it connected", "send X to the device", "run the firmware update", "what happened on the board".

How it works

  1. Before anything else
  2. The cursor discipline — this is the whole point
  3. Reading, cheapest first
  4. Acting
  5. Annotating — do this as you go, not at the end
  6. Working a hardware flow
  7. Don'ts
Original SKILL.md headings · 121 lines, 837 words
SKILL.md preview
---
name: logscope
description: Observe and drive a device's serial logs without pasting them into chat. Use whenever the task involves watching firmware/device output, waiting for something to happen on hardware, sending CLI commands to a board, or running a flash/OTA/test flow and checking whether it worked. Triggers on "watch the logs", "did it boot", "is it connected", "send X to the device", "run the firmware update", "what happened on the board".
---

# logscope

A local daemon owns the serial port, timestamps every line, and stores them
under a monotonically increasing `seq`. You query it. **Log volume never enters
your context unless you ask for specific lines.**

The human watches the same stream in a terminal (`logscope tui`), with your
annotations rendered inline at the exact point in the log where you made them.

## Before anything else

```
logscope status          # is the daemon up, which sources, current head seq
logscope knowledge       # what we already know about THIS system
```

`logscope knowledge` is the durable per-project notes file. **Read it first and
trust it** — it exists so the human does not have to re-explain the setup every
session. When you learn something that will still be true next week, write it
back (`logscope knowledge --append "..."`). Session-specific noise does not
belong there; use `logscope note` for that.

## The cursor discipline — this is the whole point

Every read command prints a trailing `head=N` or `cursor=N`. **Keep that number
and pass it as `--since` on the next call.** You then only ever see what is new.
Without this you re-read the same thousand lines every turn and burn the budget
for nothing.

```
logscope summary                     # → head=18422
# ... do something ...
logscope summary --since 18422       # only what happened since
```

## Reading, cheapest first

Reach for these in order. Do not skip to `tail`.

| Want | Use |
|---|---|
| "wait until X happens" | `logscope wait --pattern RE --timeout 120` |
| "what happened while I was away" | `logscope summary --since N` |
| "find every occurrence of X" | `logscope grep RE --since N` |
| "I don't know what I'm looking for" | `logscope tail -n 60` |

**`wait` is the primary tool.** It blocks server-side and returns only the
matching line plus a few lines of context — a few dozen tokens for an event that
took four minutes and ten thousand log lines to arrive. Polling `tail` in a loop
is the wrong shape and costs ~100× more.

```
logscope wait --pattern 'BootNotification.*Accepted' --timeout 90
logscope wait --pattern 'FAULT|PANIC|Halting' --timeout 300   # watch for failure
```

Exit code 2 means it timed out — that is a real signal, not an error to retry
blindly. Ask why it did not happen.

`summary` gives you counts by level and tag plus deduplicated error lines. It is
the right way to answer "is anything wrong?" over a large range.

`tail` is the escape hatch for genuinely unknown failures. Use it deliberately,
bounded with `-n`, and prefer `--level err,wrn` to narrow it.

## Acting

```
logscope send "ocpp status" --wait 'endpoint|error' --timeout 10
logscope run flash                       # a named alias from .logscope/config.json
logscope run "make patched" --timeout 600
```

`send` writes to the device and can block for the reply in one round trip —
prefer that over `send` then a separate `wait`. It reports the cursor from
*before* the write, so the reply window is exact.

`run` executes an external step (flash script, CSMS trigger, build) and anchors
it in the same timeline as the serial log. **Use it instead of plain Bash for
anything whose effect shows up in the logs** — that is what makes cause and
effect line up for the human reading the timeline later.

## Annotating — do this as you go, not at the end

```
logscope mark "phase 2: OTA download"
logscope note "Download stalled 40s at 64KB — matches the NB-IoT keepalive bug"
logscope note --kind analysis --seq 18422 "This CEREG=2 is the modem re-attaching, not a failure"
```

Annotations anchor to a `seq` and render inline in the human's log view at that
point. This is the product: the log with your reasoning attached where it
happened. A run with no annotations is a wasted run — the human gets a wall of
text and no explanation.

Anchor to a specific `--seq` when commenting on a line you already saw. Omit it
to anchor at the current head.

## Working a hardware flow

1. `logscope knowledge` — load what we know.
2. `logscope mark "<what you are about to do>"`.
3. `logscope run <trigger>` or `logscope send <command>`.
4. `logscope wait --pattern <success> --timeout <realistic>` — and pass a
   pattern that also matches the *failure* shape, so you learn fast either way.
5. `logscope note` what you concluded, anchored where it happened.
6. If it was a durable lesson: `logscope knowledge --append`.

## Don'ts

- Don't `cat` or `tail -f` the raw log file. That is the thing this tool exists
  to prevent.
- Don't poll in a loop. Use `wait`.
- Don't re-read from seq 0. Use `--since`.
- Don't dump a large `tail` "to be safe". Use `summary` and then target it.
- Don't attach, detach, or re-baud ports (`/api/attach`, `/api/detach`)
  unless asked. The human owns the device picker, and those calls are saved
  to `config.json`. If a task truly needs a temporary switch, pass
  `"persist": false`.

Versions

The database has no other skills named logscope.

Database snapshot: 13.11.2026 · package version 92b6ec5b4066 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90esp32-ota-boot-confirmation-state
    Use when designing, reviewing, debugging or validating ota boot confirmation state for ESP32 firmware; apply target-specific constraints, failure analysis and measurable verification before release.
  • 85esp32-secure-ota-production
    Use when designing production OTA, signed firmware delivery, rollback, anti-rollback, secure boot, flash encryption or fleet rollout.
  • 100serial-console
    This skill should be used when a board is attached to the host and the user asks what it printed, whether it booted, why it stopped at U-Boot or a kernel panic, to "check the serial console", "watch the board boot", "send a command to the board", "/serial-console", or when a…
  • 100guachat-device-test
    Flash and test GUACHAT firmware on real hardware after explicit user confirmation. Use when the user asks to test on device, capture serial logs, or verify sensors/radio/audio.
  • 100esphome
    Use when flashing or automating ESP32/ESP8266 firmware with ESPHome 2026.10 — YAML configuration with esphome/esp32/api/ota/wifi blocks, esphome run/compile/logs/upload CLI, OTA updates, native API encryption, substitutions and packages; also for 'Component not found', OTA…
  • 100firmware-update-patterns
    OTA update patterns: MCUboot image headers, update progress over MQTT, version comparison, boot counters with automatic rollback, and aligned chunk writes. Use when implementing the device side of a firmware update.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.