Scapton

Installation

Download the target-specific VSIX matching your VS Code host from the latest Scapton GitHub release. In VS Code, open Extensions, choose ..., select Install from VSIX, and choose the downloaded file. No Node.js, npm, KiCad installation, or manual dependency setup is required.

• Windows (x64): scapton-win32-x64-<version>.vsix
• Ubuntu/Linux (x64): scapton-linux-x64-<version>.vsix

Windows arm64, Linux arm64, and macOS builds are not published yet.

Every installer contains only the serial, Codex, and Claude native runtimes for its declared operating system and architecture.

After a Marketplace release, install Scapton directly from VS Code's Extensions view to receive automatic updates.

Open Scapton after installation

Reload VS Code if prompted, then open your firmware project folder:

1. Look near the bottom of the Activity Bar, the vertical icon strip at the far left of VS Code, for the turtle-shaped icon. Hovering it shows Scapton.
2. Select the icon, then open Analysis. If the icon is hidden, right-click the Activity Bar and enable Scapton.
3. As a keyboard alternative, open the Command Palette and run Scapton: Open.
4. Choose the project, select its Device Tree or resolved build output, and select Verify.

Any project folder opens. The hardware comparison needs a KiCad schematic (.kicad_sch, .sch) or a scapton.wiring declaration; a project with neither opens normally and only Verify is unavailable — build, flash, serial capture, log analysis, datasheets, and the assistant all work.

Scapton combines the project's KiCad schematic sheets automatically. Findings appear under Analysis and are saved locally to scapton-report/report.json; Drivers reports per-part Zephyr driver support, Logs analyzes captured device output, Device contains build, flash, and serial tools, and Datasheets manages optional local documentation.

Drivers

For every software-controlled part on the schematic, Scapton checks whether the Zephyr tree this project builds against already contains a driver for it — by reading that tree, not from a table of what Zephyr is expected to ship. Each verdict is one of four: a driver is available, this tree has none, the schematic does not name the part precisely enough, or nothing was checked.

That last one matters. When no Zephyr workspace can be found, no component is checked, and the view says so rather than showing an empty list that reads like a clean result. Build the project once so Scapton can read the build directory, select the tree from the view, or set scapton.zephyr.base. The tree is only read — your own build and flash commands are untouched.

Rejected near-misses travel with each verdict, so "no driver" is visibly a decision with reasons.

Logs

Logs analyzes a captured boot or serial log locally — the live serial session, a saved transcript, or any .log / .txt / .jsonl file you open. No model and no network are involved in the analysis itself.

Each finding separates what was observed, what is proven from it, an explicitly unproven hypothesis, what blocked a firmer answer, and a suggested next step — so a guess can never be mistaken for a conclusion. The capture's context state and quality (truncated, garbled, missing timestamps) lead the report, because both qualify everything below them. Evidence rows carry the line number and open the capture there.

Explain with AI is a separate, explicit step that hands the finished report to the assistant you connected. The command Scapton: Analyze Logs opens the view and analyzes the newest capture.

AI explanations (local-first, your own model)

Each finding card has Explain with AI and Copy AI prompt; the results panel has the same two for the whole scan. The AI explains findings — what the mismatch means, why it breaks bring-up, what to probe, which line to open. It is never the source of truth: the deterministic analyzer is, and the prompt says so.

Scapton runs no backend. Nothing is uploaded to an Scapton server, because there is no Scapton server. Four ways to reach a model, all of them yours:

• Codex account — Connect Codex uses the pinned official Codex runtime bundled in the target-specific Scapton installer, then uses its normal ChatGPT/OpenAI browser sign-in and model catalog. Codex opens in Edit mode by default. It runs ephemerally with a workspace-write sandbox rooted at the selected project, never receives approval to escape that sandbox, and uses Scapton's authenticated local MCP bridge for the guarded serial/build/flash actions. Scapton never reads or copies the Codex account token. Device-code authorization is not required.
• Claude account — Connect Claude uses the Claude runtime bundled in the target-specific Scapton installer, reuses an existing Claude login when available, or starts Anthropic's normal browser authorization for the user's Claude subscription. If Anthropic shows a one-time authorization code, Scapton provides a masked prompt that passes it directly to the waiting Claude runtime; the code is not stored or logged. Ask and Edit use Anthropic's official Agent SDK with session persistence disabled. Scapton never reads or copies the account credential and never sets an API key on this route.
• VS Code language model — a model you have already authorized in VS Code (Copilot, or any extension that registers one), under your own subscription and consent. Models with tool-calling support can use Edit mode through project-scoped read and exact-replace tools; other models remain Ask-only.
• Clipboard prompt — the always-available fallback. Scapton calls nothing: it copies the prompt so you can paste it into whatever assistant your company approves.

Scapton installers are target-specific for Windows or Linux x64, and contain the matching pinned provider runtimes. Note that VS Code's Language Model API has no system role, so on that path the "analyzer is the source of truth" instruction rides as a user turn; the direct Anthropic path uses a real system prompt.

Set scapton.ai.disabled to guarantee the extension never calls a model. Copy prompt remains available so you can paste the compact context into an assistant your organization approves.

The answer streams into the assistant view as it arrives and is cancellable. Edit mode can use Codex, Claude with its runtime, or a tool-capable VS Code model. Ask mode can use any listed model; the selected model is remembered and is never silently replaced with another provider. The picker uses each provider's live model catalog. Claude subscription models are listed individually, and reasoning-effort controls show only the levels the selected model reports. Image-capable models also accept pasted PNG, JPEG, GIF, or WebP images in the composer; pasted bytes go directly to the selected model and Codex temporary image files are removed after the request.

In Ask mode, the model sees findings.ai.txt — the compact deterministic findings, never your schematic or device-tree source — plus bounded, page-cited excerpts from datasheets you explicitly attach. In Edit mode, the selected model can read and update files inside the selected project. The composer shows the provider and project disclosure inline; sending in Edit mode grants access for that request without an extra confirmation window.

Edit mode also exposes fixed Build project and Flash project actions. They use the same command and detected Zephyr virtual environment as the Device buttons, stream output into the Device console, and return an explicit verdict to the model. The model cannot supply shell text: it can only select build or flash. Flash releases Scapton's serial connection first, and concurrent build/flash processes are rejected.

The prompt also lifts the analyzer's own doubts into a section the model is told not to paper over: incomplete coverage, experimental SoC adapters, unparsed pin properties, connectivity-only verification, and parser warnings. A confident explanation of a finding the analyzer could not actually verify is the worst possible output here, so the caveats are made impossible to skim past.

Datasheets during bring-up

The Datasheets tool deterministically reads component part values from the schematic and considers only useful active parts such as sensors, microcontrollers, radio modules, motors, microphones, and transistors. Composite module symbols can produce separate module and underlying-SoC recommendations. Generic passives, cables, solder jumpers, connectors, test points, mounting parts, and power symbols are omitted; each recommendation identifies the component references and why the document is useful. Unresolved parts are hidden. Matching part-number documents, Markdown beside the schematic, and board-specific Markdown elsewhere in the project are shown, but never sent merely because they exist: choose Attach for each document the assistant may use. PDF text extraction is local, bounded, and query-aware; only the most relevant pages are included and the assistant is told to cite the file and page. Image-only scanned PDFs require OCR and are reported as unsupported rather than silently attaching empty context.

Add files copies selected documents into .scapton/datasheets/ and adds a nested .gitignore so vendor PDFs are not accidentally committed. Deterministic vendor adapters offer Download & attach from a fixed, approved document source after confirmation. Downloads are HTTPS-only, bounded to 25 MB, validated as PDFs, checked against a pinned SHA-256, stored with source metadata, and never run automatically. Optional scapton.datasheets.onlineDiscovery checks up to six unresolved active-component part numbers when the page opens. It sends only each part number to DuckDuckGo, tries at most two direct public HTTPS PDF results, extracts each candidate locally, and shows the recommendation only when the PDF contains the exact normalized part number. The first use asks for permission.

Device terminal

The Terminal tool connects directly to serial devices available to the host operating system. It discovers COM ports on Windows and device paths on Linux and macOS, offers common baud rates, streams received text, and sends single- or multi-line UTF-8 commands. Commands can append no line ending, LF (\\n), CR (\\r), or CRLF (\\r\\n). Optional escape interpretation also supports \\t, \\b, \\f, \\v, \\0, \\\\, and \\xNN bytes.

Auto-detect ranks likely USB serial adapters, passively samples common baud rates, and connects when the received bytes look like readable device logs. A silent device cannot reveal its baud rate, so that case selects the most likely port and keeps the baud rate manual instead of claiming a false detection. Warning, error, panic, timeout, overrun, and fault lines are also collected in a separate diagnostics panel while the complete stream remains visible.

Serial traffic stays local. Port access ends when the application panel closes. On Linux, the signed-in user must have permission to access the selected device (commonly through the distribution's dialout or equivalent group).

In Edit mode, Codex, a tool-capable VS Code model, or a connected Claude account can run a narrow set of read-only Zephyr probes through the already-open connection: i2c scan/read/read_byte, gpio get, device list, kernel uptime, and help. Scapton blocks writes/reconfiguration, concurrent writers, and shell operators; each probe has a bounded timeout and its TX/RX is kept in the normal session transcript. Codex and Claude use a single-purpose local MCP bridge bound to loopback, authenticated with an ephemeral token; the bridge cannot read project files or open the serial port itself.

Saved sessions produce adjacent .log and .etf files under scapton-report/logs/. The ETF/1 runtime records classify reset reasons, ESP32 boot modes, I2C ACK/no-ACK results, and driver readiness with exact log-file:line evidence. The assistant receives those deterministic findings before the bounded raw transcript and is told not to re-derive mechanical log facts itself.

Feeding the findings to an AI manually

Every analysis also writes scapton-report/findings.ai.txt — the same findings in a compact, line-oriented form (ETF/1, documented in @scapton/cli). Copy findings as AI context in the results panel puts it on the clipboard.

Because the hardware/firmware mismatch has already been found deterministically, a model does not need the schematic or the device tree in context to act on it: it needs the rule, the evidence from both sides, and the file:line to open. That is all this file carries. On a real Zephyr board it is ~900 tokens, against ~57k for the raw schematic and device trees it was derived from.

Linux/Yocto boards: point at the kernel, we find the board file

For boards whose device tree lives in a Linux kernel tree rather than the hardware repo, use Use an external device tree file. You do not have to hunt down the exact board .dts: point at the kernel's arch/<arch>/boot/dts and Scapton reads the SoC off your schematic's controller (its part value, footprint, or library id), then searches the tree and offers the board files that match, best first.

Matching uses two signals. A board file's name usually carries its SoC (stm32f407-disco.dts, sun50i-a64-olinuxino.dts, am335x-boneblack.dts), but many do not — so each candidate's own compatible and model are read as well. That is the authoritative signal, and it outranks a filename guess: an A64 schematic finds teres-i.dts, whose name says nothing about the SoC, because the file declares compatible = "olimex,a64-teres-i", "allwinner,sun50i-a64". Each suggestion says which signal it matched on, so a guess is never dressed up as a declaration. ST, Nordic, TI Sitara, NXP i.MX, Rockchip, Allwinner, Espressif, Microchip/Atmel, Renesas, and Broadcom parts are recognized.

Kernel trees you have used are remembered and offered first, so the common case takes no file browsing at all. The kernel include roots (include/, arch/<arch>/boot/dts, and the vendor directory) are resolved automatically, so the SoC .dtsi and dt-bindings references stitch together without any manual --include-dir.

The desktop extension uses Node and VS Code filesystem APIs only, with no shell commands or platform-specific path assumptions, and supports Windows, Linux, and macOS.

Licence

Scapton is free to install and use, for personal and commercial work alike. No fee, registration, or separate agreement is required.

The extension itself stays proprietary: the licence grants the right to use Scapton, not to redistribute, modify, or reverse engineer it. See LICENSE and NOTICE in the extension package.

Scapton analyses projects you supply. Your schematics, source code, and the analysis output produced from them remain yours.

Versions through 0.0.10, and source revisions previously released under Apache-2.0, retain the rights granted when they were released. Bundled third-party materials remain under their respective licences.