woodshop/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

WoodShop - Voice-driven conversational 3D woodworking & furniture modeler. Speak (or type) commands like "place a 6 foot 2x4, sand it, attach a 2 foot 2x4 at 90 degrees 10 inches from the end" and watch the model build in a live 3D viewport — Holodeck-style.

Architecture

Design principle: reuse existing CmdForge tools for everything that isn't woodshop-specific; don't reinvent voice/AI plumbing.

woodshop-talk (driver.py) ── the conversational loop
   │  dictate ............... speech→text         (CmdForge tool, reused)
   │  pa-load-tools ......... wood-* → Claude schemas (reused)
   │  claude -p ............. interpret utterance → JSON tool calls (reused provider)
   │  pa-execute-tool ....... dispatch each wood-* tool (reused)
   │  read-aloud ........... speak confirmation   (reused)
   ▼
scene.json  ← single source of truth (parts, joints, selection, undo stack)
   ▲                                   │ writes
   │ reads/mutates                     ▼
wood-* CmdForge tools          woodshop-view (viewer.py)
(place/join/sand/delete/undo)  watches scene.json → live pyvista 3D
thin wrappers over `woodshop` CLI

Only woodshop-specific code lives in this repo: the scene model (scene.py), nominal→actual lumber table (lumber.py), length parsing (units.py), the woodshop CLI (cli.py), build123d geometry + STL/STEP export (geometry.py), the pyvista viewport (viewer.py), and the driver (driver.py). The driver uses Claude (not pa-tool-loop, which hard-wires a small local model) for reliable structured tool-calling.

Entry points

Command	Purpose
woodshop (no args) / woodshop-gui	The unified desktop studio (viewport + parts panel + command bar)
woodshop <op>	CLI ops: place, join, stand, lay, rotate, move, trim, copy, rename, sand, delete, select, undo, redo, clear, status, cutlist, export, render, save, open, projects
woodshop-view	Standalone live 3D viewport (watches scene.json; labels, grid, isometric)
woodshop-talk	Standalone conversational driver (--voice for mic, --once "..." for one command)

The studio (src/woodshop/gui/) is a thin PySide6 shell over the same Scene + operations + interpreter:

• controller.py — one in-memory Scene; buttons/menus call typed methods, voice/typed commands go through driver.interpret and are applied via execute_call, which reuses the CLI command functions (no behavioral drift). Every mutation saves to disk and emits changed.
• viewport.py — embedded pyvistaqt.QtInteractor; click a board to select.
• panels.py — parts list (ExtendedSelection: Ctrl/Shift multi-select) + selected-part inspector (editable length/yaw/tilt) + quick-action buttons. command_bar.py — text + push-to-talk + transcript, with slow work (LLM/dictate/TTS) on a QThreadPool (workers.py).
• numpad.py — a numberpad control panel (2/4/6/8 move, 1/3/7/9 rotate, +/− raise/lower, 0/. front/iso, 5 fit) that also responds to the physical numpad keys (MainWindow.keyPressEvent forwards them when not typing).
• Multi-selection: controller.selected is a list driven by 3D Ctrl+click (viewport.picked carries an additive flag) and list multi-select. Group ops (move_selected/rotate_selected/stand/lay/sand/delete) apply to all selected in one undo step via scene.batch(). Voice "move these" works because the selected ids are fed into the interpreter prompt.

Scene file location: $WOODSHOP_SCENE or ~/.local/share/woodshop/scene.json. Named projects: ~/.local/share/woodshop/projects/<slug>.json.

Parts have full 3D orientation (yaw_deg/tilt_deg/roll_deg) so legs and uprights stand vertically. Parts can be referred to by id (p1) or by a name set with rename. The cut list (cutlist.py) reports board-feet and an 8'-stick shopping estimate.

CmdForge tools (the documented command vocabulary)

wood-place, wood-join, wood-sand, wood-delete, wood-undo live in ~/.cmdforge/<name>/ and wrap the woodshop CLI. Regenerate them with /tmp/gen_wood_tools.py (kept in the repo plan) if their schemas change. The arg descriptions ARE the LLM's documentation, so keep them clear.

Setup

python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[viewer,dev]"   # viewer extra pulls build123d + pyvista
pytest                            # 25 tests

Known limitations / next steps

1. Joins are flush butt joints: B's end sits flush against A's surface, and B is aligned to A's reference corner (top faces level + one side flush) rather than centered. The flush corner is fixed (A's +width/+thick side; no per-join choice of which corner / centered).
2. Joinery features (Feature on each Part) are parametric ops applied in geometry.part_solid: tenon fuses a protruding tongue; mortise/hole/ slot/dado/rabbet cut a box/cylinder into a face; chamfer bevels the edges around a face via build123d chamfer() (handled specially — _apply_chamfer, with a try/except fallback for over-sized bevels). The viewport tessellates featured boards (plain boards stay fast pyvista boxes). Edit paths: CLI feature/feature-edit/feature-delete/features; voice wood-feature/wood-feature-delete; GUI Joinery tab (feature_panel.py) — add-with-default, then dragging a field shows a live red preview ghost (viewer.feature_preview_mesh — a cheap box/cylinder, no re-tessellation) of the pending change over the committed feature; Apply commits it (controller.set_preview/apply_preview, preview_changed signal → viewport.set_preview). Per-kind hints + field tooltips explain the parameters. controller.active_feature is the one being edited. A Fit to mate… button (controller.fit_feature) resizes a mortise to a chosen tenon (or vice versa) — pocket = tongue + clearance (1/32"), pocket slightly deeper; a dialog lists the complementary features (features_of_kind). The dialog's Make connection checkbox calls controller.make_connection → scene.connect(anchor, moving), which moves/orients the moving feature's board so the tenon seats into the mortise (faces meet, axes aligned). Connect builds the target world rotation from the feature frames and decomposes it to the board's yaw/tilt/roll via matrix_to_ypr (inverse of Part.local_frame's Rz·Ry(-tilt)·Rx(roll)); Part.feature_world_frame gives each feature's world point/normal/u/v. Features also have rotation_deg (spin about the face normal) to line up cross-sections. CLI connect; voice wood-connect. Not yet: countersinks, click-a-face-to-place.
3. Latency ~7–13s per utterance (one claude -p call).
4. Voice path (--voice) reuses dictate; the driver loop is hardened against failures but the mic path isn't exercised in the unit tests.
5. Auto-placement of parts in a multi-step "build a table" request depends on the LLM choosing good offsets; geometry is correct but corners may need nudging.

⚠️ CRITICAL: Updating Todos, Milestones, and Goals

DO NOT edit todos.md, milestones.md, or goals.md files directly.

These files are managed by Development Hub which has file watchers and sync logic. Direct edits will be overwritten or cause conflicts.

Use the devhub-tasks CLI instead:

# Status overview
devhub-tasks status woodshop

# Add todos
devhub-tasks todo add woodshop "Task description" --priority high --milestone M1

# Complete todos (by text match or ID number)
devhub-tasks todo complete woodshop "Task description"
devhub-tasks todo complete woodshop 3

# List todos
devhub-tasks todo list woodshop

# Add milestones
devhub-tasks milestone add woodshop M2 --name "Milestone Name" --target "March 2026"

# Complete milestones (also completes linked todos)
devhub-tasks milestone complete woodshop M1

# Goals
devhub-tasks goal add woodshop "Goal description" --priority high
devhub-tasks goal complete woodshop "Goal description"

Use --json flag for machine-readable output. Run devhub-tasks --help for full documentation.

Files you CAN edit directly: overview.md, architecture.md, README.md, and any other docs.

Development Commands

# Install for development
pip install -e ".[dev]"

# Run tests
pytest

# Run a single test
pytest tests/test_file.py::test_name

Architecture

TODO: Describe the project architecture

Key Modules

TODO: List key modules and their purposes

Key Paths

• Source code: src/woodshop/
• Tests: tests/
• Documentation: docs/ (symlink to project-docs)

Documentation

Documentation lives in docs/ (symlink to centralized docs system).

Before updating docs, read docs/updating-documentation.md for full details on visibility rules and procedures.

Quick reference:

• Edit files in docs/ folder
• Use public: true frontmatter for public-facing docs
• Use <!-- PRIVATE_START --> / <!-- PRIVATE_END --> to hide sections
• Deploy: ~/PycharmProjects/project-docs/scripts/build-public-docs.sh woodshop --deploy

Do NOT create documentation files directly in this repository.