Skip to content

Commit 45e9df1

Browse files
author
Alex
committed
feat(examples): add opencode-plugin-rlm with OpenCode plugin and Claude Code hook
Adds RLM integration for OpenCode and Claude Code: - terraphim-rlm.js: OpenCode plugin for RLM tool exposure - terraphim-rlm-hook.sh: Claude Code hook for RLM commands - install.sh: Installation script for both platforms - package.json: NPM package manifest - README.md: Documentation Refs #rlm
1 parent c836433 commit 45e9df1

5 files changed

Lines changed: 598 additions & 0 deletions

File tree

‎examples/opencode-plugin-rlm/README.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
# Terraphim RLM OpenCode Plugin
2+
3+
OpenCode plugin for terraphim_rlm - Recursive Language Model orchestration with secure code execution.
4+
5+
## Features
6+
7+
- **Isolated Code Execution**: Run Python code in Firecracker VMs, Docker containers, or locally
8+
- **Recursive LLM Loops**: Query → Execute → Feedback → Repeat with LLM review
9+
- **Session Management**: Create sessions with snapshots and rollback
10+
- **Knowledge Graph Validation**: Validate commands against KG before execution
11+
- **Budget Tracking**: Token, time, and recursion depth limits
12+
13+
## Requirements
14+
15+
- OpenCode CLI installed
16+
- terraphim_mcp_server with RLM tools, OR
17+
- terraphim_rlm crate built from source
18+
19+
## Installation
20+
21+
### OpenCode Plugin
22+
23+
```bash
24+
# Option 1: Copy manually
25+
cp terraphim-rlm.js ~/.config/opencode/plugin/
26+
27+
# Option 2: Use install script
28+
./install.sh --opencode
29+
```
30+
31+
### Claude Code Hook
32+
33+
```bash
34+
# Install hook
35+
./install.sh --claude
36+
37+
# Or manually
38+
cp terraphim-rlm-hook.sh ~/.claude/hooks/
39+
chmod +x ~/.claude/hooks/terraphim-rlm-hook.sh
40+
```
41+
42+
## Usage
43+
44+
### RLM Commands
45+
46+
| Command | Description |
47+
|---------|-------------|
48+
| `rlm_query "prompt"` | Execute full recursive query loop |
49+
| `rlm_code "python code"` | Execute Python in isolated VM |
50+
| `rlm_bash "command"` | Execute bash command in VM |
51+
| `rlm_status` | Get session status |
52+
53+
### Examples
54+
55+
```bash
56+
# Query with recursive LLM feedback
57+
> rlm_query "Calculate the first 10 fibonacci numbers"
58+
59+
# Execute Python
60+
> rlm_code "print('Hello from RLM!'); import math; print(math.pi)"
61+
62+
# Run bash
63+
> rlm_bash "ls -la /workspace"
64+
```
65+
66+
## Architecture
67+
68+
```
69+
TerraphimRlm (public API)
70+
├── SessionManager (VM affinity, context, snapshots, extensions)
71+
├── QueryLoop (command parsing, execution, result handling)
72+
├── BudgetTracker (token counting, time tracking, depth limits)
73+
└── KnowledgeGraphValidator (term matching, retry, strictness)
74+
75+
ExecutionEnvironment trait (pluggable)
76+
├── FirecrackerExecutor (full VM isolation, requires KVM)
77+
├── DockerExecutor (container isolation with gVisor)
78+
├── E2bExecutor (cloud-hosted Firecracker)
79+
└── LocalExecutor (local process execution, no isolation)
80+
```
81+
82+
## Configuration
83+
84+
Set environment variables to customize:
85+
86+
| Variable | Default | Description |
87+
|----------|---------|-------------|
88+
| `TERRAPHIM_AGENT` | `~/.cargo/bin/terraphim-agent` | Path to terraphim-agent |
89+
| `TERRAPHIM_MCP` | `terraphim_mcp_server` | MCP server command |
90+
| `TERRAPHIM_DEBUG` | `0` | Enable debug logging |
91+
92+
## Backends
93+
94+
By default, RLM tries backends in this order:
95+
1. **Firecracker** - Full VM isolation (requires KVM on Linux)
96+
2. **E2B** - Cloud-hosted Firecracker (requires API key)
97+
3. **Docker** - Container isolation (requires Docker daemon)
98+
4. **Local** - Direct execution on host (no isolation)
99+
100+
## License
101+
102+
MIT

‎examples/opencode-plugin-rlm/install.sh‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
#!/bin/bash
2+
# @file install.sh
3+
# Install script for terraphim-rlm OpenCode plugin and Claude Code hook.
4+
#
5+
# Usage:
6+
# ./install.sh # Interactive install
7+
# ./install.sh --opencode # OpenCode only
8+
# ./install.sh --claude # Claude Code only
9+
10+
set -e
11+
12+
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
13+
OPENCODE_PLUGIN_DIR="${HOME}/.config/opencode/plugin"
14+
OPENCODE_PLUGINS_DIR="${HOME}/.config/opencode/plugins"
15+
CLAUDE_HOOKS_DIR="${HOME}/.claude/hooks"
16+
17+
usage() {
18+
echo "Usage: $0 [OPTIONS]"
19+
echo ""
20+
echo "Options:"
21+
echo " --opencode Install OpenCode plugin only"
22+
echo " --claude Install Claude Code hook only"
23+
echo " --both Install both (default)"
24+
echo " --uninstall Uninstall"
25+
echo " --help Show this help"
26+
exit 0
27+
}
28+
29+
install_opencode() {
30+
echo "Installing OpenCode plugin..."
31+
32+
if [ -d "$OPENCODE_PLUGIN_DIR" ]; then
33+
cp "${SCRIPT_DIR}/terraphim-rlm.js" "$OPENCODE_PLUGIN_DIR/"
34+
echo " -> Copied to $OPENCODE_PLUGIN_DIR/terraphim-rlm.js"
35+
fi
36+
37+
if [ -d "$OPENCODE_PLUGINS_DIR" ]; then
38+
cp "${SCRIPT_DIR}/terraphim-rlm.js" "$OPENCODE_PLUGINS_DIR/"
39+
echo " -> Copied to $OPENCODE_PLUGINS_DIR/terraphim-rlm.js"
40+
fi
41+
42+
if [ ! -d "$OPENCODE_PLUGIN_DIR" ] && [ ! -d "$OPENCODE_PLUGINS_DIR" ]; then
43+
echo "ERROR: OpenCode config directory not found"
44+
echo " Expected: $OPENCODE_PLUGIN_DIR or $OPENCODE_PLUGINS_DIR"
45+
return 1
46+
fi
47+
48+
echo "OpenCode plugin installed!"
49+
}
50+
51+
install_claude() {
52+
echo "Installing Claude Code hook..."
53+
54+
mkdir -p "$CLAUDE_HOOKS_DIR"
55+
56+
cp "${SCRIPT_DIR}/terraphim-rlm-hook.sh" "$CLAUDE_HOOKS_DIR/"
57+
chmod +x "$CLAUDE_HOOKS_DIR/terraphim-rlm-hook.sh"
58+
59+
echo " -> Copied to $CLAUDE_HOOKS_DIR/terraphim-rlm-hook.sh"
60+
61+
if [ -f "${HOME}/.claude/settings.local.json" ]; then
62+
echo " -> Claude Code settings found at ${HOME}/.claude/settings.local.json"
63+
echo " -> Add the hook manually in settings.local.json:"
64+
echo ""
65+
echo ' {
66+
"hooks": {
67+
"PreToolUse": [{
68+
"matcher": "Bash",
69+
"hooks": [{
70+
"type": "command",
71+
"command": "~/.claude/hooks/terraphim-rlm-hook.sh"
72+
}]
73+
}]
74+
}
75+
}'
76+
else
77+
cat > "${HOME}/.claude/settings.local.json" << 'EOF'
78+
{
79+
"hooks": {
80+
"PreToolUse": [{
81+
"matcher": "Bash",
82+
"hooks": [{
83+
"type": "command",
84+
"command": "~/.claude/hooks/terraphim-rlm-hook.sh"
85+
}]
86+
}]
87+
}
88+
}
89+
EOF
90+
echo " -> Created ${HOME}/.claude/settings.local.json"
91+
fi
92+
93+
echo "Claude Code hook installed!"
94+
}
95+
96+
uninstall() {
97+
echo "Uninstalling..."
98+
99+
rm -f "$OPENCODE_PLUGIN_DIR/terraphim-rlm.js" 2>/dev/null || true
100+
rm -f "$OPENCODE_PLUGINS_DIR/terraphim-rlm.js" 2>/dev/null || true
101+
rm -f "$CLAUDE_HOOKS_DIR/terraphim-rlm-hook.sh" 2>/dev/null || true
102+
103+
echo "Uninstalled!"
104+
}
105+
106+
TARGET="both"
107+
108+
while [[ $# -gt 0 ]]; do
109+
case "$1" in
110+
--opencode) TARGET="opencode"; shift ;;
111+
--claude) TARGET="claude"; shift ;;
112+
--both) TARGET="both"; shift ;;
113+
--uninstall) TARGET="uninstall"; shift ;;
114+
--help) usage ;;
115+
*) echo "Unknown option: $1"; usage ;;
116+
esac
117+
done
118+
119+
case "$TARGET" in
120+
opencode) install_opencode ;;
121+
claude) install_claude ;;
122+
both)
123+
install_opencode
124+
echo ""
125+
install_claude
126+
;;
127+
uninstall) uninstall ;;
128+
esac
129+
130+
echo ""
131+
echo "Done!"

‎examples/opencode-plugin-rlm/package.json‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
{
2+
"name": "terraphim-rlm-opencode-plugin",
3+
"version": "1.0.0",
4+
"description": "OpenCode plugin for terraphim_rlm - Recursive Language Model orchestration",
5+
"main": "terraphim-rlm.js",
6+
"scripts": {
7+
"install": "cp terraphim-rlm.js ~/.config/opencode/plugin/",
8+
"install:global": "cp terraphim-rlm.js ~/.config/opencode/plugins/"
9+
},
10+
"keywords": [
11+
"terraphim",
12+
"rlm",
13+
"opencode",
14+
"code-execution",
15+
"llm"
16+
],
17+
"author": "Terraphim",
18+
"license": "MIT",
19+
"engines": {
20+
"node": ">=16.0.0"
21+
}
22+
}

0 commit comments

Comments
 (0)