{"id":34827224,"url":"https://github.com/darwin/supex","last_synced_at":"2026-04-28T03:04:00.442Z","repository":{"id":326694979,"uuid":"1002671260","full_name":"darwin/supex","owner":"darwin","description":"SketchUp meets AI Agents","archived":false,"fork":false,"pushed_at":"2026-04-25T15:01:58.000Z","size":6232,"stargazers_count":24,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-25T17:11:25.159Z","etag":null,"topics":["agentic-ai","claude-code","sketchup"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/darwin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-16T00:29:04.000Z","updated_at":"2026-04-22T08:30:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/darwin/supex","commit_stats":null,"previous_names":["darwin/supex"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/darwin/supex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darwin%2Fsupex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darwin%2Fsupex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darwin%2Fsupex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darwin%2Fsupex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/darwin","download_url":"https://codeload.github.com/darwin/supex/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/darwin%2Fsupex/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32364094,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-27T20:07:02.737Z","status":"online","status_checked_at":"2026-04-28T02:00:07.250Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","claude-code","sketchup"],"created_at":"2025-12-25T15:18:57.991Z","updated_at":"2026-04-28T03:04:00.438Z","avatar_url":"https://github.com/darwin.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003e **Note**: Unless you explicitly switched, you are viewing the `main` branch which contains stable releases. Active development happens on the [`dev` branch](https://github.com/darwin/supex/tree/dev).\n\n![Supex Hero](assets/supex-hero-poster.jpeg)\n\n# Supex: SketchUp Automation for Agentic Coding\n\nAn experimental platform that brings [agentic coding](https://www.claude.com/blog/introduction-to-agentic-coding) to [SketchUp](https://www.sketchup.com). Describe what you want to build in natural language, and let AI write and execute Ruby scripts directly in SketchUp. Designed for programmers who want to augment their 3D modeling workflow with AI assistance and direct API access.\n\n\u003e **Early Stage Project**: Supex is in very early development, tested only on macOS with [Claude Code](https://claude.ai/code) and the latest SketchUp version. Programmers with existing agentic coding experience will get the most out of it.\n\n## Motivation\n\nI'm Antonin, a programmer who discovered the power of agentic coding. Working with Claude Code on git-versioned projects changed how I think about software development - describing intent in natural language, iterating rapidly, and having full history of every change.\n\nWhen I started a SketchUp project for my house renovation, I wondered if similar workflow could be used. Not to replace direct modeling in SketchUp's GUI - that's still the best way to sketch ideas and make quick adjustments. But for repetitive tasks, parametric designs, and complex geometry, I wanted to describe what I need and let AI figure out the Ruby code.\n\nSupex bridges these two worlds: keep using SketchUp's intuitive interface for direct manipulation, while having AI handle the scripting when you need precision, automation, or just want to say \"create a staircase with 15 steps\" instead of drawing it manually.\n\n## Contents\n\n- [Key Features](#key-features)\n- [Architecture Overview](#architecture-overview)\n- [Project-Based Workflow](#project-based-workflow)\n- [Installation \u0026 Setup](#installation--setup)\n- [Quick Start](#quick-start)\n- [Development](#development)\n- [Reference](#reference)\n\n## Key Features\n\n### Direct Ruby API Access\n- **Full SketchUp Ruby API**: Execute any SketchUp operation via Ruby code\n- **eval_ruby \u0026 eval_ruby_file**: Run code inline or from project scripts\n- **Unlimited Flexibility**: No constraints on what you can create or modify\n\n### Model Introspection\n- **Entity Inspection**: List and examine faces, edges, groups, components with details\n- **Visual Verification**: Take screenshots to verify modeling results\n- **Selection \u0026 Context**: Inspect currently selected entities\n- **Materials \u0026 Layers**: Browse materials and layers in the model\n- **Camera Information**: Query current view position and settings\n- **Model Statistics**: Get comprehensive model state without writing code\n\n### Project-Based Workflow\n- **Scripts in Your Repository**: Ruby files live in your project directory structure\n- **Version Control Ready**: Full git integration for modeling scripts\n- **IDE Support**: Edit scripts with syntax highlighting and RuboCop\n- **Modular Organization**: Separate scripts for different features and utilities\n- **Export Capabilities**: SKP, OBJ, STL, PNG, JPG formats\n\n## Architecture Overview\n\nSupex bridges AI agents and CLI tools with SketchUp through a client-server architecture:\n\n![Architecture Overview](assets/supex-architecture-poster.jpeg)\n\n**Client-Side Components (Python):**\n\n- **Driver** (`./mcp`) - [MCP](https://modelcontextprotocol.io) server for AI agent integration (FastMCP framework)\n- **CLI** (`./supex`) - Command-line interface for direct interaction\n- **REPL** (`./repl`) - Interactive Ruby console for development\n\n**SketchUp-Side Components (Ruby):**\n\n- **Supex Runtime** - Bridge server accepting JSON-RPC connections on ports 9876 (MCP/CLI) and 4433 (REPL)\n- **Supex StdLib** - Helper library for common SketchUp operations\n- **SketchUp API** - Native Ruby API for 3D modeling\n\n**Communication**: JSON-RPC 2.0 over TCP sockets (localhost:9876 for MCP/CLI, localhost:4433 for REPL) enables execution of Ruby code directly in SketchUp's context.\n\nFor more details, see [Architecture](docs/architecture.md).\n\n## Project-Based Workflow\n\nSupex enables a **project-based workflow** where Ruby scripts live in your git-versioned project directories, treating 3D modeling code like application code:\n\n```\nyour-project/\n├── src/\n│   ├── create_table.rb    # Create base geometry\n│   ├── add_details.rb     # Add decorative elements\n│   └── materials.rb       # Apply materials\n├── models/\n│   └── project.skp\n└── .mcp.json              # MCP client configuration\n```\n\n### Development Cycle\n\n```bash\n# 1. Launch SketchUp with Supex extension\ncd /path/to/supex\n./scripts/launch-sketchup.sh\n\n# 2. Execute scripts (use absolute paths)\n./supex eval-file /path/to/your-project/src/create_table.rb\n\n# 3. Verify results\n./supex info\n./supex screenshot\n\n# 4. Iterate - edit script and re-run\n```\n\nFor AI-driven development, Claude Code handles paths automatically via MCP tools.\n\n### Benefits\n\n- **Version Control**: Modeling code tracked in git\n- **IDE Integration**: Syntax highlighting, autocomplete, linting\n- **Team Collaboration**: Multiple people can work on scripts\n- **Code Reusability**: Share scripts across projects\n- **Proper Errors**: Line numbers and stack traces point to actual files\n\n### AI-Driven Development\n\nThis workflow is ideal for Claude Code:\n\n1. **AI writes Ruby scripts** (in your git-versioned project)\n2. **AI executes scripts** using `eval_ruby_file` tool via MCP\n3. **AI verifies results** using introspection tools via MCP:\n    - `get_model_info()` - Entity counts and state\n    - `take_screenshot()` - Visual verification\n    - `list_entities()` - Geometry inspection\n4. **AI iterates** based on verification feedback\n\n## Installation \u0026 Setup\n\n### Requirements\n\n- **SketchUp 2026** - Download from [sketchup.com](https://www.sketchup.com)\n    - Only the latest SketchUp version is tested\n    - Project is experimental - no backward compatibility guarantees\n- **Claude Code** - AI-powered development environment from [claude.ai/code](https://claude.ai/code)\n    - Only tested with Claude Code (experimental project)\n    - Other MCP-compatible AI agents might work but are untested\n- **macOS** - Currently the primary supported platform\n- **Python 3.14+** - For the MCP driver (managed via UV)\n- **Ruby 3.2.2** - Same as the Ruby version bundled with SketchUp 2026\n\n\n### 1. Clone the Repository\n\n```bash\ngit clone https://github.com/darwin/supex.git\ncd supex\n```\n\n### 2. Launch SketchUp with Extension\n\nThe development launcher handles extension deployment automatically:\n\n```bash\n./scripts/launch-sketchup.sh path/to/your/model.skp\n```\n\nThis script:\n- Launches the installed SketchUp app\n- Deploys Ruby extension sources directly (no .rbz building required)\n- Enables live reloading during development\n- Optionally opens a model given as parameter  \n\n### 3. Configure Claude Code\n\nAdd Supex MCP server to your project:\n\n```bash\nclaude mcp add supex -- /path/to/supex/mcp\n```\n\nReplace `/path/to/supex/mcp` with the actual path to your Supex installation.\n\n### 4. Verify Connection\n\n```bash\n./supex status\n```\n\nYou should see connection status and SketchUp version information.\n\n## Quick Start\n\nFor a complete step-by-step tutorial, see the **[Simple Table Example](https://github.com/darwin/supex/tree/example-simple-table)**.\n\nExample projects live in separate orphan branches. To clone an example:\n\n```bash\ngit clone -b example-simple-table https://github.com/darwin/supex.git simple-table\ncd simple-table\n```\n\nThe example covers:\n1. Project setup and configuration\n2. Creating geometry with Ruby scripts\n3. Using introspection tools to verify results\n4. Iterative development workflow\n\n## Development\n\nRun tests and linters from the repository root:\n\n```bash\n# Run all unit tests (driver, stdlib, runtime)\n./scripts/launch-tests.sh\n\n# Run all tests including E2E (requires SketchUp running)\n./scripts/launch-tests.sh --e2e\n\n# Run all linters (RuboCop, ruff, mypy)\n./scripts/lint.sh\n```\n\nIf you have [mise](https://mise.jdx.dev/) installed:\n\n```bash\nmise run test       # Unit tests\nmise run test:e2e   # All tests including E2E\nmise run lint       # All linters\n```\n\n## Reference\n\n- **[CLI Reference](docs/cli.md)** - Command-line interface for direct SketchUp interaction\n- **[Interactive REPL](docs/repl.md)** - Interactive Ruby development in SketchUp\n- **[MCP Reference](docs/mcp.md)** - Tools available for AI agents (Claude Code)\n- **[Configuration](docs/configuration.md)** - Environment variables and settings\n- **[Protocol](docs/protocol.md)** - JSON-RPC communication protocol details\n- **[Security](docs/security.md)** - Authentication, path restrictions, and recommendations\n- **[Troubleshooting](docs/troubleshooting.md)** - Common issues and solutions\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdarwin%2Fsupex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdarwin%2Fsupex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdarwin%2Fsupex/lists"}