SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillscoding-runner

coding-runner

Coding & development

View repository

Updated 10-16 05:06

About this skill

coding-runner (tmux-only, docs-only)

Goal: no longer implement a separate script/entry point; use only one document to explain how to reuse the existing tmux skill to run code-type CLIs.

You only need to tell the agent what to do; internally the agent uses tmux to start a session, and returns according to the following specification: socket, session, start/inspect/stop commands.

1. Unified principles

  1. Use only tmux, not interactive_shell
    • All scenarios that require "running a CLI to write code / starting a dev server / long-running tasks" must go through tmux.
  2. Do not write new scripts, do not implement new entry points
    • This skill has only this Markdown document, with no index.ts or similar implementation files.
    • When needed, the agent directly refers to this description and uses the existing tmux skill / tmux commands to complete the task.
  3. Always return 3 types of commands (to satisfy the gateway protocol)
    • start: the start command that has already been executed (for reference).
    • inspect: the command to inspect / attach to the session.
    • stop: the command to stop the session.

2. tmux session conventions

2.1 Socket path

Use uniformly (example convention, can be adjusted according to the actual tmux skill):

SOCKET="/tmp/pi-tmux-sockets/pi.sock"

2.2 Session naming

  • Use short names without spaces, for example:
    • pi-task-<slug>
    • pi-dev-<project>
  • Example:
SESSION="pi-task-auth-fix"

3. Typical usage templates

3.1 Start a code task (Codex / pi / Claude / OpenCode)

Example: in /path/to/project , use Codex to fix a bug.

  1. Construct the command to execute (example):
CMD="cd /path/to/project && codex exec --full-auto 'Fix the auth bug in auth.ts'"
  1. Start the tmux session:
SOCKET="/tmp/pi-tmux-sockets/pi.sock"
SESSION="pi-task-auth-fix"

mkdir -p "$(dirname "$SOCKET")"
tmux -S "$SOCKET" new -d -s "$SESSION" "$CMD"
  1. The three commands returned to the user / gateway:
# 启动命令（已执行，仅供记录）
tmux -S /tmp/pi-tmux-sockets/pi.sock new -d -s pi-task-auth-fix "cd /path/to/project && codex exec --full-auto 'Fix the auth bug in auth.ts'"

# 查看 / 进入会话
tmux -S /tmp/pi-tmux-sockets/pi.sock attach -t pi-task-auth-fix

# 停止会话
tmux -S /tmp/pi-tmux-sockets/pi.sock kill-session -t pi-task-auth-fix

In its response, the agent should provide at least the latter two commands (inspect/stop), and explain the socket and session names.

3.2 Start a dev server service

Example: in /path/to/project , run npm run dev。

SOCKET="/tmp/pi-tmux-sockets/pi.sock"
SESSION="pi-dev-myproj"

CMD="cd /path/to/project && npm run dev"
mkdir -p "$(dirname "$SOCKET")"
tmux -S "$SOCKET" new -d -s "$SESSION" "$CMD"

# 返回给用户：
# 查看
#   tmux -S /tmp/pi-tmux-sockets/pi.sock attach -t pi-dev-myproj
# 停止
#   tmux -S /tmp/pi-tmux-sockets/pi.sock kill-session -t pi-dev-myproj

4. Safety and constraints

  1. Do not start session commands in sensitive directories

    • Do not use the following directories as the working directory:
      • ~/.pi/agent
      • ~/.pi/gateway
    • If you need to operate on these directories, use dedicated maintenance scripts instead of a coding tmux session.

  2. Respect the user's explicit requests

    • If the user specifically specifies the command / session name / socket, follow the user.
    • If the user only describes the goal, the agent decides on reasonable commands and naming itself.

  3. Non-blocking

    • Return immediately after starting the session; do not wait in the conversation for the command to complete.
    • All subsequent operations (viewing logs, stopping) are done by the user executing tmux commands.

5. Behavior summary (for the Agent)

  • When the user raises a request such as "need to run a code-type task / start a dev server / open a long-running CLI":
    1. Determine the working directory and the CLI command to execute (Codex / Claude / pi / OpenCode, etc.).
    2. Choose an appropriate tmux session name.
    3. Create a tmux session on /tmp/pi-tmux-sockets/pi.sock according to the template in this file.
    4. In the response, return: the socket path, the session name, and the commands for attach / kill .
  • Do not create new skill scripts or entry files; all logic is completed through this description + tmux skill/commands.