pneuma-skills

<p align="center"> <img src="docs/images/pneuma-logo-helix_2.png" alt="Pneuma" width="120" /> </p> <h1 align="center">Pneuma Skills</h1> <p align="center"><strong>Co-creation Infrastructure for Humans × Code Agents</strong></p> <p align="center">Visual environment, skills, continuous learning, and distribution — <br>everything humans and agents need to build content together.</p> <p align="center"><strong>Works with</strong></p> <table align="center"><tr> <td align="center" width="160"> <a href="https://docs.anthropic.com/en/docs/claude-code"> <img src="docs/images/backends/claude-code.png" alt="Claude Code" width="72" height="72" /> <br /><strong>Claude Code</strong> </a> <br />_{by Anthropic} </td> <td align="center" width="160"> <a href="https://github.com/openai/codex"> <img src="docs/images/backends/codex.png" alt="Codex" width="72" height="72" /> <br /><strong>Codex</strong> </a> <br />_{by OpenAI} </td> <td align="center" width="160"> <a href="https://moonshotai.github.io/kimi-code/"> <img src="docs/images/backends/kimi.png" alt="Kimi" width="72" height="72" /> <br /><strong>Kimi</strong> </a> <br />_{by Moonshot AI} </td> </tr></table> <p align="center"> <a href="https://www.npmjs.com/package/pneuma-skills"><img src="https://img.shields.io/npm/v/pneuma-skills.svg" alt="npm version" /></a> <a href="https://www.npmjs.com/package/pneuma-skills"><img src="https://img.shields.io/npm/dm/pneuma-skills.svg" alt="npm downloads" /></a> <a href="https://github.com/pandazki/pneuma-skills/releases"><img src="https://img.shields.io/github/v/release/pandazki/pneuma-skills?label=desktop" alt="Desktop release" /></a> <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT License" /></a> </p> <p align="center"> <a href="README.zh.md">中文</a> · <a href="#built-in-modes">Modes</a> · <a href="#getting-started">Getting started</a> · <a href="#projects-30">Projects</a> </p> <p align="center"> <img src="docs/images/slide-mode-screenshot.png" alt="Pneuma Slide Mode" width="800" /> </p> <pre align="center">bunx pneuma-skills slide --workspace ./my-first-pneuma-slide</pre>

---

"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's bet is simple: coding agents already do the work; what's missing is a way for people to watch them and participate at the right moments. Agents live in files on disk — that's their native habitat and we don't try to abstract it away. Instead, we give each task a live player that renders the work in domain terms (a deck of slides, a board of tiles, a project) and let humans drop in direct edits or structured suggestions without breaking the agent's flow. 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 works directly in files on disk — its native surface. Viewers are live players for agent output rendered in domain terms, with optional human participation directly in the UI. | | 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 | |------|-------------| | webcraft | Live web development with Impeccable AI design intelligence — 22 design commands, brand vs product register, responsive preview, export | | clipcraft | AI-orchestrated video production on @pneuma-craft — assets, composition with tracks/clips, provenance DAG, scenes; canvas preview + 3D timeline + dive panels; image / video / TTS / BGM generation scripts | | kami | Paper-canvas typesetting — locked paper size (A4/A5/A3/Letter/Legal × portrait/landscape), Scroll / Focus / Book views, fit-discipline feedback loop, PDF / PNG / HTML export. Design language adapted from tw93/kami | | slide | HTML presentations — content sets, drag-reorder, presenter mode, PDF/image export. Skill design guidelines informed by frontend-slides | | doc | Markdown documents with live preview — the simplest mode, a minimal example of the mode system | | draw | Diagrams and visual thinking on an Excalidraw canvas | | diagram | Professional draw.io diagrams — flowcharts, architecture, UML, ER, with streaming render and sketch style | | illustrate | AI illustration studio — generate and curate visual assets on a row-based canvas with content sets | | remotion | Code-driven video composition on Remotion — live preview, frame-perfect animation, MP4/WebM export via WebCodecs | | gridboard | Interactive dashboards — draggable tile grid on a fixed canvas, JIT-compiled React tiles via defineTile(), agent-driven redesign on resize | | cosmos | Project any content — code, prose, research, business — into a structured cosmos: an interactive graph that lays its inner shape bare. Schema and dashboard tech borrow from Lum1104/Understand-Anything (MIT) | | wordtaste | Human-in-the-loop Chinese long-form writing — shape the argument and its strongest landing points first, write sequential units in isolated contexts, check with a fresh model family (Claude Code / Codex), and finish through finite repair with human gates | | mode-maker | Create custom modes with AI — fork, play-test, publish | | evolve | Evolution Agent — analyze history, propose skill improvements, apply/rollback |

Each mode versions independently. Per-mode versions surface in the launcher and on the mode marketplace — they're not duplicated here to avoid drift.

First Run — Pneuma Walks You Through It

Create a project and Pneuma greets you on the way in. A hidden project-onboard mode auto-runs the first time you open a fresh project: it reads your README, package manifest, and visual assets, then drafts a Discovery Report — what your project is, what's already there, and two concrete next moves you can pick with one click.

<p align="center"> <img src="modes/project-onboard/viewer/illustrations/04-auto-discovery.png" alt="Pneuma reading a fresh project, anchor cards filling in" width="720" /> </p>

While the onboarding agent works (~30–60s), the loading slot becomes a 10-frame carousel introducing what Pneuma actually is — agents working in real files, twelve modes sharing one shell, sessions that share a project's brain. By the time the report lands, you already have the map.

For projects that are nearly empty (just a test.txt or a stub README), the agent draws a small welcome egg — a paper lantern in the dusk, a notebook with constellations being sketched — and writes a short greeting that matches your tone. Projects with content but no logo get an auto-generated cover so the launcher tile stops showing the dotted-letter placeholder. Both gestures only fire when an image-gen API key is configured; otherwise the report still renders, just without the gift.

Prefer to set things up by hand? The Create Project dialog's chevron menu offers Create without discovery — you can still trigger discovery later via ProjectPanel's Re-discover affordance.

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, Codex, and Moonshot Kimi are implemented.

CLI

# Prerequisites: Bun >= 1.3.5, plus one or more of: Claude Code CLI, Codex CLI, Kimi Code 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

<details> <summary><strong>Install from source</strong></summary>

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

</details>

CLI Usage

pneuma-skills [mode] [options]

Modes:
  (no argument)                Open the Launcher (marketplace UI)
  webcraft                     Web design with Impeccable.style
  clipcraft                    AI-orchestrated video production
  kami                         Paper-canvas typesetting
  slide                        HTML presentations
  doc                          Markdown with live preview
  draw                         Excalidraw canvas
  diagram                      draw.io diagrams
  illustrate                   AI illustration studio
  remotion                     Code-driven video composition
  gridboard                    Interactive tile dashboards
  wordtaste                    Chinese long-form writing loop
  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 (claude-code | codex | kimi-cli)
  --project <path>     Run as a session inside the project at <path>
  --session-id <id>    Resume a project session by id (with --project)
  --session-name <s>   Custom session display name
  --viewing            Start in viewing mode (no agent, no skill install)
  --no-open            Don't auto-open the browser
  --skip-skill         Skip skill installation (silent resume)
  --debug              Enable debug mode
  --dev                Force dev mode (Vite)

Subcommands:
  mode add <url>           Install a remote mode (single → ~/.pneuma/modes/; library → ~/.pneuma/libraries/)
  mode list                List published modes on R2
  mode publish             Publish current workspace as a mode
  library init <name>      Scaffold a new mode library locally; --github user/repo creates + pushes
  library link <source>    Alias for `mode add` when the source is a library
  library list             List linked libraries
  library sync <id>        Refresh a library from source
  library publish <mod