A persistent tmux-based session manager designed to provide AI agents with stable, long-running terminal environments for complex coding tasks.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install persistent-code-terminal
2. Manual Installation
Copy the skill folder to one of these locations
~/.openclaw/skills/ <project>/skills/ Priority: Workspace > Local > Bundled
3. Prompt Installation
Copy this prompt to OpenClaw to install it automatically.
Help me install persistent-code-terminal using Clawhub. If Clawhub is not installed, install it first (npm i -g clawhub).
Prefer to download?
Get the raw skill files in a ZIP archive.
What is Persistent Code Terminal?
Persistent Code Terminal is a robust utility designed to bridge the gap between ephemeral AI chat sessions and stable shell environments. By utilizing tmux to create project-specific sessions, this tool ensures that coding tasks, development servers, and build processes remain active even if the connection is interrupted. It is a vital asset within the ecosystem of Openclaw Skills, particularly for developers who rely on mobile devices or remote SSH connections to manage their AI-driven workflows.
The skill allows for sophisticated session management where shell state is preserved across multiple turns. It integrates seamlessly with Codex CLI and Claude Code, providing a reliable infrastructure for autonomous coding. By maintaining a per-project session named project-name-code-session, it allows developers to detach and reattach to active tasks without losing output or environmental context.
Persistent Code Terminal Use Cases
- Running long-duration AI coding operations via Codex CLI that require stability over several minutes or hours.
- Managing multiple coding projects simultaneously with dedicated, isolated shell environments for each repository.
- Maintaining active development servers or file watchers in the background while the AI agent performs other tasks.
- Executing remote development tasks over SSH or mobile interfaces where connection stability cannot be guaranteed.
How Persistent Code Terminal Works
- The skill initializes a dedicated tmux session for the specific project using the start.sh script to ensure a persistent environment.
- Commands are dispatched to the session via the send.sh utility, which appends a unique sentinel to track when the command finishes.
- A read.sh script monitors the session output, captures the exit code, and updates the local state tracking file.
- Intelligent routing logic analyzes natural language input to determine if the user wants to trigger a full Codex CLI execution chain or a simple terminal command.
- Status and summary scripts provide structured JSON or markdown feedback on the current state of the terminal and the progress of running tasks.
Persistent Code Terminal Setup
To get started with this skill, ensure you have tmux installed on your system. This is a primary requirement for most terminal-based Openclaw Skills.
# Install tmux on macOS using Homebrew
brew install tmux
# Install tmux on Linux (Ubuntu/Debian)
sudo apt-get update && sudo apt-get install tmux
# Initialize a persistent session for your current project
./bin/persistent-code-terminal-start.sh
Persistent Code Terminal Data Schema & Taxonomy
The skill manages its state locally within each project directory to ensure the AI agent always has context of the previous terminal actions.
| File | Description |
|---|---|
.pct-state.json |
The primary state file containing session ID, last command, exit code, and timestamps. |
*-code-session |
The tmux session identifier used to map terminal processes to specific projects. |
State Object Properties:
projectDir: The absolute path to the project root.session: The name of the active tmux session.lastCommand: The most recent string sent to the terminal.lastExitCode: The numerical return code of the last completed process.
Persistent Code Terminal Advanced Features
- Natural Language Intent Detection: Automatically routes messages to Codex CLI based on keywords like fix, build, or commit.
- Multi-Project Support: Handles complex instructions that span across different repositories by executing tasks serially.
- Codex-First Workflow: One-shot execution mode that leverages codex exec with configurable sandboxing and safety policies.
- Automated Retries: Built-in retry logic for instruction execution to ensure higher success rates in autonomous coding tasks.
- Structured Reporting: Supports --json output for all major scripts, allowing for easy integration into custom dashboards or agentic loops.
SKILL.md
Loading
Related Openclaw Skills
Agent Browser
A robust browser automation CLI designed for AI agents to navigate, interact with, and extract data from web pages using persistent sessions.
YT-to-Blog Content Engine
A comprehensive AI-powered pipeline that converts a single YouTube URL into a complete cross-platform content suite including blogs, social threads, and AI avatar videos.
GEDCOM Explorer
A Python-based tool that transforms static GEDCOM files into interactive, single-file HTML genealogy dashboards.
Dory-Memory
A robust file-based memory framework that ensures AI agents maintain task continuity and context across session resets.
Elsa x402 DeFi Tools
An advanced DeFi toolkit for portfolio management and automated swap execution powered by x402 micropayments.
Moltforsale
A competitive social arena where autonomous agents interact, build status, and execute power actions through a structured HTTP API.
Featured*
