Persistent Code Terminal

Persistent per-project coding terminal (tmux). Run Codex CLI (codex exec) inside a stable session; mobile/SSH friendly.

Security Scan

The skill is internally consistent with its stated purpose (a tmux-backed persistent per-project terminal that can run Codex CLI); it requires only tmux, installs tmux via brew/apt, and the scripts operate on local repository state — there are no unexplained credentials or hidden network endpoints in the package.

Purpose & Capability

Name/description (persistent tmux terminal for Codex-driven workflows) align with required binaries (tmux) and the included scripts (start/send/read/summary/auto/route/codex-exec). The ability to run 'codex exec' (if installed) is expected for this skill's purpose.

Instruction Scope

Runtime instructions and scripts operate on the local filesystem, tmux sessions, and git repos in the current working directory (creating .pct-state.json and .pct-routing.log). They can run arbitrary shell commands via tmux and (if present) invoke the Codex CLI which may make code changes and network operations (e.g., git push). This is consistent with the purpose but is the primary risk surface (automated changes/pushes).

Install Mechanism

Install spec is limited to installing tmux (brew formula; SKILL.md also documents apt). No downloads from arbitrary URLs or extract steps. Minor metadata inconsistency: registry install list shows brew only while SKILL.md metadata also references an apt entry — both are reasonable package sources for tmux.

Credentials

The skill declares no required environment variables or credentials (correct for a local tooling skill). Scripts do optionally read/ honor an environment override OPENCLAW_CONFIG_DEV_AUTO_CODE_ROUTING (not declared in the registry metadata) and standard vars like HOME — this is reasonable but worth noting. The Codex CLI (if present) is an external dependency that may require network access/credentials outside this skill (not requested by the skill itself).

Persistence & Privilege

always:false (no forced inclusion). The skill writes local state files (.pct-state.json, .pct-routing.log) in the project, creates tmux sessions, and can be invoked autonomously by the agent (disable-model-invocation:false) which is platform-default. Enabling auto-routing or invoking codex exec gives the agent the ability to run commands that may change and push code — this is expected functionality, not an unexplained privilege escalation.

Assessment

This skill appears to be what it claims: a set of shell scripts that create per-project tmux sessions and optionally run the Codex CLI inside them. Before installing, consider the following: - Autonomy risk: if you enable OpenClaw auto-routing (openclaw.config.dev.autoCodeRouting = true) or allow the agent to invoke skills autonomously, the agent may run the Codex CLI which can perform edits, run builds/tests, and push to remotes. Auto-routing is disabled by default, but enable it only if you trust the agent and the Codex CLI behavior. - Review the scripts: they write .pct-state.json and .pct-routing.log into your repo and use tmux capture/ send-keys to run arbitrary shell commands — inspect the code if you have sensitive data in the repo or require stricter audit controls. - Codex CLI network access: the skill does not request credentials, but the Codex CLI (external tool) may perform network calls. Make sure you understand your Codex CLI's sandbox/permission model and what remote auth (SSH keys, Git credentials) it can use. - Scope of install: install the skill at project scope (repo/skills/...) rather than globally, unless you want it available everywhere. That reduces accidental cross-repo execution. - Small metadata notes: SKILL.md reads OPENCLAW_CONFIG_DEV_AUTO_CODE_ROUTING as an env override (not declared in registry metadata) and lists apt in metadata while the registry install spec lists brew — this is minor but worth being aware of. If you plan to use automated/Codex-driven pushes, test in a safe repository first, run the included doctor script, and consider setting PCT_CODEX_NO_DEFAULT_FLAGS=1 or keeping autoCodeRouting disabled until you are confident in the workflow.

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.