understanding-architecture

Stars16

Forks0

UpdatedApril 1, 2026 at 09:12

Understand clawctl's architecture and design decisions. Use when exploring the codebase structure, understanding package responsibilities, learning about the VM backend, mount system, onboarding flow, or making cross-cutting changes.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Source

TimBeyer

TimBeyer/clawctl

View GitHub Repository View Creator Repositories

Download

Related occupationsSOC

Based on SOC occupation classification

Computer Systems AnalystsComputer and Mathematical Occupations·SOC 15-1211

File Explorer

2 files

SKILL.md

readonly

More from this repository

same repository

adding-cli-commands

TimBeyer/clawctl

Add new CLI commands to clawctl. Use when creating a new command, subcommand group, or modifying the CLI surface. Ensures all touchpoints are updated: handler, exports, commander wiring, README, shell completions, and tests.

2026-04-0116

developing-vm-cli

TimBeyer/clawctl

Develop the guest CLI (claw) that runs inside the VM. Use when working on vm-cli commands, the JSON output protocol, doctor checks, CapabilityContext implementation, or the capability registry.

2026-04-0116

extending-capabilities

TimBeyer/clawctl

Write and extend VM provisioning capabilities for clawctl. Use when adding new tools to the VM, modifying the provisioning pipeline, writing CapabilityDef modules, or working with lifecycle hooks and CapabilityContext SDK.

2026-04-0116

managing-provisioning

TimBeyer/clawctl

Understand and modify the VM provisioning workflow. Use when working on the host-side provisioning sequence, understanding what each phase installs, debugging provisioning failures, or modifying the idempotency/verification flow.

2026-04-0116

name	understanding-architecture
description	Understand clawctl's architecture and design decisions. Use when exploring the codebase structure, understanding package responsibilities, learning about the VM backend, mount system, onboarding flow, or making cross-cutting changes.

Understanding the Architecture

clawctl is a CLI for creating and managing OpenClaw gateways on macOS. Each instance is a Lima VM provisioned and managed from the host.

Package responsibilities

Package	Role
`types`	Shared types, schemas, constants
`templates`	Lima config generators (lima-yaml.ts)
`capabilities`	Capability definitions + runner + state tracking
`host-core`	Host-side library (drivers, provisioning, registry)
`cli`	Host CLI (Ink wizard + commands)
`vm-cli`	Guest CLI (claw) — runs inside the VM

Key design decisions

Internal CLI (claw) — compiled TypeScript binary in the VM; same language on both sides; structured JSON output
Capabilities — self-contained provisioning modules with lifecycle hooks, dependency resolution, state tracking, and migrations
vz backend — Apple Virtualization.framework for near-native performance on Apple Silicon
virtiofs mounts — project dir (read-only) + data dir (writable) survive VM rebuilds
Delegate to OpenClaw — wrap their installer/onboarding, don't reimplement

Two modes

Interactive wizard — Ink UI collects config, steps advance via onComplete callbacks
Headless — config-file-driven, no prompts

Full reference

See references/architecture.md for the complete documentation including directory structure, component relationships, onboarding approach, and error handling.