ReddRadar
Agent skill
debug-connection
Debug WebSocket connection issues between CLI and FigJam plugin. Use when diagrams aren't syncing or connection fails.
Install this agent skill to your Project
npx add-skill https://github.com/aiskillstore/marketplace/tree/main/skills/7nohe/debug-connection
SKILL.md
WebSocket Connection Debugging
Architecture
┌─────────────┐ WebSocket ┌─────────────────┐ postMessage ┌─────────────────┐
│ CLI serve │ ◄───────────────► │ Plugin UI │ ◄───────────────► │ Plugin Main │
│ (Bun) │ ws://...:3456 │ (ui.ts) │ │ (code.ts) │
└─────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
│ File watcher │ Browser APIs │ Figma API
│ YAML parsing │ WebSocket client │ Canvas rendering
└───────────────────────────────────┴─────────────────────────────────────┘
Common Issues & Solutions
1. Connection Refused
Symptoms: Plugin shows "Connecting..." indefinitely
Check:
# Is CLI serve running?
ps aux | grep "figram serve"
# Check port availability (default: 3456)
lsof -i :3456
Solution: Start CLI with bun run packages/cli/src/index.ts serve diagram.yaml
2. Connection Drops
Symptoms: Works initially, then stops syncing
Check:
- Plugin UI console for WebSocket close events
- CLI terminal for error messages
Solution: Check for YAML parse errors blocking updates
3. Patches Not Applied
Symptoms: Connected but canvas doesn't update
Debug steps:
- Check CLI output for patch generation
- Check Plugin UI console for received messages
- Check Plugin Main console for rendering errors
4. YAML Parse Errors
Symptoms: CLI shows validation errors
Solution: Validate YAML syntax and schema compliance
5. Secret Mismatch
Symptoms: Connection established but immediately closed
Check: Ensure --secret flag value matches between CLI and plugin
6. JSON Import Errors
Symptoms: Import dialog shows an error alert
Check:
- JSON must be an object
- DSL JSON requires
version,docId, andnodesarray - IR JSON requires
version,docId, andnodesobject
Solution: Fix validation errors shown in the alert (path + message)
Debugging Tools
CLI Side
# Run with verbose output
DEBUG=* bun run packages/cli/src/index.ts serve diagram.yaml
# Specify custom port
bun run packages/cli/src/index.ts serve diagram.yaml --port 8080
# With authentication
bun run packages/cli/src/index.ts serve diagram.yaml --secret mysecret
Plugin UI Side
- Right-click plugin UI → Inspect
- Check Console for WebSocket events
- Check Network tab for WS frames
Plugin Main Side
- Figma Desktop → Plugins → Development → Open console
- Check for rendering errors
WebSocket Protocol
Plugin → CLI Messages
// Connection initiation
interface HelloMessage {
type: "hello";
docId: string;
secret?: string; // If server requires authentication
}
// Request full sync (e.g., after reconnection)
interface RequestFullMessage {
type: "requestFull";
docId: string;
}
CLI → Plugin Messages
// Full document sync
interface FullMessage {
type: "full";
rev: number; // Current revision number
ir: IRDocument; // Complete normalized document
}
// Incremental update
interface PatchMessage {
type: "patch";
baseRev: number; // Expected current revision
nextRev: number; // New revision after applying
ops: PatchOp[]; // Operations to apply
}
// Error notification
interface ErrorMessage {
type: "error";
message: string;
}
Patch Operations
type PatchOp =
| { op: "upsertNode"; node: IRNode }
| { op: "removeNode"; id: string }
| { op: "upsertEdge"; edge: IREdge }
| { op: "removeEdge"; id: string };
Quick Diagnostic
# 1. Start CLI serve (default port: 3456)
bun run packages/cli/src/index.ts serve examples/diagram.yaml
# 2. Test WebSocket with wscat (if installed)
wscat -c ws://localhost:3456
# 3. Send hello message
{"type":"hello","docId":"test"}
# 4. Check YAML is valid
bun run packages/cli/src/index.ts build examples/diagram.yaml
Message Flow
Plugin CLI
│ │
│──── HelloMessage ───────────►│ (docId, secret?)
│ │
│◄──── FullMessage ───────────│ (rev, ir)
│ │
│ [YAML file changes] │
│ │
│◄──── PatchMessage ──────────│ (baseRev, nextRev, ops)
│ │
│ [Plugin reconnects] │
│ │
│──── RequestFullMessage ─────►│ (docId)
│ │
│◄──── FullMessage ───────────│ (rev, ir)
│ │
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
aiskillstore/marketplace
perigon-backend
Perigon ASP.NET Core + EF Core + Aspire conventions
aiskillstore/marketplace
perigon-agent
Pointers for Copilot/agents to apply Perigon conventions
aiskillstore/marketplace
perigon-angular
Angular 21+ standalone/Material/signal conventions for Perigon WebApp
aiskillstore/marketplace
fastapi-mastery
Comprehensive FastAPI development skill covering REST API creation, routing, request/response handling, validation, authentication, database integration, middleware, and deployment. Use when working with FastAPI projects, building APIs, implementing CRUD operations, setting up authentication/authorization, integrating databases (SQL/NoSQL), adding middleware, handling WebSockets, or deploying FastAPI applications. Triggered by requests involving .py files with FastAPI code, API endpoint creation, Pydantic models, or FastAPI-specific features.
aiskillstore/marketplace
context7-efficient
Token-efficient library documentation fetcher using Context7 MCP with 86.8% token savings through intelligent shell pipeline filtering. Fetches code examples, API references, and best practices for JavaScript, Python, Go, Rust, and other libraries. Use when users ask about library documentation, need code examples, want API usage patterns, are learning a new framework, need syntax reference, or troubleshooting with library-specific information. Triggers include questions like "Show me React hooks", "How do I use Prisma", "What's the Next.js routing syntax", or any request for library/framework documentation.
aiskillstore/marketplace
browser-use
Browser automation using Playwright MCP. Navigate websites, fill forms, click elements, take screenshots, and extract data. Use when tasks require web browsing, form submission, web scraping, UI testing, or any browser interaction.
Didn't find tool you were looking for?