Co-creation Infrastructure for Humans × Code Agents

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

Works with

Claude Code by Anthropic

Codex by OpenAI

Kimi by Moonshot AI

中文 · Modes · Getting started · Projects

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

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

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.

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.

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

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

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
  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 <mode>   Copy a local mode into a linked library; --to <id> --push
  library push <id>        Push the library's local clone to its remote
  library unlink <id>      Remove a library and its on-disk clone
  evolve <mode>            Analyze history, propose skill improvements
  plugin add <source>      Install a plugin from path/github/URL
  plugin list              List builtin + external plugins
  plugin remove <name>     Remove an external plugin
  history export [--out]   Export this session as a shareable .tar.gz
  history share [--title]  Export + upload to R2, return a link
  history open <path|url>  Download / prepare a replay package
  project add <path>       Register an existing project into the session registry
  snapshot push / pull     Upload / download workspace snapshot

┌─────────────────────────────────────────────────────────┐
│  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.

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 mode: "Do a full preference refresh from my session history." The agent will scan your past Pneuma sessions, extract your patterns and preferences, and build your profile in one pass — you might be surprised by what it picks up. Works with Claude Code, Codex, and Kimi backends.

Pneuma supports an optional Project layer above sessions — a way to anchor one ongoing thing across many sessions in many modes, with shared preferences and a shared project atlas.

A project is any user directory marked by <root>/.pneuma/project.json. Inside one you can:

• Run multiple sessions in different modes (doc + webcraft + kami + …) — all targeting the same project root, all sharing the same atlas and preferences
• Smart Handoff between modes — the source agent emits a structured <pneuma:request-handoff> tag, Pneuma surfaces a Handoff Card with intent + suggested files + key decisions, you confirm, and the target session spawns with the brief pre-staged in its CLAUDE.md
• Project-scoped preferences at <root>/.pneuma/preferences/, orthogonal to your global ~/.pneuma/preferences/ — both inject into every session's startup prompt
• Auto-onboarding the first time you enter a fresh project (see First Run above)

Quick (project-less) sessions remain fully supported — projects are opt-in. Create one from the launcher's "+ Create Project" button. The full design lives at docs/archive/proposals/2026-04-27-pneuma-projects-design.md (3.0 project layer) and 2026-04-28-handoff-tool-call.md (handoff protocol).

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

MIT