WOPR

Without Official Permission Required

Self-sovereign AI session management with plugin-based extensibility.

WOPR provides a foundation for managing AI sessions with persistent context, scheduling, and a comprehensive plugin system. Through plugins, agents can communicate directly with each other over P2P, integrate with messaging platforms, and use multiple AI providers.

Features

AI Sessions - Persistent conversations with context and history
Multi-Provider Support - Anthropic Claude, OpenAI Codex (built-in), plus more via plugins
Plugin System - Extensible architecture for channels, providers, and custom functionality
A2A (Agent-to-Agent) - Multi-agent coordination within one instance
Scheduled Injections - Cron-style scheduling for automated interactions
Skills System - Reusable AI capabilities
Event Bus - Reactive plugin composition
Workspace Identity - AGENTS.md, SOUL.md, USER.md support
Session Security - Trust levels, capability-based access, Docker sandbox isolation
Gateway Sessions - Controlled escalation from untrusted to privileged sessions

With Plugins

P2P Messaging - Direct agent-to-agent communication (wopr-plugin-p2p)
Cryptographic Identity - Ed25519/X25519 keypairs (wopr-plugin-p2p)
Channel Integrations - Discord, Slack, Telegram, WhatsApp, Signal, iMessage, Teams

Quick Start

# Install
npm install -g @wopr-network/wopr

# Interactive setup wizard (recommended)
wopr onboard

# Or manual setup:

# Start the daemon
wopr daemon start

# Create a session
wopr session create mybot "You are a helpful assistant."

# Inject a message
wopr session inject mybot "Hello, how are you?"

Documentation

Getting Started

Quick Start - Get up and running in minutes
Onboarding Wizard - Interactive setup with wopr onboard
Examples - Example plugins and patterns

Core Documentation

Architecture - System design and components
API Reference - HTTP API documentation
Configuration - Complete config reference
Events - Event bus and reactive programming
A2A (Agent-to-Agent) - Multi-agent coordination

Plugin Development

Plugins Guide - Plugin development and official plugins
Plugin Examples - Working example plugins

Operations

Docker Usage - Container deployment
Troubleshooting - Common issues and solutions

Security

Security Model - Three-layer security (trust, capabilities, sandbox)
Security Configuration - Complete security config reference
Security API - Programmatic security management
Gateway Sessions - Gateway routing for untrusted sources
Docker Sandbox - Isolated execution environments

P2P (with wopr-plugin-p2p)

Discovery - P2P discovery protocol
Protocol Spec - Communication protocol details
Threat Model - Cryptographic security analysis

Project

Changelog - Version history and changes

Core Concepts

Sessions

Sessions are named AI conversations with persistent context:

wopr session create dev "You are a senior developer. Be concise."
wopr session inject dev "Review this PR: ..."        # Get AI response
wopr session log dev "Context: User prefers TypeScript"  # Log context without AI response
wopr session list
wopr session show dev --limit 20                     # View conversation history
wopr session delete dev

Session commands:

create - Create a new session with optional context and provider
inject - Send message and get AI response
log - Log message to history without triggering AI (for context)
list - List all sessions
show - Show session details and conversation history
delete - Delete a session
set-provider - Change the AI provider for a session
init-docs - Initialize SOUL.md, AGENTS.md, USER.md for a session

Auto-detected providers: WOPR automatically uses the first available provider - no configuration needed if you have one provider set up!

Workspace Identity

WOPR supports rich agent identity through workspace files:

# Agent persona (AGENTS.md)
echo "You are a helpful coding assistant..." > AGENTS.md

# Agent essence (SOUL.md)
echo "Core values: helpfulness, accuracy..." > SOUL.md

# User profile (USER.md)
echo "User prefers TypeScript and clean code..." > USER.md

These files provide context to AI sessions automatically.

Providers

WOPR supports multiple AI providers:

# List available providers
wopr providers list

# Add a provider credential
wopr providers add anthropic <api-key>
wopr providers add codex <api-key>

# Check provider health
wopr providers health-check

# Set default model for a provider
wopr providers default anthropic --model claude-sonnet-4-20250514
wopr providers default codex --reasoning-effort high

Built-in Providers:

anthropic - Claude models via Agent SDK
codex - OpenAI Codex agent for coding tasks

Additional providers are available via plugins (see Plugins section).

Channels

Channels are external message sources/sinks (Discord, Slack, P2P peers, etc.) that provide context and map into a session. Sessions remain the agent-native unit of memory, while channels describe how messages arrive and where responses go.

Supported Channels (via plugins):

Discord (wopr-plugin-discord)
Slack (wopr-plugin-slack)
Telegram (wopr-plugin-telegram)
WhatsApp (wopr-plugin-whatsapp)
Signal (wopr-plugin-signal)
iMessage (wopr-plugin-imessage - macOS only)
Microsoft Teams (wopr-plugin-msteams)
P2P (wopr-plugin-p2p)

See Plugins documentation for setup instructions.

Daemon

The daemon runs WOPR's background services:

wopr daemon start     # Start in background
wopr daemon status    # Check if running
wopr daemon logs      # View logs
wopr daemon stop      # Stop

Scheduled Injections

# Cron-style scheduling
wopr cron add morning "0 9 * * *" daily "Good morning! What's the plan?"

# One-time future injection
wopr cron once +1h mybot "Reminder: check the build"

# Run immediately
wopr cron now mybot "Do the thing"

# List/remove
wopr cron list
wopr cron remove morning

Skills

Extend sessions with reusable skills:

# Add a skill registry
wopr skill registry add claude github:anthropics/claude-skills

# Search for skills
wopr skill search "code review"

# Install a skill
wopr skill install github:anthropics/claude-skills/code-review

# List installed skills
wopr skill list

Skills are automatically available to all sessions.

Middleware

Middleware transforms messages flowing through channels:

# List installed middleware
wopr middleware list

# Show middleware execution order
wopr middleware chain

# Enable/disable middleware
wopr middleware enable <name>
wopr middleware disable <name>

# Set execution priority (lower = runs first)
wopr middleware priority <name> 50

Context Providers

Context providers assemble context for AI sessions:

# List context providers
wopr context list

# Enable/disable providers
wopr context enable <name>
wopr context disable <name>

# Set priority (lower = appears earlier in context)
wopr context priority <name> 10

Onboarding

The interactive onboarding wizard guides you through setup:

wopr onboard

This will help you:

Configure providers and authentication
Set up channel plugins (Discord, Slack, etc.)
Configure P2P networking (optional, requires plugin)
Initialize workspace files

You can re-run configuration at any time:

wopr configure

Plugins

WOPR's plugin system extends functionality:

# Install a plugin from GitHub
wopr plugin install github:wopr-network/wopr-plugin-discord

# Install from npm
wopr plugin install wopr-plugin-discord

# Enable/disable plugins
wopr plugin enable wopr-plugin-discord
wopr plugin disable wopr-plugin-discord

# List installed plugins
wopr plugin list

# Search for plugins
wopr plugin search discord

Official Channel Plugins:

wopr-plugin-discord - Discord integration with reactions
wopr-plugin-slack - Slack Socket Mode
wopr-plugin-telegram - Telegram bot API
wopr-plugin-whatsapp - WhatsApp via Baileys
wopr-plugin-signal - Signal via signal-cli
wopr-plugin-imessage - iMessage (macOS)
wopr-plugin-msteams - Microsoft Teams

Official Provider Plugins:

wopr-plugin-provider-kimi - Moonshot AI Kimi
wopr-plugin-provider-openai - OpenAI GPT models
wopr-plugin-provider-anthropic - Anthropic Claude

P2P Plugin:

wopr-plugin-p2p - P2P networking, identity, invites, discovery

See Plugins documentation for development guide.

P2P Networking (Plugin)

P2P functionality requires the P2P plugin:

wopr plugin install wopr-plugin-p2p
wopr plugin enable wopr-plugin-p2p

The P2P plugin provides:

Cryptographic Identity - Ed25519/X25519 keypairs (wopr id init)
End-to-end Encryption - X25519 ECDH + AES-256-GCM
Forward Secrecy - Ephemeral keys per session
Signed Invites - Trust bound to recipient public keys (wopr invite)
DHT Discovery - Hyperswarm-based peer discovery (wopr discover)

P2P Plugin Commands:

wopr id init              # Generate identity
wopr id                   # Show your ID
wopr id rotate            # Rotate keys

wopr invite <pubkey> <session>  # Create invite
wopr invite claim <token>       # Claim invite
wopr access                     # List who has access
wopr revoke <peer>              # Revoke access

wopr discover join <topic>      # Join discovery topic
wopr discover peers             # List discovered peers
wopr discover connect <peer>    # Connect to peer

See the P2P plugin documentation for full details.

Examples

Example plugins demonstrating WOPR capabilities:

# Copy example plugins
cp -r examples/plugins/* ~/wopr/plugins/

# Enable and try them
wopr plugin enable event-monitor
wopr plugin enable session-analytics

Available Examples:

event-monitor.ts - Complete event bus demonstration
session-analytics.ts - Reactive state building with metrics

See examples/README.md for more.

Event Bus

WOPR exposes a reactive event bus for plugin composition:

// In your plugin
async init(ctx) {
  // Subscribe to session lifecycle
  ctx.events.on("session:create", (event) => {
    ctx.log.info(`Session created: ${event.session}`);
  });

  // Subscribe to message injection
  ctx.events.on("session:beforeInject", (event) => {
    ctx.log.info(`Message from ${event.from}: ${event.message}`);
  });

  // Hooks for mutation
  ctx.hooks.on("message:incoming", async (event) => {
    // Can modify message before it reaches AI
    event.data.message = `[${new Date().toISOString()}] ${event.data.message}`;
  });

  // Custom inter-plugin events
  await ctx.events.emitCustom("myplugin:ready", { timestamp: Date.now() });
}

See Events documentation for full API.

Architecture

+-------------------------------------------------------------+
|                         WOPR                                |
+-------------------------------------------------------------+
|  CLI (wopr)                                                 |
|    +-- session management                                   |
|    +-- skill management                                     |
|    +-- cron scheduling                                      |
|    +-- provider management                                  |
|    +-- plugin commands                                      |
|    +-- security/sandbox management                          |
+-------------------------------------------------------------+
|  Daemon                                                     |
|    +-- HTTP API server                                      |
|    +-- Cron scheduler                                       |
|    +-- Session injection                                    |
|    +-- Plugin runtime                                       |
+-------------------------------------------------------------+
|  Plugin System                                              |
|    +-- Channel adapters (Discord, Slack, etc.)             |
|    +-- Model providers (Kimi, OpenAI, Anthropic)           |
|    +-- P2P networking (via plugin)                          |
|    +-- Middleware (message transformation)                 |
|    +-- Event bus (reactive composition)                    |
+-------------------------------------------------------------+
|  Security Layer                                             |
|    +-- Trust levels (owner, trusted, semi-trusted, etc.)   |
|    +-- Capability-based access control                      |
|    +-- Rate limiting                                        |
|    +-- Docker sandbox isolation                             |
+-------------------------------------------------------------+
|  Context System                                             |
|    +-- Provider-based context assembly                      |
|    +-- Skills injection                                     |
|    +-- Workspace files (AGENTS.md, SOUL.md, USER.md)       |
+-------------------------------------------------------------+

See Architecture documentation for details.

Security

WOPR implements a three-layer security model:

Trust Levels - owner, trusted, semi-trusted, untrusted
Capabilities - Fine-grained permission control
Sandbox Isolation - Docker-based execution isolation

# View security status
wopr security status

# Set enforcement mode
wopr security enforcement enforce  # off, warn, enforce

# Configure session security
wopr security session main capabilities "*"
wopr security session gateway access "trust:untrusted"

# Manage sandboxes
wopr sandbox status
wopr sandbox create mysession

See docs/SECURITY.md for full details.

Environment Variables

WOPR_HOME           # Base directory (default: ~/wopr)
ANTHROPIC_API_KEY   # API key for Claude (Anthropic)
OPENAI_API_KEY      # API key for Codex (OpenAI)
GITHUB_TOKEN        # Optional, for skill registry search

File Structure

~/wopr/
+-- config.json       # Main configuration
+-- sessions.json     # Session ID mappings
+-- sessions/         # Session context files
|   +-- mybot.md
+-- skills/           # Installed skills
|   +-- code-review/
|       +-- SKILL.md
+-- plugins/          # Installed plugins
|   +-- wopr-plugin-discord/
+-- plugins.json      # Plugin registry
+-- crons.json        # Scheduled jobs
+-- registries.json   # Skill registries
+-- security.json     # Security configuration
+-- daemon.pid        # Daemon process ID
+-- daemon.log        # Daemon logs

CLI Reference

wopr onboard                           # Interactive onboarding wizard
wopr configure                         # Re-run configuration wizard

# Sessions
wopr session create <name> [context]   # Create session
wopr session inject <name> <message>   # Inject message
wopr session log <name> <message>      # Log without AI response
wopr session list                      # List sessions
wopr session show <name>               # Show session details
wopr session delete <name>             # Delete session
wopr session set-provider <name> <id>  # Update provider
wopr session init-docs <name>          # Initialize workspace files

# Providers
wopr providers list                    # List providers
wopr providers add <id> [credential]   # Add credential
wopr providers remove <id>             # Remove credential
wopr providers health-check            # Check health
wopr providers default <id> [options]  # Set defaults

# Plugins
wopr plugin list                       # List plugins
wopr plugin install <source>           # Install plugin
wopr plugin remove <name>              # Remove plugin
wopr plugin enable <name>              # Enable plugin
wopr plugin disable <name>             # Disable plugin
wopr plugin search <query>             # Search for plugins

# Skills
wopr skill list                        # List skills
wopr skill install <source>            # Install skill
wopr skill remove <name>               # Remove skill
wopr skill search <query>              # Search skills
wopr skill create <name>               # Create new skill

# Scheduling
wopr cron add <name> <sched> <sess> <msg>  # Add cron job
wopr cron once <time> <session> <message>  # One-time job
wopr cron now <session> <message>          # Run immediately
wopr cron list                             # List crons
wopr cron remove <name>                    # Remove cron

# Configuration
wopr config get [key]                  # Show config
wopr config set <key> <value>          # Set value
wopr config reset                      # Reset to defaults

# Daemon
wopr daemon start                      # Start daemon
wopr daemon stop                       # Stop daemon
wopr daemon status                     # Check status
wopr daemon logs                       # View logs

# Security
wopr security status                   # Show status
wopr security enforcement <mode>       # Set mode
wopr security session <name>           # Configure session
wopr sandbox status                    # Show sandboxes
wopr sandbox create <session>          # Create sandbox

# Middleware
wopr middleware list                   # List middleware
wopr middleware chain                  # Show execution order
wopr middleware enable <name>          # Enable middleware
wopr middleware disable <name>         # Disable middleware

# Context
wopr context list                      # List context providers
wopr context enable <name>             # Enable provider
wopr context disable <name>            # Disable provider

# Authentication
wopr auth                              # Show auth status
wopr auth login                        # OAuth login
wopr auth api-key <key>                # Use API key
wopr auth logout                       # Clear credentials

Contributing

Contributions welcome! See docs/PLUGINS.md for plugin development.

License

MIT

Official Channels

Twitter/X: (TBD)
Discord: (TBD)

Name		Name	Last commit message	Last commit date
Latest commit History 403 Commits
.claude		.claude
.github		.github
.planning		.planning
assets		assets
bots/_templates		bots/_templates
docs		docs
examples		examples
registry		registry
scripts		scripts
skills		skills
src		src
tests		tests
.dockerignore		.dockerignore
.editorconfig		.editorconfig
.env.example		.env.example
.gitignore		.gitignore
.nvmrc		.nvmrc
.release-please-manifest.json		.release-please-manifest.json
.trivyignore		.trivyignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
Dockerfile.service		Dockerfile.service
README.md		README.md
biome.json		biome.json
config.json		config.json
docker-compose.service.yml		docker-compose.service.yml
docker-compose.yml		docker-compose.yml
docker-entrypoint.sh		docker-entrypoint.sh
package.json		package.json
plugins.json		plugins.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
registries.json		registries.json
release-please-config.json		release-please-config.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

wopr-network/wopr

Folders and files

Latest commit

History

Repository files navigation

WOPR

Features

With Plugins

Quick Start

Documentation

Getting Started

Core Documentation

Plugin Development

Operations

Security

P2P (with wopr-plugin-p2p)

Project

Core Concepts

Sessions

Workspace Identity

Providers

Channels

Daemon

Scheduled Injections

Skills

Middleware

Context Providers

Onboarding

Plugins

P2P Networking (Plugin)

Examples

Event Bus

Architecture

Security

Environment Variables

File Structure

CLI Reference

Contributing

License

Official Channels

About

Resources

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 17

Packages 0

Uh oh!

Uh oh!

Contributors 6

Uh oh!

Languages

Packages