🖥️ TUI Integration Plan v0.8

FreeBSD jail-worker integration strategy for replacing Claude-specific runtime pieces with an open-source TUI engine

1. Current State

Current engine: Claude-backed jail worker execution

• Host side runs through src/jail-runner.ts
• Jail-side worker runs through container/agent-runner/src/index.ts
• Claude-specific behavior is currently embedded in the jail worker

Problems:

• ❌ Claude is coupled at the runtime boundary, not just the UI layer
• ❌ FreeBSD viability for coding-agent is still unproven
• ❌ Installation-time provider selection is premature before runtime proof
• ❌ Feature parity with Claude has not been established yet

2. Goal: Replace Claude at the Jail Worker Boundary

Vision: Clawdie keeps its FreeBSD jail architecture and swaps the engine inside the jail worker first

• ✅ Preserve the existing host/jail protocol
• ✅ Make jail worker engine selection explicit
• ✅ Validate non-interactive execution before TTY work
• ✅ Keep provider choice possible without redesigning the runtime twice
• ✅ Add installation-time UX only after the runtime path works

3. TUI Provider Options

3.1 coding-agent (Recommended) ⭐

Project: github.com/badlogic/pi-mono

Status: Candidate

• Latest release mentioned by prior research: 06.03.2026 (v0.56.3)
• TypeScript-based (matches Clawdie stack)
• Provider-agnostic by design
• FreeBSD support still needs to be proven on the target system

Why recommended:

• Potential fit for the new jail-worker engine slot
• Can support multiple providers behind one CLI
• Open-source replacement path for Claude-specific runtime
• Modular architecture if only worker-mode execution is needed

3.2 Claude Code (Fallback During Migration)

Status: Current default

• Anthropic-specific
• Currently integrated in the live runtime path
• Should remain available until PI TUI parity is good enough

3.3 Codex CLI (Experimental)

Status: Not primary for FreeBSD

• OpenAI-specific
• FreeBSD bug #13802
• Not the recommended path for this migration

4. Provider Support Matrix

Provider	coding-agent	Claude Code	Codex CLI
OpenAI	Likely	❌	✅
Anthropic	Likely	✅	❌
Google	Likely	❌	❌
FreeBSD support	Untested	✅	⚠️ Bug
Non-interactive worker mode	Untested	✅	Untested
Jail compatibility	Untested	✅	Untested

5. Runtime Validation Flow

5.1 Step 1: Validate on the FreeBSD Host

# Build or install coding-agent on the host first
# Confirm:
# - binary exists
# - --version works
# - non-interactive stdin/stdout mode works
# - no TTY is required

5.2 Step 2: Validate Inside the Jail

# Repeat the same checks inside the jail
# The critical question is whether coding-agent works in the same
# non-interactive shape as the jail worker:
# - stdin prompt in
# - stdout result out
# - stderr errors
# - no inherited TTY

5.3 Step 3: Wire Engine Selection

AGENT_ENGINE=pi-tui
PI_TUI_BIN=coding-agent
PI_TUI_MODEL=your-model-here

# Keep Claude available as fallback during migration
# AGENT_ENGINE=claude remains the safe default

5.4 Step 4: Add Provider UX Later

Future setup UX:

1. Offer engine selection only after coding-agent is proven viable
2. Then add provider and model selection on top of the engine switch
3. Keep host and jail configuration consistent

6. ZFS Jail Setup (Native FreeBSD Isolation)

6.1 Create ZFS Datasets

zfs create -o mountpoint=/jails zroot/jails
zfs create -o mountpoint=/jails/clawdie-cp zroot/jails/clawdie-cp
zfs create -o mountpoint=/jails/clawdie-cp-data zroot/jails/clawdie-cp-data

6.2 Start and Enter Jail

service jail start clawdie-cp
jls
jexec clawdie-cp /bin/csh

7. Architecture

7.1 Runtime Boundary

Clawdie AI Stack:
├── Host Runner
│   └── src/jail-runner.ts
│
├── Jail Worker
│   └── container/agent-runner/src/index.ts
│       ├── ClaudeSdkEngine
│       └── PiTuiEngine
│
└── Runtime Isolation
    └── FreeBSD jails

Key rule:
- preserve host/jail protocol
- swap engine inside the jail worker
- add provider UX only after the worker path is stable

7.2 Engine Abstraction

interface AgentEngine {
  name: string;
  runTurn(input: AgentTurnInput): Promise<AgentTurnResult>;
}

class ClaudeSdkEngine implements AgentEngine { ... }
class PiTuiEngine implements AgentEngine { ... }

8. Benefits

8.1 Runtime Stability

• ✅ Keeps the FreeBSD jail model intact
• ✅ Avoids rewriting the host runner for each provider change
• ✅ Reduces migration risk by preserving existing protocol shape

8.2 Provider Flexibility

• ✅ Makes provider choice possible behind a stable engine slot
• ✅ Allows gradual expansion beyond Anthropic
• ✅ Keeps Claude available as fallback during migration

8.3 Operational Clarity

• ✅ Forces FreeBSD and jail viability to be proven first
• ✅ Separates runtime blockers from setup UX work
• ✅ Makes feature gaps versus Claude explicit

8.4 Future-Proof

• ✅ Engine slot can host future open-source replacements
• ✅ Provider UX can be layered on later
• ✅ Keeps implementation grounded in the real runtime model

9. Implementation Timeline

Week 1: FreeBSD Viability

• Install or build coding-agent on the FreeBSD host
• Verify non-interactive stdin/stdout behavior
• Repeat the same checks inside the jail
• Document blockers before broader integration work

Week 2: Jail Worker Integration

• Use the engine abstraction inside the jail worker
• Keep Claude engine as fallback
• Pass engine selection through the host runner
• Test a single jailed turn with PI TUI

Week 3: Feature Gap Review

• Compare PI TUI behavior with current Claude features
• Check session persistence and resume semantics
• Check tool execution and MCP expectations
• Decide which gaps need shims or temporary limits

Week 4: Setup UX and Documentation

• Add engine selection to setup if runtime validation passed
• Add provider and model selection on top of that
• Document FreeBSD and jail deployment requirements
• Release after runtime path is proven, not before

10. Current Status

Component	Status	Notes
Host/jail engine switch	Started	Engine abstraction exists, PI TUI parity not proven
coding-agent on FreeBSD host	Untested	Must prove build and worker-mode execution first
coding-agent inside jail	Untested	Critical deployment gate
Session parity with Claude	Incomplete	Resume and continuation behavior still need work
ZFS jail support	Ready	Native FreeBSD isolation

11. Next Steps

1. ✅ Choose candidate engine: coding-agent
2. ⏳ Prove coding-agent builds and runs on FreeBSD host
3. ⏳ Prove coding-agent works inside the jail without a TTY
4. ⏳ Run one jailed Clawdie turn with AGENT_ENGINE=pi-tui
5. ⏳ Review feature gaps versus Claude
6. ⏳ Add setup UX only if runtime testing succeeds
7. ⏳ Release after the live runtime path is stable

12. Testing Strategies

12.1 Option A: Build from Source

cd ~
git clone https://github.com/badlogic/pi-mono.git
cd pi-mono
npm install
npm run build
node packages/coding-agent/dist/index.js --version
printf 'Say hello in one sentence.\n' | node packages/coding-agent/dist/index.js --non-interactive --stdin

12.2 Option B: NPM Install

npm install -g @mariozechner/coding-agent
coding-agent --version
printf 'Say hello in one sentence.\n' | coding-agent --non-interactive --stdin

12.3 Option C: Jail Isolation

jexec clawdie-cp /bin/csh
pkg install node24 npm git
# Build or install coding-agent in the jail
# Then repeat the same non-interactive stdin/stdout smoke test

12.4 Recommended Testing Flow

1. Stage 1: Build or install on the host
2. Stage 2: Prove non-interactive worker mode on the host
3. Stage 3: Prove the same flow inside the jail
4. Stage 4: Test one real Clawdie jailed turn with AGENT_ENGINE=pi-tui
5. Stage 5: Document findings and gaps

12.5 Testing Checklist

Test	Command	Expected
Build succeeds	npm run build	No errors
Non-interactive host run	printf '... ' | coding-agent --non-interactive --stdin	Exit 0, usable stdout, no TTY needed
Non-interactive jail run	printf '... ' | coding-agent --non-interactive --stdin	Same behavior inside jail
Single jailed Clawdie turn	AGENT_ENGINE=pi-tui	Host/jail protocol still works
Session parity	Run follow-up turn	Resume behavior is defined and predictable