Ralphex port for Pi agent

[vkosilko]

Hi @umputun,

I noticed a thread in radio-t chat, where you confirmed that there is no yet developed solution to use Ralphex with Pi Agent. I have done some high-level research with Claude and would like to get your approval to go ahead with development or maybe not to reinvent the wheel if someone already started similar project.

Please feel free to review the plan, suggested by Claude or to give it a go. Looking forward to your feedback!

PORT_PLAN.md

[umputun]

hi @vkosilko, nobody's working on Pi support, go ahead. Pi is a good fit for the existing wrapper pattern and another provider option is welcome.

before you start writing code, the attached plan needs significant trimming. It's badly over-engineered relative to what's actually needed. The four existing wrappers in scripts/ are the ground truth for the pattern, and they look like this:

wrapper	shell script	extras
gemini-as-claude	117 lines	none
codex-as-claude	105 lines	none
opencode	181 lines	none
copilot-as-claude	~850 lines (complex internally)	none

each one is a single shell script plus a test file plus a short README. Nothing else. No prerequisites checker, no in-process extension, no provider-specific Dockerfile, no SKILL.md modifications, no .pi/-style config tree.

your plan is 944 lines for the same scope. On top of the wrapper script it proposes a 235-line check-prereqs.sh, a TypeScript .pi/extensions/ralphex/index.ts, a .pi/settings.json plus models.json.example, frontmatter changes to all four ralphex SKILL.md files, a docker/pi/ directory with Dockerfile + docker-compose.yml + .env.example, plus glossary tables, validation checklists, definition-of-done, and a maintenance-parity section. None of that exists for the four current providers and none of it should exist for Pi. Cut all of it.

beyond bulk, there are concrete plan errors to fix before you write code:

1. RALPHEX_IS_REVIEW=1 env var doesn't exist. ralphex doesn't set that. Real wrappers detect review mode by scanning the prompt itself for the <<<RALPHEX:REVIEW_DONE>>> marker, see gemini-as-claude.sh:51-56. Use that pattern.

2. SKILL.md frontmatter changes are out of scope. the files in assets/claude/skills/ are Claude Code skills users install for convenience. They have nothing to do with how ralphex orchestrates the underlying agent. Don't touch them.

3. .pi/extensions/ralphex/index.ts isn't needed. none of the existing wrappers ship in-process extensions. The shell wrapper IS the integration. It accepts Claude flags, runs the target CLI, translates output to stream-json, passes signal markers through. That's all.

4. per-provider Docker setup isn't a pattern here. scripts/ralphex-dk/ is the general Docker wrapper. Don't add docker/pi/.

5. check-prereqs.sh isn't a pattern either. existing wrappers expect the user to have the underlying CLI installed and document that in the README. One-line check at most.

6. several items in the plan's "Known Unknowns" table are still genuinely unknown (Pi --mode json event schema, signal marker behavior under JSON output) but the wrapper code in step 3.2 already commits to them. Resolve those by actually running Pi and inspecting output before locking in the wrapper design.

real scope, matching the gemini wrapper:

scripts/pi-as-claude/
├── pi-as-claude.sh       (~150 lines)
├── pi-as-claude_test.sh
└── README.md             (~1-2 KB)

read gemini-as-claude.sh first. If Pi has a plain-text output mode it's your template almost line-for-line. If you have to use --mode json and parse a Pi-specific event schema, the codex wrapper is closer.

once you have the wrapper working end-to-end against one provider (Anthropic via Pi is fine for testing), open a PR. Parallel sub-agents for the review phase are a bonus, not a blocker. Sequential review via the prompt-prepend adapter (same as gemini/opencode) is acceptable.