Persistent Code Terminal

# persistent-code-terminal

A persistent coding terminal for OpenClaw. It creates a tmux session per project:

`<project-name>-code-session`

• This makes terminal-first AI coding (Codex CLI / Claude Code / any CLI tool) reliable and mobile/SSH friendly:
• detach/reattach without losing output
• keep shell state across turns
• keep long-running tasks alive (dev server, watch mode, etc.)

OpenClaw natural-language routing

When user intent is "use natural language to drive Codex CLI in this repo", route through this skill first.

• Intelligent auto-trigger:
• Routing toggle: `openclaw.config.dev.autoCodeRouting` (default `false`).
• If enabled, route coding workflow messages via:
• - `{baseDir}/bin/persistent-code-terminal-route.sh "<user message>"`
• The route script applies:
• - intent detection (code change / fix / test / build / commit / push / codex phrases)
• - safety filtering (must be git repo + action verbs; bypass on `不要执行，只分析`)
• - execution chain:
• - `persistent-code-terminal-auto.sh --max-retries 3 --instruction "<message>"`
• - `persistent-code-terminal-summary.sh --lines 120`
• - fallback for missing deps (`tmux`/`codex`) with doctor guidance.

• Multi-project routing:
• One message can include multiple project tasks split by newline / `；` / `;`
• Supported patterns:
• - `给 <project> 项目 <instruction>`
• - `给<project>项目：<instruction>`
• - `为 <project> 修复/增加/修改 ...`
• - `<project> 项目 ...；<project> 项目 ...`
• Execution is serial per project:
• - `start.sh --project <project>`
• - `auto.sh --max-retries 3 --instruction "<instruction>"`
• - `summary.sh --lines 120 --json`
• Invalid/unknown project tasks are reported as failed without blocking other tasks.

• Trigger shortcuts (recommended):
• If user message starts with `codex `, treat the remaining text as instruction.
• Execute:
• - `{baseDir}/bin/persistent-code-terminal-codex-exec.sh "<remaining text>"`
• Then report with:
• - `{baseDir}/bin/persistent-code-terminal-status.sh`
• - `{baseDir}/bin/persistent-code-terminal-summary.sh --lines 120`

• Preferred execution pattern in chat-driven runs:
• `start.sh` (or implicit auto-create from `send.sh`)
• `codex-exec.sh "<instruction>"` for Codex-driven work
• `status.sh` / `summary.sh` for concise progress reporting

If user says "检查项目/继续会话/跑测试并总结", use this skill scripts instead of asking user to type long shell commands.

Core model (must follow)

start → send → read → decide

• 1) Start/ensure session:
• `{baseDir}/bin/persistent-code-terminal-start.sh`

• 2) Send ONE command:
• `{baseDir}/bin/persistent-code-terminal-send.sh "<command>"`
• - Appends a pane sentinel on completion: `__PCT_EXIT_CODE__N`
• - Supports: `--timeout <seconds>`, `--dry-run`, `--phase <name>`

• 3) Read output:
• `{baseDir}/bin/persistent-code-terminal-read.sh`
• - Parses the latest sentinel and updates `.pct-state.json`

• 4) Check state quickly (optional):
• `{baseDir}/bin/persistent-code-terminal-status.sh`
• `{baseDir}/bin/persistent-code-terminal-summary.sh --lines 120`
• `{baseDir}/bin/persistent-code-terminal-doctor.sh`
• `{baseDir}/bin/persistent-code-terminal-list.sh` (list `*-code-session`)
• `{baseDir}/bin/persistent-code-terminal-switch.sh --project <name>`

• State file:
• `.pct-state.json` (current project directory)
• Fields: `projectDir`, `session`, `lastCommand`, `lastExitCode`, `phase`, `updatedAt`

• Structured output:
• `{baseDir}/bin/persistent-code-terminal-read.sh --json`
• `{baseDir}/bin/persistent-code-terminal-summary.sh --json`
• `{baseDir}/bin/persistent-code-terminal-auto.sh --json`

Codex-first workflow (one-shot)

If Codex CLI is installed as `codex`, prefer:

• `{baseDir}/bin/persistent-code-terminal-codex-exec.sh "<instruction>"`
• Default behavior uses:
• - `codex exec --full-auto --sandbox workspace-write --cd <current-dir> "<instruction>"`
• You can pass additional flags before the instruction:
• - `{baseDir}/bin/persistent-code-terminal-codex-exec.sh --json -o /tmp/codex.json "<instruction>"`
• Set `PCT_CODEX_NO_DEFAULT_FLAGS=1` to disable default flags.

• Example:
• `{baseDir}/bin/persistent-code-terminal-codex-exec.sh "Implement feature X. Ensure build and tests pass. Commit and push to current branch. Do NOT force push."`

Safety

• Never `git push --force` unless user explicitly requests.
• Keep secrets out of terminal output.
• Prefer feature branches; avoid direct pushes to main/master unless explicitly requested.
• For network/privileged actions (for example `git push`), follow active Codex approval/sandbox policy.