UREPL Skill: Universal REPL Protocol for Claude Code

**Version**: 0.2.0 **Status**: Phase 2 Self-Hosting Complete ✅ **Language**: Clojure (coordinator) + Scheme/Clojure/CL (targets) **License**: MIT

plurigrid/asi·0installs67stars

SKILL.md

Full skill instructions

UREPL Skill: Universal REPL Protocol for Claude Code

Version: 0.2.0 Status: Phase 2 Self-Hosting Complete ✅ Language: Clojure (coordinator) + Scheme/Clojure/CL (targets) License: MIT

Overview

UREPL (Universal REPL Protocol) is a skill for Claude Code that enables execution of code across three different languages (Scheme, Clojure, Common Lisp) through a unified interface with color-guided coordination.

This skill brings together:

📡 WebSocket Server for remote protocol execution
🔗 Multi-Language REPL Connectors (Geiser, nREPL, SLIME)
🎨 Color-Guided Execution with deterministic SplitMix64 RNG
📚 SRFI Management (10 Scheme standard library implementations)
🔄 3-Agent Architecture (Syntax/Semantics/Tests)

Installation

Via npm (recommended for Claude Code)

npm install -g urepl-skill

Via git (development)

git clone https://github.com/music-topos/urepl-skill.git
cd urepl-skill
npm install
npm run build
npm link  # Makes 'urepl' available globally

Verify Installation

urepl --version
# UREPL v0.2.0

urepl help
# Shows available commands

Usage in Claude Code

Execute Code in Any Dialect

/urepl execute scheme "(+ 1 2 3)" 42
/urepl execute clojure "(+ 1 2 3)" 42
/urepl execute lisp "(+ 1 2 3)" 42

Each execution:

Routes through the 3-agent coordinator
Gets annotated with deterministic color from seed
Returns syntax, semantics, and test results

Bootstrap the System

/urepl bootstrap
# Runs 12-step initialization with color guidance
# Seed: 42 (deterministic colors)

Initialization steps:

Connect to three REPLs
Set UREPL version in each
Load core SRFIs (2, 5, 26, 48)
Self-host the meta-interpreter
Enable color guidance

Load Scheme Requests for Implementation

/urepl load-srfi 26     # Cut/Cute (partial application)
/urepl load-srfi 2      # List predicates
/urepl load-srfi 48     # Formatted output

List Available SRFIs

/urepl list-srfis

# Output:
# Implemented SRFIs:
#   SRFI   2: List Predicates
#   SRFI   5: Compatible Let Syntax
#   SRFI  26: Cut/Cute (Partial Application)
#   SRFI  48: Intermediate Format Strings
#   SRFI  89: Factorial and Binomial
#   SRFI 135: Immutable Cyclic Data

Check Server Status

/urepl status

# Output:
# Messages: 42
# Errors: 0
# REPL Connections:
#   scheme: connected
#   clojure: connected
#   lisp: connected
# Loaded SRFIs: 2, 5, 26, 48

Start WebSocket Server

/urepl server 8765
# Server ready on port 8765

Server endpoints:

POST /urepl/execute - Execute code
POST /urepl/bootstrap - Run bootstrap
POST /urepl/srfi/:number - Load SRFI
GET /health - Health check
GET /status - Server status

CLI Commands Reference

Execute Code

urepl execute <dialect> <code> [seed]

Dialects: scheme | clojure | lisp
Seed: integer (default: 42)

Examples:
  urepl execute scheme "(+ 1 2 3)"
  urepl execute clojure "(* 4 5)" 999
  urepl execute lisp "(list 1 2 3)" 42

Bootstrap Sequence

urepl bootstrap [seed]

Seed: integer (default: 42)

Examples:
  urepl bootstrap
  urepl bootstrap 777

Load SRFI

urepl load-srfi <number>

Number: 1-200+ (SRFI number)

Examples:
  urepl load-srfi 26
  urepl load-srfi 2

List SRFIs

urepl list-srfis

# No arguments, shows all registered SRFIs

Check Status

urepl status

# Shows server health and connection status

Start Server

urepl server [port]

Port: integer (default: 8765)

Examples:
  urepl server 8765
  urepl server 9000

Architecture

System Layers

Claude Code / CLI
    ↓
UREPL Client (bin/urepl.js)
    ↓
WebSocket Server (src/urepl/server.clj)
    ↓
3-Agent Coordinator (src/urepl/coordinator.clj)
    ├─ Agent 1: Syntax (Geiser)
    ├─ Agent 2: Semantics (CIDER)
    └─ Agent 3: Tests (SLIME)
    ↓
REPL Connectors (src/urepl/repl-connectors.clj)
    ├─ Scheme REPL (Geiser Protocol)
    ├─ Clojure REPL (nREPL Protocol)
    └─ Common Lisp REPL (SLIME Protocol)
    ↓
Live REPL Processes
    ├─ Racket/Guile (Scheme)
    ├─ Clojure (nREPL)
    └─ SBCL/CCL (Common Lisp)

Color Guidance Flow

Seed (42)
  ↓
SplitMix64 RNG
  ↓
Golden Angle Spiral (137.508°)
  ↓
Deterministic Color Sequence
  ↓
Hex Colors (#RRGGBB)
  ↓
Annotate Execution Trace

System Requirements

Node.js

Version: 18.0.0 or higher
npm: 9.0.0 or higher

Install Node:

# macOS (via Homebrew)
brew install node

# Linux (via apt)
sudo apt-get install nodejs npm

# Windows (via Chocolatey)
choco install nodejs

REPL Backends (optional but required for live execution)

Scheme (Geiser):

# macOS
brew install racket
# Or: brew install guile

# Then in REPL:
(require (planet neil/geiser:1:2))

Clojure (nREPL):

brew install clojure
# Or: https://clojure.org/guides/getting_started

# Start nREPL server:
clojure -Sdeps '{:deps {nrepl/nrepl {:mvn/version "0.8.3"}}}'

Common Lisp (SLIME):

# macOS
brew install sbcl
# Or: brew install ccl

# In LISP REPL:
(require 'swank)
(swank:create-server)

Examples

Example 1: Basic Arithmetic

$ urepl execute scheme "(+ 1 2 3)"

🎨 UREPL Execute
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

ℹ Dialect: scheme
ℹ Code: (+ 1 2 3)
ℹ Seed: 42

✓ Execution completed

Result:
{
  "success": true,
  "value": 6,
  "color": "#FF6B35",
  "duration_ms": 142
}

Example 2: Bootstrap with Color Guidance

$ urepl bootstrap

🎨 UREPL Bootstrap Sequence
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

ℹ Seed: 42

Bootstrap steps:
  ✓ Initialize Scheme REPL [#FF6B35]
  ✓ Initialize Clojure REPL [#F7931E]
  ✓ Initialize Common Lisp REPL [#FBB03B]
  ✓ Set UREPL Version (Scheme) [#009CA3]
  ✓ Set UREPL Version (Clojure) [#7B68EE]
  ✓ Set UREPL Version (Common Lisp) [#FF1493]
  ✓ Load SRFI 2 (List Predicates) [#00CED1]
  ✓ Load SRFI 5 (Let Syntax) [#32CD32]
  ✓ Load SRFI 26 (Cut/Cute) [#FFD700]
  ✓ Load SRFI 48 (Formatted Output) [#FF6347]
  ✓ Self-Host UREPL Evaluator [#DC143C]
  ✓ Enable Color-Guided Execution [#FF69B4]

✓ Bootstrap complete: 12/12

Example 3: Load SRFI

$ urepl load-srfi 26

🎨 Load SRFI
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

ℹ Loading SRFI 26

✓ SRFI 26 loaded: Notation for Specializing Parameters without Currying

Provides:
  • cut
  • cute
  • <>
  • <...>

Configuration

Environment Variables

# UREPL Server Port
export UREPL_PORT=8765

# Scheme REPL Host:Port
export UREPL_SCHEME_HOST=localhost
export UREPL_SCHEME_PORT=4005

# Clojure REPL Host:Port
export UREPL_CLOJURE_HOST=localhost
export UREPL_CLOJURE_PORT=7888

# Common Lisp REPL Host:Port
export UREPL_LISP_HOST=localhost
export UREPL_LISP_PORT=4005

# Color Seed
export UREPL_SEED=42

Configuration File (future)

Create .urepl.config.json:

{
  "server": {
    "port": 8765,
    "host": "localhost"
  },
  "repls": {
    "scheme": {
      "host": "localhost",
      "port": 4005
    },
    "clojure": {
      "host": "localhost",
      "port": 7888
    },
    "lisp": {
      "host": "localhost",
      "port": 4005
    }
  },
  "bootstrap": {
    "seed": 42,
    "steps": 12
  },
  "srfis": {
    "auto_load": [2, 5, 26, 48]
  }
}

API Reference

WebSocket/REST API

POST /urepl/execute

Request:
{
  "type": "execute",
  "dialect": "scheme",
  "code": "(+ 1 2 3)",
  "seed": 42
}

Response:
{
  "success": true,
  "id": "uuid",
  "result": {
    "value": 6,
    "color": "#FF6B35"
  },
  "color_trace": [...],
  "duration_ms": 142
}

POST /urepl/bootstrap

Request:
{
  "type": "bootstrap",
  "seed": 42
}

Response:
{
  "success": true,
  "steps_completed": 12,
  "steps_total": 12,
  "results": [...]
}

POST /urepl/srfi/:number

POST /urepl/srfi/26

Response:
{
  "success": true,
  "srfi_number": 26,
  "srfi_title": "Notation for Specializing Parameters without Currying",
  "symbols": ["cut", "cute", "<>", "<...>"]
}

GET /health

Response:
{
  "status": "ok",
  "timestamp": "2025-12-21T22:15:00Z",
  "uptime_ms": 12345
}

GET /status

Response:
{
  "message_count": 42,
  "error_count": 0,
  "repl_status": {
    "scheme": "connected",
    "clojure": "connected",
    "lisp": "connected"
  },
  "loaded_srfis": [2, 5, 26, 48],
  "active_connections": 3
}

Development

Build from Source

git clone https://github.com/music-topos/urepl-skill.git
cd urepl-skill
npm install
npm run build
npm link

Run Tests

npm test                    # Run all tests
npm run test:connectors     # Test REPL connectors
npm run test:bootstrap      # Test bootstrap sequence

Lint Code

npm run lint

Clean Build Artifacts

npm run clean

Troubleshooting

Issue: Server won't start

# Check port is available
lsof -i :8765

# Try different port
urepl server 9000

# Check for process on port
sudo lsof -i :8765
# Kill if needed
kill -9 <PID>

Issue: REPL connections failing

# Verify backends are running
netstat -an | grep 4005  # Scheme REPL
netstat -an | grep 7888  # Clojure REPL

# Start backends manually:
# Terminal 1:
racket
(require (planet neil/geiser:1:2))

# Terminal 2:
clojure -Sdeps '{:deps {nrepl/nrepl {:mvn/version "0.8.3"}}}'

# Terminal 3:
sbcl
(require 'swank)
(swank:create-server)

# Then try:
urepl status

Issue: Colors not displaying

# Ensure terminal supports 256 colors
echo $TERM
# Should output: xterm-256color or similar

# Or set manually
export TERM=xterm-256color

# Then retry
urepl execute scheme "(+ 1 2)"

Performance

Benchmarks

Startup Time: ~500ms (including REPL connections)
Code Execution: ~100-200ms per command
Bootstrap Sequence: ~2-3 seconds (12 steps)
Color Generation: <1ms (deterministic)

Optimization Tips

Keep REPL processes warm (don't disconnect between calls)
Use connection pooling for multiple executions
Batch multiple commands in bootstrap sequence
Cache SRFI metadata after first load

Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch
Write tests for new functionality
Submit a pull request

License

MIT - See LICENSE file for details

Credits

Color Guidance: Gay.jl (deterministic color generation)
REPL Protocols: Geiser, nREPL, SLIME communities
Framework: Music-Topos project
Maintenance: Claude Code team

Install skill

Copy and run in your terminal

npx -y skills add https://github.com/plurigrid/asi --skill README_UREPL_SKILL.md

View on GitHub

ies/music-topos/README_UREPL_SKILL.md

UREPL Skill: Universal REPL Protocol for Claude Code

SKILL.md

UREPL Skill: Universal REPL Protocol for Claude Code

Overview

Installation

Via npm (recommended for Claude Code)

Via git (development)

Verify Installation

Usage in Claude Code

Execute Code in Any Dialect

Bootstrap the System

Load Scheme Requests for Implementation

List Available SRFIs

Check Server Status

Start WebSocket Server

CLI Commands Reference

Execute Code

Bootstrap Sequence

Load SRFI

List SRFIs

Check Status

Start Server

Architecture

System Layers

Color Guidance Flow

System Requirements

Node.js

REPL Backends (optional but required for live execution)

Examples

Example 1: Basic Arithmetic

Example 2: Bootstrap with Color Guidance

Example 3: Load SRFI

Configuration

Environment Variables

Configuration File (future)

API Reference

WebSocket/​REST API

POST /​urepl/​execute

POST /​urepl/​bootstrap

POST /​urepl/​srfi/:number

GET /​health

GET /​status

Development

Build from Source

Run Tests

Lint Code

Clean Build Artifacts

Troubleshooting

Issue: Server won't start

Issue: REPL connections failing

Issue: Colors not displaying

Performance

Benchmarks

Optimization Tips

Contributing

License

Credits

Links

WebSocket/REST API

POST /urepl/execute

POST /urepl/bootstrap

POST /urepl/srfi/:number

GET /health

GET /status