PenguinClaw embeds an AI agent directly into Rhino 8 as a dockable panel. The model is given a lean, curated tool set — execute_python_code for all geometry and edits, a single run_rhino_command passthrough to every Rhino command (980+, including third-party plugins), Grasshopper build/inspect tools, and a viewport vision loop — and a live snapshot of the scene (units, current selection with IDs, object inventory) is injected into every turn, so the agent always knows what it is working on. Replies stream token-by-token, with tool calls shown live as they run. The agent loop runs in-process inside Rhino with direct RhinoCommon API access. Grasshopper components are auto-indexed at startup and keyword-matched per request, so the five most relevant GH tools are always available without bloating the context window.
"Build a 10×10×10 box, fillet the top edges at radius 2,
then Boolean union it with a sphere at the top"
No scripting. No macros. Just natural language.
Rhino 8 (C# plugin)
├── Embedded HTTP server — React UI at localhost:8080; /chat streams NDJSON events
├── AI agent loop — streaming tool-use loop (retry + cancellation + loop detection)
├── Live scene context — units + selection + object inventory injected every turn
├── Lean tool layer — 14 curated tools; run_rhino_command passthrough (980+ commands)
├── GH component registry — auto-indexed, keyword-matched top-5 per turn
└── Vision layer — capture_and_assess injects viewport images into model context
Agent loop — each message runs a tool-use loop: the AI receives the message + live scene context + tool definitions, streams text and returns tool calls, tools execute on the Rhino UI thread, results feed back into the next turn. Text and tool calls are streamed to the UI live (chunked NDJSON). Continues until the model returns end_turn or after 25 iterations, with loop detection and malformed-response recovery in between.
Tool selection — the model is offered 14 curated tools. All object transforms (move/scale/rotate/mirror/array/boolean/colour/layer/rename/delete) go through execute_python_code with rhinoscriptsyntax rather than as separate schemas. A single run_rhino_command tool covers every Rhino command. The GH component registry (hundreds of entries) is keyword-matched against the message and the top 5 are appended per request, keeping the per-request tool list small and stable.
Live scene context — a compact snapshot (document units, the current selection with full GUIDs, and an object inventory) is injected into every turn, so "scale it" / "put it on top" resolve without a wasted scene-query round-trip.
Thread safety — all RhinoDoc / RhinoApp calls are dispatched to the UI thread via RhinoApp.InvokeOnUiThread + ManualResetEventSlim. The HTTP server and agent loop run on background threads.
Prompt caching — when using Anthropic, the system prompt, tool definitions, scan context, and the message history are marked cache_control: ephemeral. After the first request, cached blocks cost ~10% of their normal price, and multi-step tool loops reuse the growing prefix instead of re-billing the whole conversation each step.
See AGENTS.md for a full technical reference.
| 🤖 Full Rhino access | Any built-in command via natural language (_Box, _Loft, _FilletEdge, …) |
| 🌿 Grasshopper integration | List/set sliders, enumerate canvas components, build definitions programmatically with build_gh_definition (slider, panel, toggle, component, python3, sdk types); solve_gh_definition; bake_gh_definition |
| ⚡ Live streaming | Replies stream token-by-token; tool calls appear and complete live in an interleaved build log, not one dump at the end |
| 🧠 Live scene awareness | Units, current selection (with IDs), and an object inventory are injected every turn — "scale it", "move that", "put it on top of the box" resolve without extra tool calls |
| 🐍 Python-first editing | execute_python_code (RhinoCommon + rhinoscriptsyntax) is the primary path for creating geometry and for all transforms, booleans, colour, and layer edits — returns object IDs directly |
| 📐 Geometry inspection | get_scene_layout, get_object_info — bounding boxes, volumes, and areas on demand |
| 📸 Viewport capture | Captures the active Rhino viewport at its actual resolution |
| 👁 Vision loop | capture_and_assess injects a live viewport screenshot into the AI context for visual verification after modeling steps |
| 💬 Persistent history | Chat history and action log survive panel reloads and Rhino restarts |
| 🔍 Dynamic GH registry | Rebuilt on startup and after PenguinClawScan; picks up third-party plugins automatically |
- Rhino 8 for Windows or Mac (RhinoCommon
.NET 4.8) - An AI provider — choose one from the table below (configured inside the plugin)
1. Install the plugin — drag PenguinClaw.rhp onto the Rhino viewport, or use PluginManager → Install.
2. Open the panel — run the PenguinClaw command in Rhino.
3. Choose a provider — the Settings tab opens automatically on first launch. Enter your API key and click Save & Connect.
4. (Optional) Run PenguinClawScan to deep-index your installed Grasshopper components.
| Provider | Cost | Tool-calling quality | Setup |
|---|---|---|---|
| Anthropic (default) | ~$1–2/month daily use | Best | Free account + API key |
| Groq | Free tier (14,400 req/day) | Good | Free account + API key |
| Ollama | Free, always | Good on large models | Install Ollama + pull a model |
- Sign up at console.anthropic.com — pay-as-you-go, no subscription
- Go to API Keys → Create Key → copy the key (
sk-ant-...) - In PenguinClaw → Settings tab → select Anthropic → paste the key → Save & Connect
- Sign up at console.groq.com — free, no credit card
- Go to API Keys → Create API Key → copy the key (
gsk_...) - In PenguinClaw → Settings tab → select Groq → paste the key → Save & Connect
- Install Ollama from ollama.com
- Open a terminal and run:
ollama pull qwen2.5:7b(~4.7 GB download) - In PenguinClaw → Settings tab → select Ollama → Save & Connect
For complex multi-step tasks (Grasshopper definition building, boolean chains), Anthropic gives the most reliable results. See AGENTS.md for a detailed comparison.
- .NET 4.8 SDK (Windows) or .NET 8 SDK (Mac builds use Mono)
- Node.js 18+
- Rhino 8 installed (provides the RhinoCommon reference)
# 1. Clone
git clone https://github.com/LCS3002/PenguinClaw-Rhinoceros.git
cd PenguinClaw-Rhinoceros
# 2. Build the React UI
cd penguinclaw/ui
npm install
npm run build
# 3. Build the C# plugin
cd ../rhino_plugin
dotnet build PenguinClaw.csproj -c Release
# 4. Load into Rhino
# Drag bin/Release/net48/PenguinClaw.dll onto Rhino (or rename to .rhp first)
# Run: PenguinClawpenguinclaw/
├── rhino_plugin/
│ ├── PenguinClawPlugin.cs # Plugin entry point, panel registration
│ ├── PenguinClawPanel.cs # Eto dockable panel + WebView host (Win+Mac)
│ ├── PenguinClawServer.cs # Embedded HTTP server (port 8080); /chat streams NDJSON + /stop
│ ├── PenguinClawAgent.cs # Streaming tool-use loop, live scene context, cancellation
│ ├── LlmProviders.cs # ILlmProvider + Anthropic / Groq / Ollama, SSE streaming + retry
│ ├── PenguinClawTools.cs # Tool registry (14 curated tools offered; all remain callable)
│ ├── RhinoCommandRegistry.cs # GH component index + keyword matcher
│ ├── PenguinClawActionLog.cs # Persistent action log + retry/recovery events
│ ├── PenguinClawScanCommand.cs # PenguinClawScan — deep GH component index
│ └── www/ # Embedded React build
├── PenguinClaw.Tests/ # xUnit test project (net8.0, no Rhino needed) — 96 tests
│ ├── ProviderTests.cs # Providers, retry policy, factory, friendly errors
│ ├── SchemaValidationTests.cs # Tool schema validation
│ ├── SseParserTests.cs # Anthropic + OpenAI streaming (SSE) parsers
│ ├── MessageCacheTests.cs # Prompt-cache breakpoint on message history
│ ├── AgentLoopTests.cs # History trim, OpenAI message conversion, result structure
│ └── KeywordMatcherTests.cs # Tokenizer and relevance-scoring logic
└── ui/
└── App.jsx # React chat UI — light Raven design, streaming build log, drawer
See CONTRIBUTING.md.
MIT — see LICENSE.