trebuchet

Trebuchet Plugin for Claude Code

Expert assistance for Trebuchet distributed actor framework development.

What is Trebuchet?

Trebuchet is a Swift 6.2 distributed actor framework that makes RPC stupid simple. Define actors once and use them seamlessly whether they're local or remote, in-process or deployed to AWS Lambda.

What This Plugin Provides

This plugin gives Claude Code deep expertise in Trebuchet through:

📚 Skills (9 total)

Documentation organized as discoverable skills that Claude automatically uses when relevant:

• getting-started - Installation, setup, basic actor patterns
• distributed-actors - Best practices for defining actors
• streaming - Real-time state synchronization with @StreamedState
• swiftui-integration - Reactive SwiftUI integration
• cloud-deployment - Serverless deployment architecture
• aws-lambda - AWS Lambda deployment guide
• cli - Trebuchet CLI commands and workflows
• security - Authentication, authorization, rate limiting
• observability - Logging, metrics, distributed tracing

🤖 Specialized Agent

The trebuchet-expert agent provides comprehensive guidance on:

• Setting up new projects
• Debugging distributed actor issues
• Designing actor architectures
• Configuring cloud deployments
• Optimizing performance and costs
• Implementing security and observability

Claude automatically delegates Trebuchet questions to this agent.

Installation

Using Claude Code CLI

# Clone the plugin repository
git clone https://github.com/briannadoubt/trebuchet-plugin

# Install locally
claude plugin add ./trebuchet-plugin

Enable in Settings

Add to your Claude Code settings:

{
  "enabledPlugins": {
    "trebuchet@briannadoubt": true
  }
}

Usage

Automatic Skill Invocation

Claude automatically uses relevant skills when you:

Ask: "How do I get started with Trebuchet?"
→ Invokes getting-started skill

Ask: "How do I add streaming to my actor?"
→ Invokes streaming skill

Ask: "Deploy my actors to AWS"
→ Invokes aws-lambda and cli skills

Explicit Agent Invocation

For comprehensive guidance, explicitly invoke the expert agent:

"Use trebuchet-expert to help me design my actor system"
"Ask the trebuchet-expert about optimizing my deployment"

Working with Your Code

When you're working in a Trebuchet project, Claude will:

• Automatically recognize Trebuchet code
• Use relevant skills for context
• Suggest best practices
• Help debug issues
• Assist with deployments

Example Interactions

Setting Up a New Project

You: "Help me create a new Trebuchet project for a real-time game server"

Claude (using getting-started and distributed-actors skills):

• Guides you through installation
• Helps define your actors
• Sets up server and client code
• Suggests architecture patterns

Adding Streaming

You: "Add real-time state streaming to my GameRoom actor"

Claude (using streaming skill):

• Adds @StreamedState to your actor
• Shows SwiftUI integration with @ObservedActor
• Configures stream resumption
• Suggests filtering and delta encoding for optimization

Deploying to AWS

You: "Deploy my actors to AWS Lambda"

Claude (using aws-lambda and cli skills):

• Creates or updates trebuchet.yaml
• Explains AWS resources
• Runs trebuchet deploy --dry-run
• Executes deployment
• Provides client connection instructions

Adding Security

You: "Add API key authentication to my actors"

Claude (using security skill):

• Adds TrebuchetSecurity dependency
• Configures APIKeyAuthenticator
• Shows middleware integration
• Adds rate limiting

Skills Reference

Each skill provides comprehensive documentation on its topic:

Skill	Description
getting-started	Installation, first actors, server/client setup
distributed-actors	@Trebuchet macro, method requirements, error handling
streaming	@StreamedState, @ObservedActor, resumption, filtering
swiftui-integration	Connection management, @RemoteActor, reconnection
cloud-deployment	CloudGateway, providers, service discovery, state stores
aws-lambda	AWS deployment, DynamoDB, CloudMap, WebSocket streaming
cli	trebuchet init/deploy/status/undeploy/dev commands
security	Authentication, authorization, rate limiting, validation
observability	Logging, metrics, tracing, CloudWatch integration

Plugin Structure