Bad origin

flatmaxx takes a finished KiCad board and drives your entire home-fab bench for you: it generates Gerbers and drill files, plans isolation milling and non-copper-clearing G-code with FlatCAM, sorts every hole into the bit you actually own, prints solder-mask negatives and cuts solder-paste stencils on the xTool machines, drills plated/non-plated holes and cuts the board outline on a Makera CNC, and even works out the electroplating bath recipe. All of it runs from a single command behind a live terminal UI.

[!NOTE] This tool is built around one specific bench: a Makera Carvera (Air) CNC, xTool M1 Ultra / F1 Ultra lasers, and a DIY copper electroplating setup. It's shared as-is. Nothing stops you using it, but you'll want to retune the config to your own hardware, tools, and chemistry before trusting the output to a machine.

Contents

• No support: use entirely at your own risk
• Installation
• Features
• How it works
• How this works, without the tool
• Prerequisites
• Usage
• Configuration
• Output layout
• Terminal experience
• Development

⚠️ No support: use entirely at your own risk

[!CAUTION] This project is provided strictly AS IS, with NO SUPPORT of any kind.

• No tech support. Issues opened to ask for help, setup assistance, or troubleshooting will not be answered and may be closed without comment.
• No bug guarantees. Even legitimate bug reports may never get a response or a fix. Don't assume one is coming.
• No warranty. Nothing here is promised to work, to keep working, or to be safe for your hardware, your materials, or you. You run it at your own risk.

This is a hobby project I share for free in my spare time. I have a full-time job and a life, and I'm not interested in spending my free time doing unpaid tech support; I don't want my hobby to become my job. If that's a problem for you, don't use this.

Pull requests with fixes are welcome, but I make no commitment to review, respond to, or merge them.

Installation

flatmaxx ships as a single, codesigned macOS arm64 (Apple Silicon) binary. Pick whichever install path you prefer.

Homebrew

brew tap brunostjohn/flatmaxxing https://github.com/brunostjohn/flatmaxxing
brew trust flatmaxx
brew install flatmaxx

Upgrade later with brew upgrade flatmaxx.

Install script

Downloads the latest release into ~/.local/bin, checksum-verified, using only standard macOS tools:

curl -fsSL https://raw.githubusercontent.com/brunostjohn/flatmaxxing/main/scripts/install.sh | sh

If ~/.local/bin isn't on your PATH, the script prints the exact line to add. Pin a version with FLATMAXX_VERSION=1.2.3, or change the target with FLATMAXX_INSTALL_DIR=.... Installed this way, flatmaxx update upgrades in place (see Updating).

From source

flatmaxx builds with Bun, the only thing you need.

git clone https://github.com/brunostjohn/flatmaxxing flatmaxx
cd flatmaxx
bun install
bun run build:native   # compile the native macOS accessibility module

Run it straight from source:

bun src/index.ts <kicad-project>

Or build the standalone, codesigned binary at dist/flatmaxx:

bun run build
./dist/flatmaxx <kicad-project>

Updating

If you installed via the script (or any binary in a writable location), upgrade in place:

flatmaxx update           # check for and install the latest release, with a progress bar
flatmaxx update --check   # only report whether a newer release exists

Homebrew installs are managed by brew; run brew upgrade flatmaxx instead.

Features

• One command, full pipeline: flatmaxx <project> runs every stage from board validation to machine-ready files.
• Isolation + non-copper clearing: FlatCAM-driven V-bit isolation routing and pocket clearing, exported as Carvera G-code per side.
• Drill categorization: parses the Excellon output, matches every hole to a bit you actually own, and warns on holes too small to machine.
• Solder mask & paste stencil: automates xTool Studio over the Chrome DevTools Protocol to import geometry and set power, speed, and passes per device.
• Drilling & edge cut: automates MakeraCAM via macOS Accessibility to drill plated/non-plated holes and cut the board outline with retaining tabs.
• Electroplating report: computes bath dimensions, current density, timing, and chemistry from your board bounds and recipe.
• Design rule checks: isolation feasibility (DRC) and drill machinability gates that can warn or hard-fail before any machine moves.
• Inline board preview: renders the board image right in your terminal (kitty / iTerm2 / sixel).
• Composable TOML config: project + user config with extends inheritance, deep merge, and per-run CLI overrides.

How it works

flatmaxx runs an ordered pipeline. Each stage feeds the next; you can disable the ones you don't need from config. If you don't have a Mac, or you want to know what each machine actually does to the board, HOW_THIS_WORKS.md walks the whole physical process with real parameters so you can replicate it with your own tools.

Prerequisites

[!IMPORTANT] macOS only. The laser and CNC stages rely on native macOS Accessibility automation and AppleScript, so flatmaxx does not run on Linux or Windows.

External software (only the stages you enable need their tools):

The xTool and MakeraCAM stages also require macOS Accessibility permission (System Settings → Privacy & Security → Accessibility) and a Chrome DevTools port open for xTool Studio (127.0.0.1:9333 by default).

[!TIP] Run flatmaxx doctor <project> before your first real build. It checks every required executable, app, and permission for your enabled stages and tells you exactly what's missing, without touching a machine.

Usage

Initialize a config in your KiCad project, then build:

flatmaxx init                 # create flatmaxxing.toml for the current project
flatmaxx ~/projects/myboard   # run the full pipeline

Commands

Examples

# Use an explicit config file
flatmaxx build . --config flatmaxxing.toml

# Override any config value for a single run
flatmaxx build . --set cnc.isolation.feedRate=150

# Point at a custom kicad-cli executable
flatmaxx ~/projects/myboard -k /opt/kicad/kicad-cli

# Check the board and config without launching any apps
flatmaxx validate . --fix

# See what clean would delete, without deleting it
flatmaxx clean . --dry-run

Configuration

flatmaxx reads a flatmaxxing.toml in the project, layered over a shared ~/flatmaxxing.user.toml. Configs can pull in others via extends, are deep-merged (later wins), and any value can be overridden per run with --set path=value / --unset path.

Rather than hand-writing the whole file, run flatmaxx init to scaffold one, then flatmaxx config for an interactive editor. Every option, with its default value and allowed values, is documented in flatmaxxing.example.toml. A representative slice covering your real tooling and isolation parameters:

extends = ["~/flatmaxxing.user.toml"]

[board]
file = "myboard.kicad_pcb"   # auto-detected if omitted

[cnc]
availableDrills = [
  { diameter = 0.4 }, { diameter = 0.5 }, { diameter = 0.7 },
  { diameter = 0.8 }, { diameter = 1.0 }, { diameter = 1.2 },
]
availableMills = [
  { diameter = 0.7 }, { diameter = 1.0 }, { diameter = 1.5 },
]

[cnc.isolation]
feedRate = 120
spindleSpeed = 15000
zCutDepth = 0.05
tool = { type = "vbit", diameter = 0.14, angle = 60 }
passes = 3
overlap = 60

Output layout

A full run writes machine-ready files into your project (folders are configurable under [paths]):

myboard/
├── gerbers/    # KiCad Gerber + edge-cut DXF exports
├── drills/     # categorized Excellon drill files (one per bit)
├── gcodes/     # isolation + non-copper-clearing G-code (Carvera)
├── dxf/        # board outline DXFs
├── png/        # rendered board & mask images
├── svg/        # vector solder-mask art
├── xtool/      # xTool Studio projects (solder mask + stencil)
└── cnc/        # MakeraCAM projects + exported drilling/contour G-code

The electroplating bath report (dimensions, current density, timing, chemistry) is generated alongside.

Terminal experience

flatmaxx runs on an Ink UI: a live, hierarchical task list shows every stage and substep with spinners, progress bars, and inline error detail. When your terminal supports it (kitty, iTerm2, or sixel), the rendered board image is drawn directly in the scrollback so you can eyeball the layout before any machine moves.

Development

bun run dev         # build native + run against the bundled testdir/ project
bun test            # run the test suite
bun run typecheck   # type-check with tsgo
bun run format      # format with Biome

The codebase is built on Effect v4 and follows the conventions in CLAUDE.md; the native macOS accessibility bindings live in the Rust workspace under native/.