Pneuma Skills

Co-creation Infrastructure for Humans × Code Agents

Visual environment, skills, continuous learning, and distribution —
everything humans and agents need to build content together.

bunx pneuma-skills slide --workspace ./my-first-pneuma-slide

"pneuma" — Greek pneuma, meaning soul, breath, life force.

When humans and code agents co-create content, they need more than a chat window — they need shared infrastructure. Pneuma provides four pillars for isomorphic collaboration, built atop mainstream code agents. Today the production path is Claude Code; the runtime now exposes a startup-selectable backend layer so additional agents can be integrated without rewriting the UI shell.

Built-in Modes

Getting Started

Desktop App (recommended)

Download the latest release for your platform:

The desktop app bundles Bun — no runtime install needed. Install Claude Code CLI and you're ready to go. The launcher shows available backends — currently Claude Code and Codex are implemented.

CLI

# Prerequisites: Bun >= 1.3.5, Claude Code CLI and/or Codex CLI

# Open the Launcher (marketplace UI)
bunx pneuma-skills

# Start a mode with a fresh workspace
bunx pneuma-skills slide --workspace ./my-first-pneuma-slide

# Explicit backend selection at startup
bunx pneuma-skills doc --backend claude-code

# Or use the current directory
bunx pneuma-skills doc

git clone https://github.com/pandazki/pneuma-skills.git
cd pneuma-skills
bun install
bun run dev doc --workspace ~/my-notes

CLI Usage

pneuma-skills [mode] [options]

Modes:
  (no argument)                Open the Launcher (marketplace UI)
  webcraft                     Web design with Impeccable.style
  slide                        HTML presentations
  doc                          Markdown with live preview
  draw                         Excalidraw canvas
  illustrate                   AI illustration studio
  mode-maker                   Create custom modes with AI
  evolve                       Launch the Evolution Agent
  /path/to/mode                Load from a local directory
  github:user/repo             Load from GitHub
  https://...tar.gz            Load from URL

Options:
  --workspace <path>   Target workspace directory (default: cwd)
  --port <number>      Server port (default: 17996)
  --backend <type>     Agent backend to launch (default: claude-code)
  --no-open            Don't auto-open the browser
  --skip-skill         Skip skill installation
  --debug              Enable debug mode
  --dev                Force dev mode (Vite)

Subcommands:
  evolve <mode>        Analyze history and propose skill improvements
  mode add <url>       Install a remote mode
  mode list            List published modes
  mode publish         Publish current workspace as a mode
  snapshot push/pull   Upload/download workspace snapshot

Architecture

┌─────────────────────────────────────────────────────────┐
│  Desktop / Launcher                                     │
│  Browse → Discover → Launch → Resume                    │
├─────────────────────────────────────────────────────────┤
│  Layer 4: Mode Protocol                                 │
│  ModeManifest — skill + viewer config + agent prefs     │
├─────────────────────────────────────────────────────────┤
│  Layer 3: Content Viewer                                │
│  ViewerContract — render, select, agent-callable actions│
├─────────────────────────────────────────────────────────┤
│  Layer 2: Agent Runtime                                 │
│  Backend registry + protocol bridge + normalized state  │
├─────────────────────────────────────────────────────────┤
│  Layer 1: Runtime Shell                                 │
│  HTTP, WebSocket, PTY, File Watch, Frontend             │
└─────────────────────────────────────────────────────────┘

Three core contracts in core/types/:

The backend contract is intentionally split in two layers:

• Process lifecycle: AgentBackend owns launch, resume, exit, and capability declaration.
• Session/UI contract: the browser consumes normalized session state (backend_type, agent_capabilities, agent_version) rather than backend-specific wire details.

That means backend-specific protocols stay in backends/<name>/, while the UI and most server code depend on a stable session model.

Tech Stack

Backend Model

• Backend is selected once at launch with --backend or in the launcher modal.
• The selected backend is persisted in <workspace>/.pneuma/session.json and ~/.pneuma/sessions.json.
• Existing workspaces are backend-locked. Pneuma resumes the same backend for the lifetime of that workspace session instead of switching mid-stream.
• Frontend features now read agent_capabilities from session state. Claude-only features such as Schedules and cost tracking are hidden for non-Claude backends.

Acknowledgements

This project's Claude transport layer, NDJSON handling, and much of the initial chat bridge were heavily informed by Companion by The Vibe Company.

Companion remains the reference for Claude Code's undocumented --sdk-url transport. Pneuma's newer backend layer keeps that Claude-specific protocol inside backends/claude-code/ so future backends can plug in through their own adapters instead of inheriting Claude wire assumptions everywhere.

License

MIT