Install Capsules

Zero install

Drop into any LLM

No tooling required. Paste this prompt with a .capsule file into any modern LLM with coding capabilities. The model will unzip, read the chain, and bootstrap the skill if you let it.

Universal runtime prompt

`.capsule` : ZIP archive / portable unit of intelligence / AI coordination format
Unzip → understands identity / intent / participants / event history
⚠ no skill ? start with `handoff.md` then `chain/events.jsonl`
skills supported ? download + ask user to install from: https://raw.githubusercontent.com/virionai/capsules-protocol/main/skills/capsule/SKILL.md

Exploratory Pith skill

This prompt is a zero-install path for giving any capable LLM enough context to inspect a capsule. Pith is our exploratory skill for compact, transferable context; it should work with any LLM that can follow structured instructions.

Expanded prompt More about Pith

Installable Packages

The ./capsules repo is the canonical public surface. Each package versions independently; install only the artifact your harness needs.

Prototype notice

Capsules.run is an experimental protocol surface and has not reached full maturity. Evaluate these packages before production use. If you would like to work on the project, contact us at virion.ai/initiate. We are always looking to collaborate with like-minded explorers.

Release tags are namespaced by artifact: spec/v0.5.0, sdk/v0.1.0, capsule-skill/v0.3.0, and so on. The repo never publishes a single repo-wide version on purpose.

The Built Artifact

For harnesses that prefer a single bundled drop-in, the dist/ folder publishes the built capsule skill alongside its checksum. Verify, then install.

Recommended

Clone and install skills

Clone the repo and copy the skill folder you need into your harness's skills directory. Works with any agent that follows the Agent Skills format.

git clone https://github.com/virionai/capsules-protocol.git

Then copy a skill folder:

          # Capsule protocol skill (bundles the JS SDK)
cp -r capsules-protocol/skills/capsule ~/.claude/skills/capsule
        

          # Pith compression skill
cp -r capsules-protocol/skills/pith ~/.claude/skills/pith
        

Supported Harnesses

Claude Code Cursor OpenCode Windsurf Codex

Each harness stores skills in a different directory. See the repo architecture for harness-specific paths.

Planned

SSH Installer

An interactive SSH installer that detects which AI agents are on your machine and lets you choose where to install. Coming soon.

ssh capsules.run install

Planned

curl

A non-interactive script that detects available agents and installs with a single command. No runtime required; just shell.

curl -fsSL https://capsules.run/install.sh | sh

Uninstall

Open the relevant skills folder, inspect what is installed, then remove a skill directory manually when you are sure. These commands only open folders.

macOS

            open ~/.agents/skills
open ~/.codex/skills
open ~/.claude/skills
open ./.agents/skills
          

Windows PowerShell

            ii "$env:USERPROFILE\.agents\skills"
ii "$env:USERPROFILE\.codex\skills"
ii "$env:USERPROFILE\.claude\skills"
ii ".\.agents\skills"
          

Linux

            xdg-open ~/.agents/skills
xdg-open ~/.codex/skills
xdg-open ~/.claude/skills
xdg-open ./.agents/skills
          

Some known skill locations

Universal global ~/.agents/skills/ %USERPROFILE%\.agents\skills\
Universal project-local ./.agents/skills/
OpenAI / Codex global ~/.codex/skills/ %USERPROFILE%\.codex\skills\
Claude global ~/.claude/skills/ %USERPROFILE%\.claude\skills\

For rollback, rename or archive the skill folder before removing it.