Updated: ClaudeDebug for Spin-Tools

ke4pjw · 2026-03-17 04:29

I have created a set of markdown and shell scripts that will instruct Claude Code on how to create a build-upload-debug pipeline using spinc.exe.

The repo is located here:

https://griswoldfx.visualstudio.com/_git/ClaudeP2Debug

I hope others find this useful. I am sure it can easily adapted to accommodate users on other platforms.

Spin Tools for Claude Code

Build, upload, and debug Propeller 2 programs from Claude Code using natural language prompts.

Prerequisites

Windows with Git Bash or WSL
Spin Tools compiler (spinc.exe) — download from Spin Tools and install to C:\spin-tools\
Propeller 2 board connected via USB (e.g. P2 EVAL)
Claude Code installed and working in your terminal

Setup

1. Copy the pipeline files into your project

Copy these files into your Spin2 project directory:

your-project/
  detect_p2.sh          # Auto-detects the P2 COM port
  DebugTest_Top.spin2   # Test program to validate the pipeline
  SPINC_BUILD.md        # Pipeline reference (Claude reads this)

2. Add a CLAUDE.md to your project

Create a CLAUDE.md file in your project root so Claude Code knows how to build and run your code:

# Build & Upload

This project targets the Parallax Propeller 2 microcontroller.

## Compiler

Spin Tools compiler: `C:\spin-tools\spinc.exe`

## Build-Upload-Debug command

Source `./detect_p2.sh` to auto-detect the COM port, then compile and upload:

    source ./detect_p2.sh
    "C:\spin-tools\spinc.exe" -p $P2_PORT -d -t -r "./<YOUR_TOP_FILE>.spin2"

## Pipeline reference

See SPINC_BUILD.md for full documentation.

Replace <YOUR_TOP_FILE> with your top-level .spin2 file.

Testing the Pipeline

Once set up, open Claude Code in your project directory and try these prompts:

Verify everything works

"Build and run DebugTest_Top.spin2 on my P2"

Claude will detect your board, compile the test program, upload it, and show you the debug output. You should see Hello from P2 and Result: value = 42 in the output.

"Test the build-upload-debug pipeline"

Same as above — Claude understands the pipeline from SPINC_BUILD.md and will run through all the steps.

Check your board connection

"Detect which COM port my P2 is on"

Claude will scan your USB ports and tell you which one has a Propeller 2 attached.

Making Changes

You can ask Claude to modify DebugTest_Top.spin2 and immediately run it on your board. Here are some example prompts to try:

"Add a countdown from 10 to 1 in the debug output, then run it"

"Make the program blink the LED on pin 56 five times before printing the message"

"Change the debug output to print the Fibonacci sequence up to 100, then build and upload"

"Add a second value that multiplies value by 3 and print both results, then test it on the P2"

Each time, Claude will edit the code, compile, upload, and show you the debug output from the board — all in one step.

Reference

See SPINC_BUILD.md for the full pipeline specification including compiler flags, expected output, and troubleshooting tips.

ke4pjw · 2026-03-17 13:58

Turns out, this may not be needed for Spin-Tools at all, but I am going to leave it here for the moment as it may be useful for other generic complilers.

refaQtor · 2026-03-17 23:22

slick!
I'd done similar having the AI insert copious debug statements, watch and interpret the output to determine the execution path/breakage, and report and correct as I directed. this was pre-agents, and largely manual, but useful just the same.. brutish and obscene, but did the trick and revealed to me what the issue was.
you interpreting actual DEBUG output is extra cool!

ke4pjw · 2026-03-18 05:11

I have updated the repo with a much simpler solution. It takes care of autodetecting the com port for the P2. This weekend I will do a quick video on how to use it.

Special thanks to @macca and @"Stephen Moraco" for providing such a rich set of tools and information. Stephen has a much more sophisticated pipeline than I put together here. This is a minimal config where you can just install Claude Code, point to to your project directory, drop in a couple of files from this repo, and start vibe coding.