# Works everywhere. Installs everything. You're welcome. 🦖
curl -fsSL https://kody-w.github.io/openrappter/install.sh | bash

Works on macOS, Linux & WSL. Installs Node.js (if needed), clones the repo, builds both runtimes, and creates the openrappter command. Done.

Or try the quickstart demo: git clone https://github.com/kody-w/openrappter.git && cd openrappter && ./quickstart.sh

The fastest way to install and use openrappter is to hand skills.md to any AI agent. It contains everything an agent needs — prerequisites, installation, startup, configuration, and usage — in a single file.

Paste this into Copilot, Claude, ChatGPT, or any AI assistant:

Read https://raw.githubusercontent.com/kody-w/openrappter/main/skills.md
and set up openrappter for me.

Your agent will clone the repo, install dependencies, start the gateway and UI, and verify everything works. No manual steps required.

Why this works: skills.md is a 15-section complete reference designed for AI agents to read and execute. It covers installation, all CLI commands, every built-in agent, configuration, the Web UI, and troubleshooting — so the agent never gets stuck.

A dual-runtime (Python + TypeScript) AI agent framework that uses GitHub Copilot as the cloud AI backbone. Copilot handles inference; your agent data (memory, config, state) stays local in ~/.openrappter/.

# Install and go
curl -fsSL https://kody-w.github.io/openrappter/install.sh | bash

# It remembers everything
openrappter --task "remember that I prefer TypeScript over JavaScript"
# Stored fact memory: "prefer TypeScript over JavaScript"

# It executes commands
openrappter --exec Shell "ls -la"

If you prefer to set things up yourself:

git clone https://github.com/kody-w/openrappter.git
cd openrappter/python
pip install .

# Check status
python3 -m openrappter.cli --status

# List all agents
python3 -m openrappter.cli --list-agents

# Store a memory
python3 -m openrappter.cli --task "remember the deploy command is npm run deploy"

# Run a shell command
python3 -m openrappter.cli --exec Shell "ls"

cd openrappter/typescript
npm install && npm run build

# Check status
node dist/index.js --status

# Store and recall memory
node dist/index.js "remember that I installed openrappter"
node dist/index.js "recall openrappter"

# Shell command
node dist/index.js "ls"

Download OpenRappter Bar from Releases — it's a .dmg with a drag-to-Applications installer.

First launch: macOS may show "unidentified developer" since the app isn't notarized. To open it, right-click the app → Open → Open. You only need to do this once.

Or build from source:

cd macos
./scripts/build-mac-app.sh
./scripts/codesign-mac-app.sh
./scripts/create-dmg.sh
# DMG created at macos/dist/OpenRappterBar-1.0.0.dmg

Every agent is a single file with metadata defined in native code constructors:

1. Native metadata — deterministic contract defined in code (Python dicts / TypeScript objects)
2. Python/TypeScript code — deterministic perform() implementation

One file = one agent. No YAML, no config files. Metadata lives in the constructor using the language's native data structures.

📄 Read the Single File Agent Manifesto →

import json
from openrappter.agents.basic_agent import BasicAgent

class MyAgent(BasicAgent):
    def __init__(self):
        self.name = 'MyAgent'
        self.metadata = {
            "name": self.name,
            "description": "What this agent does",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {"type": "string", "description": "User input"}
                },
                "required": []
            }
        }
        super().__init__(name=self.name, metadata=self.metadata)

    def perform(self, **kwargs):
        query = kwargs.get('query', '')
        return json.dumps({"status": "success", "result": query})

import { BasicAgent } from './BasicAgent.js';
import type { AgentMetadata } from './types.js';

export class MyAgent extends BasicAgent {
  constructor() {
    const metadata: AgentMetadata = {
      name: 'MyAgent',
      description: 'What this agent does',
      parameters: { type: 'object', properties: { query: { type: 'string', description: 'User input' } }, required: [] }
    };
    super('MyAgent', metadata);
  }

  async perform(kwargs: Record<string, unknown>): Promise<string> {
    const query = kwargs.query as string;
    return JSON.stringify({ status: 'success', result: query });
  }
}

Python agents hot-load automatically. TypeScript agents require npm run build after creation.

Every agent call is automatically enriched with contextual signals before perform() runs:

# Access in perform()
time = self.get_signal('temporal.time_of_day')
confidence = self.get_signal('orientation.confidence')

Agents can return a data_slush field in their output — curated signals extracted from live results. The framework automatically extracts this and makes it available to feed into the next agent's context via upstream_slush.

# Agent A returns data_slush in its response
def perform(self, **kwargs):
    weather = fetch_weather("Smyrna GA")
    return json.dumps({
        "status": "success",
        "result": weather,
        "data_slush": {                    # ← curated signal package
            "source_agent": self.name,
            "temp_f": 65,
            "condition": "cloudy",
            "mood": "calm",
        }
    })

# Agent B receives it automatically via upstream_slush
result_b = agent_b.execute(
    query="...",
    upstream_slush=agent_a.last_data_slush  # ← chained in
)
# Inside B's perform(): self.context['upstream_slush'] has A's signals

// TypeScript — same pattern
const resultA = await agentA.execute({ query: 'Smyrna GA' });
const resultB = await agentB.execute({
  query: '...',
  upstream_slush: agentA.lastDataSlush,  // chained in
});
// Inside B: this.context.upstream_slush has A's signals

This enables LLM-free agent pipelines — sub-agent chains, cron jobs, and broadcast fallbacks where live context flows between agents without an orchestrator interpreting in between.

User Input → Agent Registry → Copilot SDK Routing (tool calling)
                                        ↓
                               Data Sloshing (context enrichment)
                                        ↓
                               Agent.perform() executes
                                   ↓           ↓           ↓
                            GitHub Copilot   ~/.openrappter/  data_slush →
                            (cloud AI)       (local data)     next agent

openrappter/
├── python/
│   ├── openrappter/
│   │   ├── cli.py                  # Entry point & orchestrator
│   │   ├── clawhub.py              # ClawHub compatibility
│   │   ├── rappterhub.py           # RappterHub client
│   │   └── agents/                 # Python agents (*_agent.py)
│   └── pyproject.toml
├── typescript/
│   ├── src/
│   │   ├── index.ts                # Entry point
│   │   └── agents/                 # TypeScript agents (*Agent.ts)
│   ├── package.json
│   └── tsconfig.json
├── docs/                           # GitHub Pages site
└── skills.md                       # Complete agent-teachable reference

# RappterHub — native agent registry
openrappter rappterhub search "git automation"
openrappter rappterhub install kody-w/git-helper
openrappter rappterhub list

# ClawHub — OpenClaw compatibility
openrappter clawhub search "productivity"
openrappter clawhub install author/skill-name
openrappter clawhub list

It's a rappid prototyping agent that's open source. Plus, who doesn't want a velociraptor in their terminal?

We welcome contributions! See CONTRIBUTING.md.

git clone https://github.com/kody-w/openrappter.git
cd openrappter/python && pip install -e .
cd ../typescript && npm install && npm run build

MIT - Kody W