ClippyOS

The Autonomous Operating System for Clipping.
A globally reachable control plane for running a clipping agency — clients, money, production, publishing, and a client portal — with an autonomy layer that does the busywork under human approval gates.

---

What ClippyOS is

Clipping agencies run on spreadsheets, DMs, and trust. ClippyOS replaces that with one operating system: a roster of clients with plans and fees, a live money view, a content pipeline from ideation to publish, gated automation that executes the repetitive parts, and a read-mostly portal where clients watch their own production line.

Where's the clipping? The agency-management OS ships today. The final mile — automated clip ingestion, highlight selection, captioning, and rendering — is being automated now (see Roadmap); the rails it will run on (library pipeline, render jobs, publisher integrations, approval gates) are already in production in this repo.

The operator surface

Eighteen screens, one sidebar (src/lib/nav.ts). Grouped here by job:

Job	Screens
Command center	/home dashboard — live roster, collections, pipeline counts, daily objectives; nothing stored as rollups
Revenue & clients	/money live totals · /clients roster + per-client detail with AI analysis · /calendar collection days · /leads prospect pipeline · /billing the ClippyOS subscription itself
Production	/ideation AI idea threads tagged to clients · /agent Crayo.ai automation (shorts + AutoClip) · /thumbnails chat-composed thumbnail sessions with canvas refinement · /library clips, thumbs, captions, platform-ready renders
Distribution	/social on-demand posting to Instagram, X, TikTok, YouTube · /inbox professional Telegram/WhatsApp liaison · /approvals human sign-off before anything goes live
Ops & assurance	/health integration checks (idempotent retries, never auto-starts the Social Machine) · /analytics stored performance snapshots · /team human workload vs. overload threshold · /onboarding bring a channel onto the roster · /settings add-ons, Skills, LLM providers, MCP, Hermes Connect

Plus two audiences beyond the operator:

• Client portal (/portal) — invite-based login, production-stage tracker, day N of the 30-day guarantee, deliverable downloads over signed URLs, client-side approvals, and a read-only activity timeline. Clients see their work, never your fees or tooling.
• Public site (/) — a scroll-driven landing built on the anime.js clip engine (below), Request-a-Demo flow, and Get Access checkout leading into /login.

Landing clip engine

The landing page is a scroll-driven story built on anime.js v4 and three.js. A pinned WebGL stage (src/components/marketing/engine/clip-engine-scene.ts) renders the ClippyOS engine as an exploded editing timeline drawn as a glowing holographic wireframe: a projector deck with a spinning jog wheel and a media bin, audio (A1), footage (V1) and caption (C1) tracks floating under a timecode ruler, a playhead light sheet that sweeps the stack, a source port that streams footage in, hook markers on the waveform, a razor that cuts V1 into twelve clips, a review gate, four output lanes that end in X, YouTube, Instagram and TikTok screens, and the Hermes loop around the machine. The clips move between formations (segments on the footage track, cut apart, vertical 9:16 cards, the review conveyor, the output lanes, the media bin and the Hermes loop) while the camera dollies along the timeline.

Scrolling the chapters in src/components/marketing/landing-page.tsx scrubs one anime.js timeline in src/components/marketing/anime/landing-motion.ts with onScroll; it drives the engine's stage progress, the readout, panels and HUD. anime.js also runs the engine boot (the wireframe draws itself in), stage pulses, pointer parallax, split-word reveals and magnetic buttons. three.js is loaded with a dynamic import so it only ships to the landing page.

The engine is a labelled demo run. Stage configs and clip formations live in src/lib/clip-engine.ts and are covered by src/lib/clip-engine.test.ts. Ingest, detect, cut and caption/render are marked Rolling out until the native clipping pipeline ships (see Roadmap); approvals, the Social Machine, the Library and Hermes are marked Live. With prefers-reduced-motion, the engine renders once, assembled, and nothing animates. Without WebGL the stage keeps its readouts over a static glow.

Architecture

Globally reachable control plane on Vercel; durable state in managed Postgres; files in object storage; a single Windows machine for platform logins — kept paused, not destroyed.

Layer	Where	Role
App / API / MCP	Vercel (TanStack Start, Nitro vercel preset)	Server functions, /api/v1, MCP server, OAuth 2.1
Database	Managed Postgres (Supabase / Neon) via DATABASE_URL; embedded PGLite fallback locally	RLS-enabled schema; migrations apply automatically
Clip files	Supabase Storage (clippy-library bucket) or S3-compatible overflow (Filebase / Storj / R2)	Survives deploys. Never the Windows VM.
IPFS	Pinata pin / Filebase CID	Pin layer only — never the write backend
Social Machine	Daytona daytona-medium Linux container (Windows/Linux-VM snapshots optional)	Computer Use only: platform logins, uploads. Hibernate = auto-stop after idle (filesystem persists; container class has no hot pause). Never started by cron or Test Connection. Start auto-provisions a free country proxy.
Render / sandboxes	Short-lived Linux jobs (ffmpeg/ffprobe, skill sandboxes)	Isolated from browser profiles

Key source trees: src/routes/_app (operator screens), src/routes/api (HTTP surface), src/lib/server (server-only domain logic), src/lib/auth (Better Auth wiring), migrations/ (SQL, add-only), supabase/schema.sql (consolidated schema), scripts/ (QA + pipeline).

Autonomy, safely

The autonomy stack executes real agency actions — and is deliberately leashed:

• Playbooks with conservative policies (src/lib/playbooks.ts) — auto-mark-payments off, no stage advancement without evidence, social uploads default to draft, idle-stop timers, bulk-job caps.
• Human approval gates — fee changes, churn, hard deletes, integration disconnects, bulk mark-paid, large backward stage jumps, Daytona key rotation, raw session-material export, and more require sign-off in /approvals.
• Scoped API keys (src/lib/autonomy.ts) — twelve coarse scopes (read, write:payments, approvals:admin, …) for operators and agents.
• Audit + idempotency — every /api/v1 mutation writes an audit log and honors idempotency keys (src/lib/server/autonomy-audit.server.ts).
• Skills with provenance — SKILL.md packages marked human, agent, or builtin; agent-proposed skills enter pending_review; sandboxed runtime defaults to no network (src/lib/skills.ts).

Integrations & APIs

• Versioned REST API — /api/v1/* with scoped keys, idempotency, and action-level routing (src/routes/api/v1.$.ts).
• Remote MCP server — expose the OS to coding agents over MCP with a full OAuth 2.1 authorization flow (src/routes/api/mcp.ts, src/lib/mcp-oauth.ts), including protected-resource metadata.
• Outbound webhooks — ~40 event types (payment.collected, approval.requested, social.upload.succeeded, agent.run.*, …) signed and delivered to your endpoints.
• Inbound channels — Telegram, WhatsApp Cloud API, and Whop payment webhooks (src/routes/api/webhooks/).
• First-party connectors — Linear issue sync, Discord agent runs, xAI / Grok models, Higgsfield image generation, Resend email, YouTube Data API, Twitch, publisher OAuth for Instagram / X / TikTok / YouTube.

Tech stack

Concern	Choice
Framework	TanStack Start (React 19, file routes, SSR) on Nitro → Vercel
UI	Tailwind CSS v4, Radix UI primitives, Recharts, cmdk palette, Motion
State/data	TanStack Query + Router, Zustand, Zod
Auth	Better Auth (Google / X / email-password), portal bearer tokens
DB access	Parameterized SQL over pg (managed Postgres) or PGLite (WASM)
Testing	Node built-in runner for units; Playwright suites (scripts/qa-*.ts) for flows

Quickstart

git clone https://github.com/swcstudiospace/clippyos && cd clippyos
npm install                      # Node 22+
cp .env.example .env             # names only — real values stay out of git
npm run dev                      # http://localhost:8080

With no DATABASE_URL, the app boots on embedded PGLite and applies migrations/*.sql automatically — same schema, throwaway data. Point DATABASE_URL at any Postgres to go durable; no code changes (src/lib/db.ts).

Full verification matrix:

npm test            # unit tests (node:test)
npm run typecheck   # tsc --noEmit
npm run lint        # eslint
npm run check:auth  # dev/build agree on VITE_AUTH_ENABLED (needs dev server up)

Configuration

Set in Vercel (or your host) — never commit a .env. Names are documented in .env.example:

Variable	Purpose
DATABASE_URL	Managed Postgres connection (unset ⇒ local PGLite)
SUPABASE_URL / SUPABASE_ANON_KEY / SUPABASE_SERVICE_ROLE_KEY	Supabase Storage for the clip library
BETTER_AUTH_SECRET	Session signing
CRON_SECRET	Protects /api/cron/ops (every 15 min; sweeps queues, never starts the VM). Vercel Hobby only allows daily crons — use Pro or a daily schedule there
LIBRARY_S3_*, PINATA_JWT, LIBRARY_IPFS_GATEWAY	Optional S3 overflow + IPFS pin layer
TELEGRAM_BOT_TOKEN, WHATSAPP_ACCESS_TOKEN, WHATSAPP_PHONE_NUMBER_ID	Optional liaison channels
XAI_API_KEY, RESEND_API_KEY, DISCORD_BOT_TOKEN, YOUTUBE_API_KEY, DAYTONA_API_KEY, HIGGSFIELD_*	Optional provider keys

Operator-saved credentials (publisher OAuth, Daytona key, proxy, Linear, Telegram, WhatsApp) live server-side under Settings — never in the browser bundle and never in env vars.

Deployment

The repo is production-shaped: no secrets in git, add-only SQL migrations under migrations/, and the Vercel preset wired into Vite. Connect the repo to a Vercel project; npm run build compiles, patches SSR exports, and applies pending migrations before the deploy goes warm. Liveness: GET /api/health.

Desktop app (Tauri)

ClippyOS also ships as a desktop application — a Tauri 2.0 wrapper around the same web app. Three npm scripts drive it:

Command	What it does
npm run desktop:dev	Tauri dev mode against the Vite dev server on :8080
npm run desktop:build	Bundles the app for the current platform
npm run desktop:server	Stages the Node engine into dist-desktop/ for bundling

The window loads one of two backends:

• Cloud mode — if CLIPPYOS_CLOUD_ORIGIN is set (must be an https:// URL), the window loads that origin directly and no local engine runs.
• Local mode — otherwise, a bundled Node sidecar spawns a local server on a free port; override with CLIPPYOS_SIDECAR_PORT. If the engine can't start, the window shows an offline loading page.

Bundles are produced by .github/workflows/desktop-release.yml on v* tags: deb + AppImage on Linux, dmg + app for macOS (aarch64 and x86_64), msi + NSIS installers on Windows. They are unsigned unless signing secrets are configured in the release environment.

End users need nothing installed — the Node runtime ships alongside the app binary. Building from source requires a stable Rust toolchain for the cargo build.

CI/CD & code review

Every pull request triggers two independent AI reviews, posted as PR comments and updated in place on later pushes (pr-quality.yml): a Greptile agent review (greptile review --agent) and an omp coding-agent pass over the full diff. Enable them with the GREPTILE_API_KEY and OMP_API_KEY repository secrets — either may be omitted, and that reviewer quietly skips the run. Optionally set the OMP_MODEL repository variable to pin the omp model (defaults to gpt-5.2). Desktop packaging runs (desktop-release.yml) open a draft release on v* tags and also attach every platform's installers as per-run artifacts (desktop-bundles-*), downloadable from the workflow run page even before a release is published.

How this repo is engineered

Every change travels the same pipeline — planning before code, review before hardening, verification before release:

1. Plan — contract first: routes, types, and blast radius written down before edits (AGENTS.md is the operating guide agents and humans share).
2. Implement — smallest correct change; server-only boundaries respected; add-only migrations.
3. Review — diff checked against repo conventions and the PR template contracts checklist.
4. Harden — threat-model new inputs; secrets scanned; auth invariant re-checked (npm run check:auth).
5. Verify — npm test, npm run typecheck, npm run lint locally and in CI; UI changes exercised through the Playwright qa-*.ts suites and the dual-viewport browser-smoke.ts verdict.
6. Release — conventional commit, deploy on merge, migrations apply in the build, rollback = redeploy previous tag.

Roadmap

• Automated clipping pipeline (in progress) — ingestion → highlight detection → captioning → render → review queue, riding the existing library/publisher/approval rails.
• Deeper analytics pulls and benchmarking across client channels.
• Expanded playbook marketplace built on the Skills provenance system.

Community

• Bugs and features: open an issue with the templates under .github/ISSUE_TEMPLATE.
• Contributions: read CONTRIBUTING.md and AGENTS.md first.
• Security: private disclosure only — see SECURITY.md.
• Support: SUPPORT.md.

License

MIT © SWC Studio.