Skip to content

Commit c690773

Browse files
Shashikant86Shashikant86
committed
Add docs for the code mode
1 parent 1f6bc33 commit c690773

6 files changed

Lines changed: 381 additions & 63 deletions

File tree

‎docs/codemode/cloudflare.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# Cloudflare (Remote) CodeMode Path
2+
3+
This guide explains how to use Cloudflare MCP with the current RLM release.
4+
5+
Important for this release:
6+
- Cloudflare MCP works.
7+
- Use `strategy=tool_call` for Cloudflare today.
8+
- Current `strategy=codemode` expects UTCP-style bridge tools (`search_tools`, `call_tool_chain`).
9+
10+
---
11+
12+
## 1) When to choose this path
13+
14+
Use Cloudflare path when you want:
15+
- remote MCP backend
16+
- Cloudflare-managed tools
17+
- a second backend demo alongside UTCP
18+
19+
Use UTCP page if you need native `strategy=codemode` now.
20+
21+
---
22+
23+
## 2) Add MCP config
24+
25+
Create or update `rlm_config.yaml`:
26+
27+
```yaml
28+
mcp_servers:
29+
cloudflare-codemode:
30+
name: cloudflare-codemode
31+
description: "Cloudflare MCP via remote bridge"
32+
enabled: true
33+
auto_connect: false
34+
timeout_seconds: 30
35+
retry_attempts: 3
36+
transport:
37+
type: stdio
38+
command: npx
39+
args:
40+
- "mcp-remote"
41+
- "https://mcp.cloudflare.com/mcp"
42+
```
43+
44+
---
45+
46+
## 3) Connect and inspect tools in TUI
47+
48+
```bash
49+
/connect
50+
/mcp-servers
51+
/mcp-connect cloudflare-codemode
52+
/mcp-tools cloudflare-codemode
53+
```
54+
55+
Authentication note:
56+
- On first connect, Cloudflare remote MCP can require interactive auth.
57+
- If you are not already authenticated, `mcp-remote` may open or prompt for login.
58+
- Complete auth once, then retry `/mcp-connect cloudflare-codemode`.
59+
60+
Look at the tool names from this server.
61+
If they are not `search_tools` and `call_tool_chain`, use `strategy=tool_call`.
62+
63+
---
64+
65+
## 4) First harness run (steps=3)
66+
67+
```bash
68+
/harness run "list available tools and run one safe read-only action, then summarize in 3 bullets" steps=3 mcp=on strategy=tool_call mcp_server=cloudflare-codemode
69+
```
70+
71+
This gives a stable Cloudflare demo without bridge-name mismatch.
72+
73+
---
74+
75+
## 5) Demo commands
76+
77+
```bash
78+
/mcp-servers
79+
/mcp-tools cloudflare-codemode
80+
/harness run "list tools, execute one safe read-only check, and summarize result" steps=3 mcp=on strategy=tool_call mcp_server=cloudflare-codemode
81+
```
82+
83+
---
84+
85+
## 6) Common error and fix
86+
87+
### Error
88+
89+
`Code-mode strategy could not resolve an MCP server exposing call_tool_chain/search_tools`
90+
91+
### Why
92+
93+
Current `strategy=codemode` in this release requires tool names:
94+
- `search_tools`
95+
- `call_tool_chain`
96+
97+
Your Cloudflare server may expose a different contract.
98+
99+
### Fix
100+
101+
Use:
102+
103+
```bash
104+
strategy=tool_call
105+
```
106+
107+
and keep:
108+
109+
```bash
110+
mcp_server=cloudflare-codemode
111+
```
112+
113+
---
114+
115+
## 7) Benchmark example
116+
117+
```bash
118+
/rlm bench preset=generic_smoke mode=harness strategy=tool_call mcp=on mcp_server=cloudflare-codemode limit=1 steps=3
119+
```

‎docs/codemode/index.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,22 @@ Default harness behavior remains `strategy=tool_call`.
1313
- How sandbox responsibility differs between RLM and external MCP bridges.
1414
- What guardrails are enforced before execution.
1515
- How to evaluate and promote CodeMode safely.
16+
- Step-by-step setup for both UTCP and Cloudflare paths.
17+
18+
---
19+
20+
## Implementation choices
21+
22+
Use this table first, then open the matching page in the left navigation.
23+
24+
| Implementation | Recommended strategy today | Required MCP tools | Page |
25+
|---|---|---|---|
26+
| UTCP CodeMode MCP | `codemode` | `search_tools`, `call_tool_chain` | [UTCP (Local)](utcp.md) |
27+
| Cloudflare remote MCP | `tool_call` | provider-specific (often `search`, `execute`) | [Cloudflare (Remote)](cloudflare.md) |
28+
29+
Cloudflare can still be used with RLM today.
30+
The current `codemode` strategy in this release expects the UTCP-style bridge contract.
31+
If that contract is not exposed, use `strategy=tool_call`.
1632

1733
---
1834

@@ -31,6 +47,8 @@ RLM targets the MCP bridge contract, not a single provider runtime.
3147
## Read next
3248

3349
- [Quickstart](quickstart.md)
50+
- [UTCP (Local)](utcp.md)
51+
- [Cloudflare (Remote)](cloudflare.md)
3452
- [Architecture](architecture.md)
3553
- [Guardrails](guardrails.md)
3654
- [Evaluation](evaluation.md)

‎docs/codemode/quickstart.md‎

Lines changed: 30 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,51 +1,60 @@
11
# CodeMode Quickstart
22

3-
Use this guide to run `strategy=codemode` end to end.
3+
Use this page to pick the right path fast.
4+
For full step-by-step setup, use the UTCP and Cloudflare pages in the left navigation.
45

56
---
67

7-
## Prerequisites
8+
## Choose your path
89

9-
- Connected model (`/connect ...`).
10-
- MCP server exposing `search_tools` and `call_tool_chain`.
11-
- Harness MCP enabled (`mcp=on`).
10+
| Path | When to use | Strategy |
11+
|---|---|---|
12+
| UTCP (local bridge) | You want native CodeMode flow in this release | `codemode` |
13+
| Cloudflare (remote MCP) | You want Cloudflare backend now | `tool_call` |
1214

1315
---
1416

15-
## First run
17+
## UTCP fast start
1618

1719
```bash
18-
/mcp-connect codemode
20+
/mcp-connect utcp-codemode
1921
/harness tools mcp=on
20-
/harness run "implement feature and add tests" steps=8 mcp=on strategy=codemode mcp_server=codemode
22+
/harness run "inspect repo and create report.json with actionable fixes" steps=3 mcp=on strategy=codemode mcp_server=utcp-codemode
2123
```
2224

23-
Expected flow:
24-
25+
Expected flow in this release:
2526
1. `search_tools`
26-
2. single generated JS/TS program
27+
2. one generated JS/TS program
2728
3. `call_tool_chain`
2829

2930
---
3031

31-
## Compare against baseline
32+
## Cloudflare fast start
3233

3334
```bash
34-
/rlm bench preset=dynamic_web_filtering mode=harness strategy=tool_call mcp=on mcp_server=codemode
35-
/rlm bench preset=dynamic_web_filtering mode=harness strategy=codemode mcp=on mcp_server=codemode
36-
/rlm bench compare candidate=latest baseline=previous
35+
/mcp-connect cloudflare-codemode
36+
/mcp-tools cloudflare-codemode
37+
/harness run "list available tools and run one safe read-only action, then summarize result" steps=3 mcp=on strategy=tool_call mcp_server=cloudflare-codemode
3738
```
3839

39-
For CI output:
40+
If you run Cloudflare with `strategy=codemode` and see:
41+
`could not resolve an MCP server exposing call_tool_chain/search_tools`
42+
that means this server is exposing a different tool contract.
43+
Use `strategy=tool_call` for Cloudflare in this release.
44+
45+
---
46+
47+
## Benchmark compare example
4048

4149
```bash
42-
/rlm bench validate candidate=latest baseline=previous --json
50+
/rlm bench preset=generic_smoke mode=harness strategy=codemode mcp=on mcp_server=utcp-codemode limit=1 steps=3
51+
/rlm bench preset=generic_smoke mode=harness strategy=tool_call mcp=on mcp_server=cloudflare-codemode limit=1 steps=3
52+
/rlm bench compare candidate=latest baseline=previous
4353
```
4454

4555
---
4656

47-
## Notes
57+
## Next pages
4858

49-
- `strategy=codemode` auto-enables MCP if omitted.
50-
- `tools=...` allowlist is ignored in CodeMode strategy.
51-
- If multiple MCP servers expose `call_tool_chain`, pass `mcp_server=<name>`.
59+
- [UTCP (Local)](utcp.md)
60+
- [Cloudflare (Remote)](cloudflare.md)

‎docs/codemode/utcp.md‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
# UTCP (Local) CodeMode
2+
3+
This guide is for junior developers who want a reliable local CodeMode setup.
4+
5+
Use this path when you want:
6+
- `strategy=codemode`
7+
- deterministic local behavior
8+
- the full bridge contract expected by this release (`search_tools` and `call_tool_chain`)
9+
10+
---
11+
12+
## 1) Prerequisites
13+
14+
- You are inside your project directory.
15+
- `rlm-code` is installed.
16+
- Node.js and `npx` are available.
17+
- A model can be connected in TUI (`/connect`).
18+
19+
Quick checks from shell:
20+
21+
```bash
22+
node -v
23+
npx -v
24+
rlm-code --version
25+
```
26+
27+
---
28+
29+
## 2) Add MCP config
30+
31+
Create or update `rlm_config.yaml` in your project root:
32+
33+
```yaml
34+
mcp_servers:
35+
utcp-codemode:
36+
name: utcp-codemode
37+
description: "Local CodeMode MCP bridge"
38+
enabled: true
39+
auto_connect: false
40+
timeout_seconds: 30
41+
retry_attempts: 3
42+
transport:
43+
type: stdio
44+
command: npx
45+
args:
46+
- "@utcp/code-mode-mcp"
47+
```
48+
49+
---
50+
51+
## 3) Connect and verify in TUI
52+
53+
Start TUI:
54+
55+
```bash
56+
rlm-code
57+
```
58+
59+
Run:
60+
61+
```bash
62+
/connect
63+
/mcp-servers
64+
/mcp-connect utcp-codemode
65+
/mcp-tools utcp-codemode
66+
```
67+
68+
You should see tools including:
69+
- `search_tools`
70+
- `call_tool_chain`
71+
72+
If these are missing, `strategy=codemode` will not run.
73+
74+
---
75+
76+
## 4) First harness run (steps=3)
77+
78+
```bash
79+
/harness run "inspect this repo and create report.json with TODO/FIXME counts and top 5 improvements" steps=3 mcp=on strategy=codemode mcp_server=utcp-codemode
80+
```
81+
82+
Expected sequence:
83+
1. Harness calls `mcp:utcp-codemode:search_tools`
84+
2. Model generates one JS/TS code program
85+
3. Harness calls `mcp:utcp-codemode:call_tool_chain`
86+
87+
---
88+
89+
## 5) Demo commands
90+
91+
Use this exact flow for a short recording:
92+
93+
```bash
94+
/mcp-servers
95+
/mcp-tools utcp-codemode
96+
/harness doctor
97+
/harness run "analyze this repo, find TODO/FIXME, and create report.json" steps=3 mcp=on strategy=codemode mcp_server=utcp-codemode
98+
```
99+
100+
---
101+
102+
## 6) Troubleshooting
103+
104+
### Error: permission denied during `/mcp-connect`
105+
106+
Cause: npm cache permissions.
107+
108+
Fix from shell:
109+
110+
```bash
111+
sudo chown -R "$USER" ~/.npm
112+
npm cache verify
113+
```
114+
115+
Then retry `/mcp-connect utcp-codemode`.
116+
117+
### Error: `could not resolve an MCP server exposing call_tool_chain/search_tools`
118+
119+
Cause: wrong server selected or missing tools.
120+
121+
Fix:
122+
1. Run `/mcp-tools utcp-codemode`
123+
2. Confirm both required tools exist
124+
3. Re-run with explicit `mcp_server=utcp-codemode`
125+
126+
### Harness ends partial at 2 steps
127+
128+
Cause: model did not produce a final answer in time.
129+
130+
Fix:
131+
1. Increase `steps=4` or `steps=5`
132+
2. Narrow the task text so the generated chain is shorter
133+
134+
---
135+
136+
## 7) Benchmark example
137+
138+
```bash
139+
/rlm bench preset=generic_smoke mode=harness strategy=codemode mcp=on mcp_server=utcp-codemode limit=1 steps=3
140+
```
141+

0 commit comments

Comments
 (0)