pneuma-skills

"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.

| Pillar | What it does | |--------|-------------| | Visual Environment | Agent edits files on disk; you see, select, and guide the rendered result in a live, bidirectional workspace | | Skills | Domain-specific knowledge and seed templates injected per mode. Sessions persist across runs — the agent picks up where it left off | | User Preferences | The agent builds and maintains a persistent portrait of your aesthetics, collaboration style, and per-mode habits — preferences survive across sessions, workspaces, and modes | | Continuous Learning | Evolution Agent mines conversation history to extract preferences, then augments skills with learned knowledge | | Distribution | Build custom modes with AI via Mode Maker, publish to the marketplace, share with pneuma mode add |

Built-in Modes

| Mode | What it does | Version | |------|-------------|---------| | webcraft | Live web development with Impeccable AI design intelligence — 20 design commands, responsive preview, export | 2.18.0 | | slide | HTML presentations — content sets, drag-reorder, presenter mode, PDF/image export. Skill design guidelines informed by frontend-slides | 2.18.0 | | doc | Markdown documents with live preview — the simplest mode, a minimal example of the mode system | 2.18.0 | | draw | Diagrams and visual thinking on an Excalidraw canvas | 2.18.0 | | diagram | Professional draw.io diagrams — flowcharts, architecture, UML, ER, with streaming render and sketch style | 2.27.0 | | illustrate | AI illustration studio — generate and curate visual assets on a row-based canvas with content sets | 2.18.0 | | mode-maker | Create custom modes with AI — fork, play-test, publish | 2.18.0 | | evolve | Evolution Agent — analyze history, propose skill improvements, apply/rollback | 2.25.0 |

Getting Started

Desktop App (recommended)

Download the latest release for your platform:

| Platform | Download | |----------|----------| | macOS (Apple Silicon) | .dmg | | Windows x64 | .exe installer | | Windows ARM64 | .exe installer | | Linux x64 | .AppImage / .deb |

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
  diagram                      draw.io diagrams
  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/:

| Contract | Responsibility | Extend to... | |----------|---------------|-------------| | ModeManifest | Skill, viewer config, agent preferences, init seeds | New modes (mindmap, canvas, etc.) | | ViewerContract | Preview component, context extraction, action protocol | Custom renderers, viewport tracking | | AgentBackend | Launch, resume, kill, capability declaration | Other agents (Aider, etc.) |

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.

User Preferences

Pneuma agents remember who you are. Every mode ships with a built-in preference skill that lets the agent build and maintain a persistent portrait of your tastes and habits:

~/.pneuma/preferences/
├── profile.md        ← cross-mode: aesthetics, language, collaboration style
├── mode-slide.md     ← slide-specific: layout density, color tendencies, font choices
├── mode-webcraft.md  ← webcraft-specific: design patterns, component preferences
└── ...

How it works:

• The agent reads your preferences before making design or style decisions — silently, without asking
• When it notices a stable pattern or you state a preference, it updates the files — silently, without announcing
• Hard constraints (e.g. "never use dark backgrounds") are marked as critical and auto-injected into every session startup
• A changelog at the end of each file lets the agent do incremental refreshes instead of re-analyzing everything

Three layers of understanding:

1. Observable — language, aesthetics, collaboration style (a few sessions)
2. Deep profile — value anchors, latent patterns, contradictions (many sessions, evidence-required)
3. Per-mode — concrete habits in each mode, with explicit user-stated vs. agent-observed distinction

The preference files are living documents — full rewrites, not append-only logs. Contradictions are preserved, not resolved. Everything is deletable. The agent builds understanding over time, not a label database.

Quick start tip: If you already have a history of working with Claude Code, try asking the agent in any mo