Skip to content

CLAUDE.md

Latest commit

 

History

History
62 lines (45 loc) · 4.77 KB

CLAUDE.md

File metadata and controls

62 lines (45 loc) · 4.77 KB
Raw

CLAUDE.md

Agent guide for the CreateOS Python SDK. Contributor conventions live in CONTRIBUTING.md; this file covers what an agent needs that the contributor guide does not.

This repository

  • Package: createos-sandbox on PyPI, imported as createos.
  • Source: src/createos/. Public surface is everything re-exported from src/createos/__init__.py.
  • Python 3.10–3.14. Keep the 3.10 floor: from __future__ import annotations in every module, and the local StrEnum shim in models.py instead of the stdlib 3.11 one.
  • Local checks: .venv/bin/ruff format --check src tests examples, .venv/bin/ruff check src tests examples, .venv/bin/mypy src/createos --ignore-missing-imports, .venv/bin/pytest --cov=createos --cov-fail-under=70.
  • Release: ./scripts/publish.sh (see CONTRIBUTING.md → Releasing).

Cross-repo mesh — CreateOS Sandbox

You are in createos-python-sdk — Python SDK. src/createos/ is the whole public surface. Parity with the Go SDK is mandatory — the two ship the same nine examples and the same surface.

The family

repo path role public? ripples when you change
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-go-sdk ../createos-go-sdk Go SDK 🌐 public public SDK methods, wire types, examples
createos-python-sdk ← you are here this repo Python SDK 🌐 public public SDK methods, wire types, examples
createos-csharp-sdk ../createos-csharp-sdk C# SDK 🌐 public public SDK methods, wire types, examples
createos-java-sdk ../createos-java-sdk Java SDK 🌐 public public SDK methods, wire types, examples
createos-rust-sdk ../createos-rust-sdk Rust SDK 🌐 public public SDK methods, wire types, examples
createos-cli ../createos-cli Go CLI (createos) 🌐 public commands, flags, help/UX text
createos-v2-landing ../createos-v2-landing public docs — apps/docs/src/pages/Sandbox/ 🌐 public REST / SDK / CLI reference, concept and integration pages
createos-plugin ../createos-plugin integrations monorepo — plugins for 8 agent hosts 🌐 public skills, slash commands, hooks, tools

What counts as a shared surface

HTTP endpoint or method · wire or JSON field · error shape · sandbox lifecycle/state · limit or quota · CLI command or flag · public SDK method · documented behavior. A change confined to internals — refactor, private helper, test-only — is not a shared surface, so skip the mesh for it.

Ripple order

fc (openapi.yaml) → the six SDKs → createos-cli → examples → public docs → integrations

Frozen — do not update

  • website-04 (../website-04) — Superseded as the docs home by createos-v2-landing, which is what https://createos.sh/docs actually serves. Its content/docs/Sandbox/ tree is a parallel copy that was still receiving updates — do not add to it, and do not treat it as the docs target.

Protocol — run before you call a shared-surface change done

  1. Classify origin. fc is upstream; SDKs, CLI, docs and integrations are downstream consumers. A downstream change that implies new server behavior goes to the user — never invent server behavior inside a client.
  2. Search every sibling for the touched symbol, endpoint or flag with rg. If a sibling checkout is missing, say so rather than guessing.
  3. Build a status matrix per sibling: already-present · missing-needs-update · n/a. Flag the already-present ones — never silently duplicate a change that is already there.
  4. The control plane is private. If you do not have access to it, do not guess at server behavior and do not reconstruct its internals here — describe the change you need and hand it to someone who does. Respect each repo's own wording rules; fc-sdk/AGENTS.md forbids the word "VM".
  5. Report, don't edit. This is a read-and-report protocol: do not change a sibling repo unless the user asks you to.