Common Fabric Platform

Common Labs - Radioactive experiments. Turn back! You will find no API stability here.

What is Common Fabric?

Common Fabric is a nascent distributed computing platform that provides both a runtime and storage layer. The design allows instrumentation of all information flow in the system, enabling safe & private collaboration at scale.

Core Concepts

Patterns are reactive programs that can be linked together to create data and program networks. They're written in TypeScript/JSX and run in a secure sandbox environment. Patterns can:

• Process and transform data
• Render interactive UIs using cf- prefixed components
• React to changes from linked patterns
• Connect to external APIs

Pieces are deployed instances of patterns running in Common Fabric spaces. Pieces can be linked together to create complex workflows where data flows automatically between connected components.

Spaces are collaborative environments where pieces live and interact. Users can run their own spaces or use hosted versions.

Quick Start (Development)

1. Install Deno 2
2. Clone this repo
3. Install the Git hooks: deno task install-hooks
4. Start local dev servers: ./scripts/start-local-dev.sh
5. Access the application at http://localhost:8000

For Claude Code users, run /deps to verify prerequisites and /start-local-dev to start the dev servers. See LOCAL_DEV_SERVERS.md for troubleshooting.

Architecture

This is a multi-package monorepo with several key components:

Backend (Toolshed): The hosted platform backend, written in Deno2, that provides the distributed runtime and storage.

Frontend (Shell): A web client interface written with Lit Web Components for interacting with Common Fabric spaces.

CLI (cf): Command-line interface for managing pieces, linking patterns, and deploying to spaces. Run deno task cf --help for command reference.

UI Components (packages/ui): Custom VDOM layer and cf- prefixed components for pattern UIs.

Examples & Patterns (packages/patterns): Example patterns for building with Common Fabric.

Pattern Development: Patterns can be developed using the repo-local skills/pattern-dev/ skill package. Claude compatibility still exposes this as /pattern-dev. See Pattern Documentation for patterns, components, and handlers.

Development & Integrations

AI Skills & Commands

This repository includes repo-local skills plus runtime-specific discovery surfaces and Claude compatibility commands for common workflows:

• skills/pattern-dev/ - Develop patterns with LLM assistance
• skills/pattern-test/ - Write and run pattern tests
• skills/pattern-deploy/ - Deploy patterns and test with CLI
• /start-local-dev - Start local dev servers
• /deps - Dependency and integration setup
• /fix-issue - Fix a specific issue
• /oracle - Investigate how things actually work

skills/ is the canonical authored source. Codex discovers repo-local skills through /.agents/skills/, while Claude compatibility preserves the existing /pattern-dev, /pattern-test, and related skill names through /.claude/skills/.

Dependencies & Integrations

Required:

• Deno 2 - Runtime for backend and tooling

Recommended Integrations:

• GitHub CLI - For PR and issue workflows
• Claude Code MCP integrations (run /deps in Claude Code for setup):
  • Playwright MCP for browser-based pattern testing

Development Practices

• CI/CD: All changes must pass automated checks before merging
• Testing: Tests are critical - run with deno task test
• Linting: Use deno task check for type checking
• Formatting: Always run deno fmt before committing
• See CLAUDE.md for detailed coding guidelines

Running the backend

For a more detailed guide, see ./packages/toolshed/README.md.

cd ./packages/toolshed
deno task dev

By default the backend will run at http://localhost:8000

Running the frontend

Recommended: Use ./scripts/start-local-dev.sh to start both backend and frontend together. See LOCAL_DEV_SERVERS.md for details.

Manual setup (if you need to run servers separately):

# Against local backend (use dev-local, NOT dev)
cd ./packages/shell
TOOLSHED_PORT=8000 deno task dev-local

Important: deno task dev points to the production backend. Use deno task dev-local when running against a local Toolshed instance.

The frontend dev server runs at http://localhost:5173. Access the application at http://localhost:8000, where toolshed proxies to shell.

If you are not running a local backend, you can point to the cloud:

cd ./packages/shell
deno task dev