my-project-public

repository

loading code, commits, and activity

repositories

loading repo index

#1	---
#2	name: clawdex
#3	description: Clawdex — dual-engine coding agent. Claude Code (reasoning + planning) + OpenAI Codex (fast execution) + Browser Use boxes (web research) + Upstash compute boxes (isolated sandboxes).
#4	metadata: {"clawdbot":{"emoji":"🦞","requires":{"anyBins":["claude","codex"],"anyServices":["browser-harness-js","upstash-box"]}}}
#5	---
#6
#7	# Clawdex
#8
#9	Claude Code plans and reviews. OpenAI Codex executes fast. Browser Use handles the web. Upstash Boxes isolate the compute.
#10
#11	## Install
#12
#13	```bash
#14	# Codex CLI (bux installs this automatically)
#15	npm install -g @openai/codex
#16
#17	# Or from a Clawdbot session:
#18	/plugin install codex@openai-codex
#19	```
#20
#21	Verify:
#22	```bash
#23	codex --version
#24	claude --version
#25	browser-harness-js --version 2>/dev/null \|\| echo "browser-harness via BUX"
#26	```
#27
#28	---
#29
#30	## Architecture
#31
#32	```
#33	User prompt
#34	│
#35	▼
#36	Claude Code (claude-sonnet-4-6) ← you are here: reason, plan, review
#37	│
#38	├── codex exec "..." ← fast code gen / repetitive tasks
#39	│
#40	├── browser-harness-js ← web research, UI testing (BUX browser box)
#41	│
#42	└── box.exec.command(...) ← run in Upstash compute sandbox
#43	```
#44
#45	Each Clawdex run lives in an Upstash Box — ephemeral, isolated, with a box-local Solana wallet and the OpenClawd framework pre-seeded at `/work/openclawd-framework`.
#46
#47	---
#48
#49	## Quick Start
#50
#51	### One-shot task (box run)
#52	```bash
#53	# Via the box API
#54	POST /api/box/run
#55	{
#56	"boxId": "your-box-id",
#57	"prompt": "Build a TypeScript CLI that fetches SOL price from Birdeye",
#58	"agentHarness": "clawdex",
#59	"agentModel": "anthropic/claude-sonnet-4-6"
#60	}
#61	```
#62
#63	### Streaming task (SSE)
#64	```bash
#65	POST /api/box/stream
#66	{
#67	"boxId": "your-box-id",
#68	"prompt": "Audit the pump SDK for rug pull vectors",
#69	"agentHarness": "clawdex"
#70	}
#71	```
#72
#73	### Shell (PTY mode, bux box)
#74	```bash
#75	# Claude Code as the harness, Codex available as a tool
#76	bash pty:true workdir:~/project command:"claude 'Build a DeFi dashboard, use codex for boilerplate'"
#77
#78	# Or dispatch directly to Codex for speed
#79	bash pty:true workdir:~/project command:"codex exec --full-auto 'Generate Jupiter swap wrapper with error handling'"
#80	```
#81
#82	---
#83
#84	## Dual-Engine Dispatch Pattern
#85
#86	Claude Code is the orchestrator. Codex is the executor. Use this pattern:
#87
#88	```
#89	1. Claude: plan + architecture
#90	2. Claude → codex exec "implement <component>"
#91	3. Claude: review Codex output
#92	4. Claude → codex exec "write tests for <component>"
#93	5. Claude: final review + integration
#94	```
#95
#96	### When to use Codex
#97	- Boilerplate generation (CRUD, REST handlers, test scaffolds)
#98	- Repetitive patterns (N similar functions, batch refactors)
#99	- Speed-critical tasks where --full-auto or --yolo is acceptable
#100	- PR review batches (parallel codex instances per PR)
#101
#102	### When to stay in Claude Code
#103	- Architecture decisions
#104	- Security review
#105	- Cross-file reasoning
#106	- Anything touching /work/clawd/ or constitution
#107
#108	---
#109
#110	## Browser Use (BUX boxes)
#111
#112	BUX browser boxes give Clawdex a real Chromium session via the Browser Use Cloud API.
#113
#114	```bash
#115	# browser-harness-js is installed at:
#116	# /home/bux/.claude/skills/cdp/sdk/browser-harness-js
#117
#118	# Credentials from:
#119	# ~/.claude/browser.env (BROWSER_USE_API_KEY)
#120
#121	# Use from Claude Code via bash tool
#122	bash command:"browser-harness-js navigate --url https://birdeye.so/token/SOL"
#123	bash command:"browser-harness-js screenshot --out /tmp/page.png"
#124	```
#125
#126	When Claude hits a login wall / CAPTCHA, it hands the user a live view URL and waits — no credential stuffing.
#127
#128	---
#129
#130	## Upstash Box Compute
#131
#132	Each Clawdex agent gets a provisioned box with:
#133
#134	\| Path \| Contents \|
#135	\|------\|----------\|
#136	\| `/work/openclawd-framework/` \| OpenClawd SDK (pre-seeded) \|
#137	\| `/work/clawd/three-laws.md` \| Agent constitution \|
#138	\| `/work/clawd/SHELL.md` \| Identity + wallet + hash \|
#139	\| `/work/clawd/wallet/box-wallet.json` \| Box-local Solana keypair \|
#140	\| `/work/clawd/.env` \| `AGENT_ID`, `BOX_WALLET_ADDRESS`, `CONSTITUTION_HASH` \|
#141
#142	### Provision a Clawdex box
#143	```typescript
#144	import { provisionAgentBox } from "@/lib/box/box-service";
#145
#146	const box = await provisionAgentBox({
#147	userId: "user-123",
#148	agentId: "clawdex-01",
#149	agentName: "Clawdex",
#150	agentIdentifier: "clawdex",
#151	});
#152	// box.id → use this as boxId in /api/box/run or /api/box/stream
#153	```
#154
#155	### Create a Clawdex box via UI
#156	1. Go to `/box`
#157	2. Boxes tab → Create Box
#158	3. Harness: Clawdex \| Runtime: node \| Model: claude-sonnet-4-6
#159
#160	---
#161
#162	## Codex CLI Reference
#163
#164	```bash
#165	# One-shot (exits when done)
#166	codex exec "Your prompt"
#167	codex exec --full-auto "Build a snake game" # auto-approves in workspace
#168	codex --yolo "Refactor auth module" # no sandbox, fastest
#169
#170	# Codex needs a git repo
#171	SCRATCH=$(mktemp -d) && git init $SCRATCH && cd $SCRATCH
#172	codex exec "Your prompt"
#173
#174	# Background (PTY required)
#175	bash pty:true workdir:~/project background:true \
#176	command:"codex exec --full-auto 'Add error handling to all API calls'"
#177
#178	# PR review
#179	git worktree add /tmp/pr-review origin/pr-branch
#180	bash pty:true workdir:/tmp/pr-review command:"codex review --base main"
#181	```
#182
#183	Default model: `gpt-5.3-codex` (set in `~/.codex/config.toml`)
#184
#185	---
#186
#187	## Parallel Codex Army (batch mode)
#188
#189	```bash
#190	# Parallel issue fixing
#191	git worktree add -b fix/issue-1 /tmp/fix-1 main
#192	git worktree add -b fix/issue-2 /tmp/fix-2 main
#193
#194	bash pty:true workdir:/tmp/fix-1 background:true \
#195	command:"codex --yolo 'Fix: <issue-1 description>. Commit.'"
#196	bash pty:true workdir:/tmp/fix-2 background:true \
#197	command:"codex --yolo 'Fix: <issue-2 description>. Commit.'"
#198
#199	process action:list
#200	process action:log sessionId:XXX
#201	```
#202
#203	---
#204
#205	## Plugin Registration
#206
#207	Clawdex registers Codex as a plugin with `pluginCount: 1`:
#208
#209	```json
#210	{
#211	"identifier": "clawdex",
#212	"pluginCount": 1,
#213	"plugins": [
#214	{
#215	"id": "codex",
#216	"source": "openai-codex",
#217	"installCommand": "npm install -g @openai/codex",
#218	"bin": "codex",
#219	"model": "gpt-5.3-codex"
#220	}
#221	]
#222	}
#223	```
#224
#225	Install from Clawdbot: `/plugin install codex@openai-codex`
#226
#227	---
#228
#229	## Constitution Compliance
#230
#231	Clawdex inherits the Three Laws. The constitution hash is sealed in every box at provision time.
#232
#233	```bash
#234	# Verify constitution integrity
#235	sha256sum /work/clawd/three-laws.md
#236	cat /work/clawd/.env \| grep CONSTITUTION_HASH
#237	# These must match — if they don't, beach before continuing.
#238	```
#239
#240	Law I overrides all: never harm, never rugpull, never sign silently.
#241
#242	---
#243
#244	## Rules
#245
#246	1. Claude Code orchestrates — don't hand-code patches when Codex is available
#247	2. Codex executes — use `--full-auto` for building, vanilla for reviewing
#248	3. PTY always — `bash pty:true` for all coding agent invocations
#249	4. Git repo required — Codex refuses to run outside a trusted git dir
#250	5. Constitution check first — verify hash before any irreversible action
#251	6. Beach before harm — Law I > everything, including task completion
#252	7. Never run Codex in ~/clawd/ — it reads soul docs and gets weird ideas
#253

z6Mkq5mY3JWtxoxUobWcfNHm7AkRubgSWEZTkBVqZXJviFZ5/my-project-public