Prompt Objects

LLM-backed entities as first-class autonomous objects.

Why

Alan Kay's vision: "The key in making great and growable systems is much more to design how its modules communicate rather than what their internal properties and behaviors should be."

Prompt Objects applies this to AI. Instead of treating LLMs as external APIs you call, what if they were objects that communicate with each other? Markdown files become autonomous entities. They have identity, capabilities, and memory. They delegate to each other naturally.

This is a new computing primitive: semantic late binding at runtime, where natural language becomes the interface between intelligent components.

Who

  • Ruby developers exploring AI-native architectures
  • AI tinkerers who want to build systems that grow and adapt
  • Anyone frustrated with brittle prompt chains and rigid agent frameworks

What

A Ruby framework where:

  • Markdown files define autonomous entities (Prompt Objects)
  • YAML frontmatter declares capabilities and configuration
  • Markdown body becomes identity and behavior (the system prompt)
  • Capabilities are shared between primitives (Ruby) and Prompt Objects (markdown) -- everything is a capability
  • Environments isolate collections of objects with their own memory, git history, and configuration
  • PO-to-PO delegation lets objects call each other through isolated threads with full provenance tracking
  • Autonomous Prompt Objects can act on their own interval (autonomous: frontmatter), thinking and delegating without a human in the loop
  • Services run background work alongside the server, and environment-level sessions give every object a shared, durable key-value memory (env_data)
  • Artifacts let a PO render live HTML/JSX dashboards in the UI; external systems can drive POs over a REST endpoint (POST /api/messages)

Prompt Object structure

---
name: reader
description: Helps people understand files
capabilities:
  - read_file
  - list_files
---

# Reader
## Identity
You are a careful, thoughtful file reader...

Web UI

The web interface treats the environment as a running image rather than a chat application. Its views share the same durable workspaces, threads, runs, artifacts, and environment data:

  • Floor -- the default view: freely arranged, resizable PO stations with live artifacts, timer state, and delegation edges.
  • Browser -- a Smalltalk-style object browser for source, capabilities, environment data, multiple threads, chat, live activity, and timelines.
  • Image Floor -- a responsive wall of every PO's latest visual interface.
  • Semantic Loom -- a factual map of delegation, tools, shared state, and outputs around a selected PO.
  • Artifact Cockpit -- one live artifact at useful size with its revision, owner, provenance, and action traffic.
  • Run Debugger -- a durable execution timeline with model context, definition snapshots, tool executions, child runs, and state effects.

The Transcript remains available across views, and reconnects hydrate authoritative snapshots before replaying newer events.

Interactive artifacts (BURP)

POs can render HTML/JSX artifacts into a dockable pane (React 18, Tailwind, and Babel are available in a sandboxed iframe). Artifacts are bidirectional — the Bidirectional UI Rendering Protocol injects a PromptObjects.send(message) function into every artifact, which delivers a natural-language message back to the PO that rendered it (provenance shows as artifact:<title> in the message log). A PO can build a dashboard with buttons and forms, the human clicks instead of typing, and the PO re-renders the artifact in response: generative UI as a second modality of conversation. Works in the in-app pane and popped-out artifact windows.

Durable concurrent runtime

Each Prompt Object is a reusable definition; mutable execution belongs to durable runs inside PO-owned threads. A single PO can have multiple threads, and independent threads, delegations, and safe tool calls can execute concurrently. Resource keys serialize conflicting side effects, while bounded worker/provider permits, deadlines, cancellation, autonomous coalescing, and event retention keep long-running environments controlled. REST, WebSocket, CLI, MCP, services, connectors, timers, and artifact actions all enter through the same run path.

Generative music (Sonic Pi)

Music environments connect an ensemble of Prompt Objects to Sonic Pi over OSC. The conductor establishes a shared musical contract and coordinates musicians that author and rewrite their own synchronized parts.

  • music-beginner is a constrained, talk-safe backing ensemble with curated instruments, connected phrases, coordinated movements, and Gemini 3.5 Flash as its persisted default model.
  • music-pro exposes chords, samples, subdivisions, alternation, transforms, raw Sonic Pi parameters, runtime-defined patches, and duration-aware gating while preserving an audible connective layer.
  • music remains the open-ended dynamic-band template, and chiptune remains available for its original genre-specific workflow.

Demos

Intro walkthrough ARC-AGI-1 template
Intro walkthrough: creating an environment, interacting with POs, and exploring the web UI ARC-AGI-1 template: using the ARC-AGI-1 solver environment with multi-PO delegation

MCP Server mode

Run any environment as an MCP (Model Context Protocol) server for integration with Claude Desktop, Cursor, or any MCP-compatible client:

prompt_objects serve my-assistant --mcp

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "my-assistant": {
      "command": "prompt_objects",
      "args": ["serve", "--mcp", "my-assistant"]
    }
  }
}

Exposes tools for sending messages, listing POs, inspecting state, getting conversations, and responding to pending capability-approval requests. Message responses include durable workspace, thread, and run IDs. Pass a client_request_id when retries are possible; thread_id continues a specific conversation (session_id remains a compatibility alias).

External services can enqueue the same runtime through REST:

curl -X POST http://127.0.0.1:3000/api/messages \
  -H 'Content-Type: application/json' \
  -d '{"target_po":"assistant","content":"Process this event","from_source":"service:webhook","client_request_id":"event-42"}'

The response contains workspace_session_id, thread_id, run_id, status, and the Prompt Object response. Workspace and thread IDs may be omitted to use source-appropriate defaults.

Multi-provider LLM support

Choose a provider/model in the UI; the selection is stored in the environment manifest and survives restarts. API keys come from the corresponding environment variables. Adapters include:

  • OpenAI -- GPT-5.6 Luna, Terra, and Sol; GPT-5.4 Mini/Nano; GPT-5.2; GPT-4.1
  • Anthropic -- Claude Haiku 4.5, Claude Sonnet 4.5, Claude Opus 4
  • Gemini -- Gemini 3.5 Flash, Gemini 3.1 Flash Lite, Gemini 3 Flash, Gemini 2.5 Pro/Flash
  • Ollama -- any locally installed model, discovered automatically
  • OpenRouter -- access any model through a single API key

Thread Explorer

A standalone HTML visualizer for exported conversation threads. Open it from the CLI to browse delegation chains, message flow, and tool call sequences:

prompt_objects explore my-env
prompt_objects explore my-env --session abc123

How

Installation

gem install prompt_objects

Quick Start

# Create an environment from a template
prompt_objects env create my-project --template basic

# Run and open the web interface
prompt_objects serve my-project --open

The gem also installs poop (Prompt-Object Oriented Programming) as an alias for the prompt_objects command. Every example below works with either.

Commands

prompt_objects serve <env>                  Start web server (default)
prompt_objects serve <env> --open           Start and open browser
prompt_objects serve <env> --mcp            Start as MCP server
prompt_objects serve <env> --port 4000      Custom port (default: 3000)
prompt_objects --version                    Print the installed version

prompt_objects repl [name] [objects_dir]    Interactive REPL with a prompt object
prompt_objects repl --sandbox               REPL in sandbox mode (isolates changes)

prompt_objects message <env> <po> "text"    Send a message and print the response
prompt_objects message <env> <po> "text" --json     JSON output
prompt_objects message <env> <po> "text" --events   Include event log

prompt_objects events <env>                 Show recent message bus events
prompt_objects events <env> --session ID    Events for a specific session
prompt_objects events <env> --json          JSON output
prompt_objects diagnostics <env> --json     Content-free runtime health

prompt_objects explore [env]                Open Thread Explorer in browser
prompt_objects explore <env> --session ID   Visualize a specific thread

Environment management

prompt_objects env list                     List all environments
prompt_objects env create <name>            Create new environment
prompt_objects env create <name> -t <tmpl>  Create from template
prompt_objects env info <name>              Show environment details
prompt_objects env clone <src> <dst>        Clone an environment
prompt_objects env export <name>            Export as .dump bundle
prompt_objects env import <file.dump>       Import from bundle (.poenv still works)
prompt_objects env archive <name>           Soft-delete (archive)
prompt_objects env restore <name>           Restore archived environment
prompt_objects env delete <name> --permanent  Permanently delete archived env
prompt_objects env default <name>           Set the default environment

Exports are Declarative Unified Memory Packages — a .dump file is a git bundle of the environment's complete state and history.

Operational guidance: runtime diagnostics and recovery and the release rehearsal checklist.

Templates

Create an environment from a template with prompt_objects env create <name> --template <template>:

Template Description
basic No capabilities, learns as needed -- great for demos
minimal Basic assistant with file reading
developer Code review, debugging, testing specialists
writer Editor, researcher for content creation
empty Start from scratch with just a bootstrap assistant
arc-agi-1 ARC-AGI-1 challenge solver with grid primitives
arc-agi-3 ARC-AGI-3 agent with player, analyst, and strategist POs
chiptune Collaborative chiptune band — conductor + voice POs driving Sonic Pi
music Genre-agnostic band — the conductor builds voices for any style on the fly
music-beginner Talk-safe generative backing ensemble with curated Sonic Pi instruments
music-pro Expressive live-pattern ensemble with independent voice POs and raw Sonic Pi patches

Extras

Community

Join the Discord for support, discussion, and updates.

Blog Posts