chip-cnc 0.1.2

Type what you want carved. Chip designs it, checks it, and carves it on a FoxAlien XE-Ultra 8080 CNC — no CAM software, no G-code, no jargon.

Chip

Type what you want carved. Chip does the rest.

Chip is a desktop app that turns a plain-English sentence — "a sign that says The Hendersons with a pine tree on each side" — into a finished carving on a FoxAlien XE-Ultra 8080 CNC machine. No CAM software, no G-code, no file formats, no settings panels: describe the design, check the preview, clamp the board, press start.

What it does

• Design from a sentence. An AI designer lays out text, clip-art, and borders on your board, sized and centered sensibly. Refine it by dragging things around or just typing "make the name bigger". Every change — including the AI's — is undoable. No API key or internet? Built-in templates and full manual editing still work.
• Plain-language everything. Dimensions are fractional inches (3/4", 1-1/2"). Carve styles are "lines", "scooped out", and "cut through". Machine errors are translated into what happened, whether your workpiece is okay, and what to do next — never a raw error code.
• A guided carve, end to end. The app generates the toolpaths, walks through clamping, bit installation (with a picture of the right bit), setting the start point, and Z-probing — then streams the job with live progress and a STOP button that is always on screen. Multi-bit jobs pause for a guided bit change with a mandatory re-probe.
• Safety interlocks in software. No motion without an explicit press; carves refuse to start unless the machine is homed, zeroed, and the job fits the work envelope; STOP needs no confirmation and always works.
• An escape hatch. Any design exports as a true-size SVG (text as paths, pocket fills, engrave strokes) that imports cleanly into Easel Pro or other CAM tools for jobs beyond Chip's scope.

Honesty section: Chip targets exactly one machine — the FoxAlien XE-Ultra 8080 (840 × 840 × 120 mm, GRBL/grblHAL over USB serial). Machine limits live in config so contributors can adapt it, but nothing else has been tested. If you have a different machine, expect to do some work.

Requirements

• Windows installer: Windows 10/11, nothing else needed.
• pip install: Python 3.12–3.14 on Windows, macOS, or Linux.
• Machine control: the CNC connects over USB serial (CH340/FTDI/CP210x). On Linux, add yourself to the dialout group to access the port.
• AI design (optional): an Anthropic API key. Everything except "design it for me from a sentence" works without one.

Install

Windows: download ChipSetup-<version>.exe from the latest release and run it. Windows SmartScreen will warn about an unknown publisher — click More info → Run anyway (the exe is unsigned; this is expected).

Any OS, via pip:

pip install chip-cnc        # add 'chip-cnc[trace]' for picture tracing
chip                        # launches the app
chip --demo                 # full app with a simulated machine, no hardware needed
chip --self-check           # verifies the install, exits 0 when healthy

With uv (isolated install, no venv management):

uv tool install chip-cnc                   # or: uv tool install "chip-cnc[trace]"
chip --demo

uvx --from chip-cnc chip --demo            # or just try it, nothing installed

uv tool upgrade chip-cnc                   # later

With pipx:

pipx install chip-cnc                      # or: pipx install "chip-cnc[trace]"
chip --demo

pipx run --spec chip-cnc chip --demo       # one-off run without installing

pipx upgrade chip-cnc                      # later

Chip needs Python 3.12–3.14; if your default interpreter is something else, add --python 3.14 to the uv tool install, or --python python3.14 to pipx install.

The PyPI package is chip-cnc; the import package is chip. The [trace] extra (turning photos/logos into carvable shapes) depends on a native tracing wheel that is broken on some platform/Python combinations; when it doesn't work, that one feature grays out and everything else is unaffected (a potrace binary on your PATH also works as a fallback).

First run

1. Connect the machine (or don't — chip --demo runs everything against a simulator). With exactly one known USB-serial adapter plugged in, Chip connects automatically; the status strip at the bottom turns green when it's ready. If you have several serial devices, pick the port once in the Admin area.
2. Set up the AI designer (optional). Press Ctrl+Shift+A to reveal the hidden Admin area, paste your Anthropic API key under General, and it's stored in your OS keyring. The model is configurable there too. Without a key, the "describe it" step offers templates instead.
3. Make something. Make something new → type a sentence → adjust the preview → pick your wood and board size → follow the checklist → set the start point → hold Start carving.

Everything technical (serial port override, feeds/speeds tables, jog-arrow flipping for mirrored wiring, raw machine console, logs) lives in that same Admin area. If something goes wrong and you want help, Admin → Console & Logs → Export help bundle zips the logs, the last job, and the design into one file you can attach to a GitHub issue.

Your projects live in the standard per-user app-data directory (%LOCALAPPDATA%\Chip on Windows, ~/Library/Application Support/Chip on macOS, ~/.local/share/Chip on Linux) and autosave continuously — there is no save button, and deleted projects sit in a trash for 90 days.

Safety disclaimer

CNC machines spin sharp tools with real force and can injure you and destroy material. Chip adds software interlocks, but you are responsible for safe operation: eye protection, dust control, secure clamping, and never leaving a running machine unattended. The software is provided as-is, without warranty of any kind, per the Apache-2.0 license.

Development

Chip uses hatch — it creates the environment and installs all dependencies on first run:

git clone https://github.com/brettbergin/chip
cd chip
pip install hatch
hatch run test                            # full test suite (Qt runs offscreen)
hatch run lint                            # ruff
hatch run typecheck                       # mypy
hatch run python -m chip.app --demo       # run the app from source, simulated machine
hatch build                               # sdist + wheel

Prefer a plain venv? pip install -e ".[dev,trace]" then pytest works the same. No display is needed for the tests (QT_QPA_PLATFORM=offscreen is set automatically); the machine-control tests run against the bundled FakeGrbl simulator, and hardware-only checks are documented in tests/HARDWARE.md. If you change the design templates, regenerate the golden files with python tests/test_golden.py --regen.

The architecture in one line: pipeline/ (geometry, CAM, G-code), models/, store/, and the GRBL protocol code are pure Python (no Qt) and headless-testable; ui/ imports everything; nothing imports ui/. A test enforces this. See CONTRIBUTING.md for the ground rules and DECISIONS.md for the judgment-call log.

Releases are automated: maintainers tag vX.Y.Z, CI builds and publishes to PyPI (trusted publishing) and attaches the Windows installer to the GitHub release. There is no manual publish step.

License

Apache-2.0 — see LICENSE.