Skip to content

feat: pi extension #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
BhautikChudasama wants to merge 7 commits into from
Open

feat: pi extension #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
be243fc
refactor: migrate to monorepo packages/ structure
BhautikChudasama Aug 4, 2026
f747017
refactor: rename createos-sandbox to claude-code-plugin, expand Pi docs
BhautikChudasama Aug 4, 2026
d53f545
docs: rename header to CreateOS Integrations, equal billing for Claud…
BhautikChudasama Aug 4, 2026
b5425a4
docs: add Pi quick start alongside Claude Code in Quick start section
BhautikChudasama Aug 4, 2026
1b0c86a
feat(pi): auto-install createos CLI when not found
BhautikChudasama Aug 4, 2026
896ca6c
docs: equal Claude Code and Pi command sections in README
BhautikChudasama Aug 4, 2026
7187f7b
chore: apply oxfmt formatting to pi-extension
BhautikChudasama Aug 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .claude-plugin/marketplace.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,8 @@
"owner": { "name": "NodeOps", "url": "https://createos.sh" },
"plugins": [
{
"name": "createos-sandbox",
"source": "./createos-sandbox",
"name": "claude-code-plugin",
"source": "./packages/claude-code-plugin",
"description": "Run ad-hoc/heavy/untrusted code in disposable CreateOS Sandboxes; offload, parallel fanout, scratch shell, reusable box with sync, port tunnel, public expose, network clusters, S3 disks, WireGuard VPN, fork, pause/resume, and custom images."
}
]
Expand Down
18 changes: 9 additions & 9 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,8 @@ cross-repo mesh guide.
Architectural decisions live in `docs/adr/`. Read the relevant one before
reworking the thing it covers.

| ADR | Decision | Status |
|---|---|---|
| ADR | Decision | Status |
| ------------------------------------------ | ---------------------------------------------------------------------------------------- | -------------------------- |
| [0001](./docs/adr/0001-cos-bash-driver.md) | `cos`, a bash driver, as the plugin's execution engine — not the `createos` CLI directly | accepted, **under review** |

ADR-0001 is load-bearing for anyone touching `scripts/cos`, the skill, or the
Expand Down Expand Up @@ -52,13 +52,13 @@ claim aligned with `fc`. This repo is one of five in the product mesh.

### Repo map

| repo | path | role | public? | changes that ripple across the mesh |
|---|---|---|---|---|
| **fc** | `../fc` | control-plane — **source of truth** | 🔒 private | HTTP API, wire/JSON fields, error shapes, lifecycle/state, limits/quotas, behavior |
| **fc-sdk** | `../fc-sdk` | TypeScript SDK **+ `examples/`** | 🌐 public | public SDK methods, wire types, example apps |
| **createos-cli** | `../createos-cli` | Go CLI | 🌐 public | commands, flags, help/UX text |
| **website-04** | `../website-04` (`content/docs/Sandbox`) | public docs | 🌐 public | REST / SDK / CLI reference + concept pages |
| **createos** | `../createos-claude-plugins` | Claude Code plugin marketplace; `createos-sandbox` plugin over the `createos` CLI | 🌐 public | skills, slash commands, hooks |
| repo | path | role | public? | changes that ripple across the mesh |
| ---------------- | ---------------------------------------- | --------------------------------------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------- |
| **fc** | `../fc` | control-plane — **source of truth** | 🔒 private | HTTP API, wire/JSON fields, error shapes, lifecycle/state, limits/quotas, behavior |
| **fc-sdk** | `../fc-sdk` | TypeScript SDK **+ `examples/`** | 🌐 public | public SDK methods, wire types, example apps |
| **createos-cli** | `../createos-cli` | Go CLI | 🌐 public | commands, flags, help/UX text |
| **website-04** | `../website-04` (`content/docs/Sandbox`) | public docs | 🌐 public | REST / SDK / CLI reference + concept pages |
| **createos** | `../createos-claude-plugins` | Claude Code plugin marketplace; `createos-sandbox` plugin over the `createos` CLI | 🌐 public | skills, slash commands, hooks |

### What counts as a shared surface

Expand Down
35 changes: 35 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
# Contributing to CreateOS Claude Plugins

Contributions are welcome! This repository is a monorepo of integrations and plugins for
[CreateOS](https://nodeops.network/createos). Each package in `packages/` is self-contained;
apps in `apps/` are standalone projects.

## What you can contribute

- Bug fixes and new features in existing packages or apps.
- New integrations or plugins (please open an issue first to discuss the fit).
- Documentation improvements.

## Submitting a pull request

1. Fork the repository and create a branch for your change.
2. Keep each PR scoped to one package or app.
3. Use [Conventional Commit](https://www.conventionalcommits.org/) style for your PR title
(e.g. `feat(pi-extension): add X`, `fix(adk-plugin): handle Y`).
4. Run lint, build, and tests for the package you changed before opening the PR.
5. Open a pull request. A maintainer will review it and, once approved, merge it into `main`.

## Code style

- Follow the conventions already established in the package you are modifying.
- Use TypeScript where applicable.
- Keep changes focused and minimal.

## Reporting issues

Found a bug or have a feature request? Open an issue, but please check for duplicates first.

## License

By contributing, you agree that your contributions will be licensed under the same license as
the project (see [LICENSE](./LICENSE)).
141 changes: 97 additions & 44 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,13 @@
<div align="center">

# CreateOS Claude Plugin Marketplace
# CreateOS Integrations

**A [Claude Code](https://docs.claude.com/en/docs/claude-code) plugin marketplace for disposable sandbox compute.**
**[Claude Code](https://docs.claude.com/en/docs/claude-code) plugin & [Pi](https://github.com/anthropics/pi) extension for disposable sandbox compute.**

Run ad-hoc, heavy, or untrusted code **off your machine** in disposable [CreateOS](https://createos.sh) Sandboxes — straight from your Claude Code session.
Run code **off your machine** in disposable [CreateOS](https://createos.sh) Sandboxes — from Claude Code or Pi.

[![Claude Code](https://img.shields.io/badge/Claude%20Code-plugin-6E56CF)](https://docs.claude.com/en/docs/claude-code)
[![Pi](https://img.shields.io/badge/Pi-extension-F97316)](https://github.com/anthropics/pi)
[![CreateOS](https://img.shields.io/badge/CreateOS-Sandboxes-0EA5E9)](https://createos.sh)
[![Spawn](https://img.shields.io/badge/create%20to%20first%20command-~200ms-22C55E)](https://createos.sh)
[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)](#contributing)
Expand All @@ -17,7 +18,7 @@ Run ad-hoc, heavy, or untrusted code **off your machine** in disposable [CreateO

## Why

Heavy builds, flaky test suites, and untrusted code don't belong on your laptop. `createos-sandbox` gives Claude a skill + slash commands that offload them to throwaway CreateOS Sandboxes — created and running your first command in roughly 200 ms, self-destructing when done — so your machine stays free, your deps stay isolated, and untrusted code never touches local state.
Heavy builds, flaky test suites, and untrusted code don't belong on your laptop. `claude-code-plugin` gives Claude a skill + slash commands that offload them to throwaway CreateOS Sandboxes — created and running your first command in roughly 200 ms, self-destructing when done — so your machine stays free, your deps stay isolated, and untrusted code never touches local state.

- 🧨 **Disposable** — one-shot offload stages a dir, runs, pulls artifacts, then auto-destroys. Box-side changes never touch local unless you ask.
- ⚡ **Fast** — ~200 ms from create to first command; parallel fanout across N boxes for matrix builds and split test suites.
Expand All @@ -27,63 +28,105 @@ Heavy builds, flaky test suites, and untrusted code don't belong on your laptop.

## Quick start

**Claude Code:**

```bash
# 1. Add the marketplace + install the plugin
/plugin marketplace add NodeOps-app/createos-claude-plugins
/plugin install createos-sandbox@createos
/plugin install claude-code-plugin@createos

# 2. Offload a heavy test run to a throwaway box (auto-destroys)
/createos-sandbox:offload . "npm ci && npm test"
```

The `createos` CLI **auto-installs** on first use. Sign in once with `createos login` (browser OAuth, run it in your own terminal) or `export CREATEOS_API_KEY=<key>`; check with `cos auth`. Prefer a local checkout? See [Install](#install).

## Plugins
**Pi:**

| Plugin | What it does |
|---|---|
| [**createos-sandbox**](./createos-sandbox) | Offload, parallel fanout, scratch shell, reusable box with sync, port tunnel, public HTTPS expose, private-network clusters, BYO-S3 disk mounts, WireGuard VPN, and snapshot/fork — all driving the authed `createos` CLI. |

> The marketplace currently ships one plugin; more CreateOS plugins land here as siblings.
```bash
# 1. Install the extension
pi install npm:@createos/pi

## Commands at a glance
# 2. Start a session with all tools routed to a remote sandbox
pi --createos
```

| Command | What |
|---|---|
| `/createos-sandbox:offload <dir> <cmd>` | one-shot: stage → run → pull artifacts → destroy |
| `/createos-sandbox:fanout <dir> <cmd1> [cmd2 …]` | run each command in its own throwaway box, in parallel |
| `/createos-sandbox:shell` | instant throwaway interactive Linux (destroyed on exit) |
| `/createos-sandbox:up` · `run` · `sync` · `down` | reusable per-repo box + file sync for live dev loops |
| `/createos-sandbox:tunnel <port>` | forward a box port to `127.0.0.1` (private) |
| `/createos-sandbox:expose <port>` | public HTTPS URL for a box port |
| `/createos-sandbox:cluster …` | N boxes on one private network, name-addressable |
| `/createos-sandbox:disk …` | mount your own S3 bucket into the project box |
| `/createos-sandbox:vpn …` | WireGuard L3 into your private networks |
| `/createos-sandbox:fork` | snapshot the project box → independent clone |
| `/createos-sandbox:pause` · `resume` | park the warm box at zero compute cost, then restore it exactly |
| `/createos-sandbox:template …` | build a custom image so boxes boot with the toolchain already installed |
| `/createos-sandbox:status` | show active box + sync + tunnels + cluster |
The `createos` CLI **auto-installs** on first use. Sign in once with `createos login` (browser OAuth, run it in your own terminal) or `export CREATEOS_API_KEY=<key>`; check with `cos auth`. Prefer a local checkout? See [Install](#install).

Full flags, networking guide, and heavy-build tips live in the [**plugin README**](./createos-sandbox/README.md).
## Packages

| Package | What it does |
| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [**claude-code-plugin**](./packages/claude-code-plugin) | Hooks-based Claude Code plugin — offload, parallel fanout, scratch shell, reusable box with sync, port tunnel, public HTTPS expose, private-network clusters, BYO-S3 disk mounts, WireGuard VPN, and snapshot/fork — all driving the authed `createos` CLI. |
| [**pi-extension**](./packages/pi-extension) | Pi coding agent extension that transparently routes all built-in commands (bash, read, write, edit, ls, find, grep) to a remote CreateOS Sandbox, plus 26 additional tools for sandbox lifecycle, configuration, port tunnels, file sync, private networks, persistent disks, and device VPN — 33 tools total. |

## Claude Code — commands at a glance

| Command | What |
| ------------------------------------------------ | ----------------------------------------------------------------------- |
| `/createos-sandbox:offload <dir> <cmd>` | one-shot: stage → run → pull artifacts → destroy |
| `/createos-sandbox:fanout <dir> <cmd1> [cmd2 …]` | run each command in its own throwaway box, in parallel |
| `/createos-sandbox:shell` | instant throwaway interactive Linux (destroyed on exit) |
| `/createos-sandbox:up` · `run` · `sync` · `down` | reusable per-repo box + file sync for live dev loops |
| `/createos-sandbox:tunnel <port>` | forward a box port to `127.0.0.1` (private) |
| `/createos-sandbox:expose <port>` | public HTTPS URL for a box port |
| `/createos-sandbox:cluster …` | N boxes on one private network, name-addressable |
| `/createos-sandbox:disk …` | mount your own S3 bucket into the project box |
| `/createos-sandbox:vpn …` | WireGuard L3 into your private networks |
| `/createos-sandbox:fork` | snapshot the project box → independent clone |
| `/createos-sandbox:pause` · `resume` | park the warm box at zero compute cost, then restore it exactly |
| `/createos-sandbox:template …` | build a custom image so boxes boot with the toolchain already installed |
| `/createos-sandbox:status` | show active box + sync + tunnels + cluster |

Full flags, networking guide, and heavy-build tips live in the [**Claude Code Plugin README**](./packages/claude-code-plugin/README.md).

## Pi — commands at a glance

All built-in tools (bash, read, write, edit, ls, find, grep) transparently route to the sandbox — plus 26 additional tools for lifecycle, networking, disks, and device VPN (33 tools total).

| Command | What |
| -------------------------- | ------------------------------------- |
| `/sandbox` | Show sandbox status |
| `/network create <name>` | Create a private network |
| `/network ls` | List your networks |
| `/network show <name>` | Show network members + IPs |
| `/network attach <name>` | Join this sandbox to a network |
| `/network detach <name>` | Leave a network |
| `/network rm <name>` | Delete a network |
| `/device status` | Show registered devices |
| `/device attach <network>` | Give your machine access to a network |
| `/device detach <network>` | Remove access |

### Flags

| Flag | Purpose |
| ------------------ | ------------------------------------- |
| `--createos` | Activate the extension |
| `--shape <shape>` | Sandbox size (default: `s-2vcpu-2gb`) |
| `--rootfs <name>` | Base image or template |
| `--network <name>` | Network(s) to join at creation |

Full tool inventory lives in the [**Pi Extension README**](./packages/pi-extension/README.md).

## Install

**From GitHub (recommended):**

```
/plugin marketplace add NodeOps-app/createos-claude-plugins
/plugin install createos-sandbox@createos
/plugin install claude-code-plugin@createos
```

**From a local checkout:**

```
git clone https://github.com/NodeOps-app/createos-claude-plugins
/plugin marketplace add /path/to/createos-claude-plugins
/plugin install createos-sandbox@createos
/plugin install claude-code-plugin@createos
```

**Dev (instant, no install):**

```bash
claude --plugin-dir /path/to/createos-claude-plugins/createos-sandbox
claude --plugin-dir /path/to/createos-claude-plugins/packages/claude-code-plugin
/reload-plugins # after editing plugin files
```

Expand All @@ -103,24 +146,34 @@ claude --plugin-dir /path/to/createos-claude-plugins/createos-sandbox
## Repository layout

```
createos/ # marketplace root
createos-claude-plugins/ # marketplace root
├─ .claude-plugin/
│ └─ marketplace.json # marketplace manifest
└─ createos-sandbox/ # the plugin
├─ .claude-plugin/plugin.json
├─ commands/ # slash commands
├─ skills/ # the using-createos-sandbox skill + references/
├─ hooks/ # SessionStart driver-path + PreToolUse offload-hint
├─ scripts/cos # the CLI driver
└─ README.md
│ └─ marketplace.json # marketplace manifest
├─ packages/
│ ├─ claude-code-plugin/ # hooks-based Claude plugin
│ │ ├─ .claude-plugin/plugin.json
│ │ ├─ commands/ # slash commands
│ │ ├─ skills/ # the using-createos-sandbox skill + references/
│ │ ├─ hooks/ # SessionStart driver-path + PreToolUse offload-hint
│ │ ├─ scripts/cos # the CLI driver
│ │ └─ README.md
│ └─ pi-extension/ # Pi extension (TypeScript)
│ ├─ index.ts # extension entry point
│ ├─ src/ # tools, CLI wrappers, ops
│ └─ README.md
├─ apps/ # (future starter templates)
├─ docs/
│ └─ adr/ # architecture decision records
└─ README.md
```

## Contributing

Issues and PRs welcome. The plugin is a thin Claude Code surface over the [`createos`](https://createos.sh) CLI — most command logic lives in [`createos-sandbox/scripts/cos`](./createos-sandbox/scripts/cos). Keep the slash-command, skill, and CLI surfaces aligned.
Issues and PRs welcome. The plugin is a thin Claude Code surface over the [`createos`](https://createos.sh) CLI — most command logic lives in [`claude-code-plugin/scripts/cos`](./packages/claude-code-plugin/scripts/cos). Keep the slash-command, skill, and CLI surfaces aligned.

## Links

- 🌐 [createos.sh](https://createos.sh) — CreateOS platform
- 📖 [Claude Code plugins](https://docs.claude.com/en/docs/claude-code) — how plugins & marketplaces work
- 📦 [Plugin README](./createos-sandbox/README.md) — full command & flag reference
- 📦 [Claude Code Plugin README](./packages/claude-code-plugin/README.md) — full command & flag reference
- 🔧 [Pi Extension README](./packages/pi-extension/README.md) — Pi extension setup & tool inventory
Empty file added apps/.gitkeep
View file
Open in desktop
Empty file.
Loading