Skip to content
Get packs

Guide · Agent skill

How to use the Persistent PTY Sessions agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

Persistent PTY Sessions is an agent skill from the Hive framework that teaches an AI agent to keep a live terminal open and talk to interactive programs such as Python's REPL, mysql, psql, node or ssh. It is for people who run multi-step terminal work where directory changes or environment variables must carry over between commands. After this guide you will know how to install the skill, how to phrase requests so the agent uses it, and which safety limits to keep in mind.

Persistent PTY Sessionsaden-hive/hive · Apache-2.0

Quick start

  1. 1Download and unzip. Download the skill ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder.
  2. 2Check the runtime. Confirm your Hive terminal tools runtime provides terminal_pty_open, terminal_pty_run and terminal_pty_close, and that /bin/bash exists.
  3. 3Ask for stateful work. Describe a task that needs directory changes, environment variables or an interactive program, and name the program if you have one.
  4. 4Let the agent open a session. The agent reads the skill, opens a session with terminal_pty_open and runs commands in the default mode.
  5. 5Drive REPLs with raw input. For Python, mysql or psql, the agent uses raw_send=True to type input and read_only=True to collect the output.
  6. 6Close the session. The agent should call terminal_pty_close when finished so the session does not count against the cap.

What agent skills are and what this one does

An agent skill is a folder containing a SKILL.md file that gives an AI agent instructions for a specific kind of task. This skill is named hive.terminal-tools-pty-sessions and is described as a preset skill from the aden-hive/hive project, licensed Apache-2.0.

Once installed, the agent knows when a persistent session is worth the cost, how to wait for a prompt, how to send raw input and read the response, and how to close sessions so they do not pile up against a fixed limit.

  • Keeps state across calls: cd, environment variables and sourced scripts.
  • Drives REPLs such as python -i, mysql, psql and node.
  • Answers interactive prompts such as sudo passwords and ssh host-key confirmations.
  • Always uses /bin/bash on macOS, never zsh.

Install the skill from a ZIP download

Download the ZIP for this skill from this page, then unzip it. You can put the skill in your personal skills folder or in a single project.

For a personal install, unzip into ~/.claude/skills/. For a project-only install, unzip into the project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

  • Personal: ~/.claude/skills/
  • Project: .claude/skills/ inside your project
  • Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Check the requirements before you rely on it

The skill depends on tools that this file does not provide. You need a Hive terminal tools runtime that supplies terminal_pty_open, terminal_pty_run and terminal_pty_close. The host also needs /bin/bash available.

An optional environment variable, TERMINAL_TOOLS_MAX_PTY, sets how many sessions can be open at once. Its default is 8.

  • Hive terminal tools runtime providing terminal_pty_open, terminal_pty_run and terminal_pty_close
  • /bin/bash available on the host
  • Optional: TERMINAL_TOOLS_MAX_PTY (default 8)

Trigger the skill with natural requests

You do not need a special command. Ask for something that needs state or an interactive program, and the agent should read the skill. The skill itself says to read it before calling terminal_pty_open.

Good requests name the thing that must persist or the program you want to drive. For ordinary one-off commands, the skill says the simpler terminal_exec tool is better, so ask for those plainly.

  • "Change into /var/log, list the .log files, then stay there for the next command."
  • "Open a Python shell, set x to 42 and print x squared."
  • "Connect to the mysql client and run a query, then read the output."
  • "Run ls -la in the current folder." (this suits terminal_exec, not a session)

Understand the three run modes

The skill teaches three ways to use terminal_pty_run. The default mode sends a command and waits for the session's prompt sentinel, returning the output. Only one call can be in flight per session; a concurrent call returns a "session busy" error.

For REPLs and password prompts, use raw_send=True to write bytes without waiting, then use read_only=True to drain what the program printed. For programs with their own prompt, pass expect with a regular expression so control returns when that prompt appears.

  • Default: send a command and wait for the prompt sentinel.
  • raw_send=True: write raw input and return immediately.
  • read_only=True: read output buffered since the last drain.
  • expect: a regex for a custom prompt such as >>> or mysql>.
terminal_pty_run(session_id, command="python3", expect=r">>>\s*$", timeout_sec=10) terminal_pty_run(session_id, command="x = 42", raw_send=True) terminal_pty_run(session_id, read_only=True)

Example: drive a Python REPL

This pattern from the skill opens a session, starts Python, sends input, reads the response and exits. Always close the session at the end.

sid = terminal_pty_open() terminal_pty_run(sid, command="python3", expect=r">>>\s*$") terminal_pty_run(sid, command="x = 42", raw_send=True) terminal_pty_run(sid, command="print(x*x)\n", raw_send=True) result = terminal_pty_run(sid, read_only=True) terminal_pty_run(sid, command="exit()", raw_send=True) terminal_pty_close(sid)

Always close sessions when you finish

Leaked sessions count against TERMINAL_TOOLS_MAX_PTY. Sessions idle longer than idle_timeout_sec (default 1800 seconds) are dropped lazily on later open calls, but the skill says not to rely on that. For a session that does not respond, force=True skips the graceful exit and goes straight to SIGTERM or SIGKILL.

  • Close each session with terminal_pty_close when the task is done.
  • Use force=True only for unresponsive sessions.
terminal_pty_close(session_id)

Safety notes: scripts, network and passwords

This skill runs scripts, because it starts real bash processes and whatever programs you ask them to run. It does not use the network itself, but programs you drive, such as ssh or mysql, may connect to remote hosts.

Passwords sent to a session end up in its ring buffer, so treat them carefully. The skill's own examples send sudo passwords and answer yes to ssh host-key confirmations. If you do not want the agent to type passwords or accept host keys, do not use this skill for those tasks.

  • Runs scripts: yes. Uses network: no (the programs you drive may).
  • Passwords are stored in the session buffer.
  • Accepting an ssh host key is an action you should review first.

What people use it for

  • Run a sequence of cd and ls commands while keeping the working directory between calls.
  • Use a Python REPL to test a few calculations with variables that persist.
  • Run queries in a psql or mysql shell and read the results back.
  • Answer an ssh host-key prompt and reach a password or login prompt.

Frequently asked questions

How do I install the Persistent PTY Sessions skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

What do I need to run this skill?

You need a Hive terminal tools runtime that provides terminal_pty_open, terminal_pty_run and terminal_pty_close, plus /bin/bash on the host. The optional TERMINAL_TOOLS_MAX_PTY variable sets the session limit, which defaults to 8.

Is this skill free to use?

The skill is licensed under Apache-2.0, as listed for the aden-hive/hive project. This page does not state any price, so check the source repository for licence details.

Why does the skill use bash on macOS instead of zsh?

The skill always invokes /bin/bash for PTY sessions, even when zsh is the user's default shell. The skill says this gives one shell behaviour across platforms and avoids zsh features that bypass bash-shaped security checks. Explicit shell=/bin/zsh is rejected.

When should I use terminal_exec instead of a persistent session?

Use terminal_exec for simple one-off shell commands. The skill notes that sessions cost more because each one runs a bash process with a ring buffer and idle bookkeeping, and they have a hard cap.

Can I use this skill to type passwords or accept ssh host keys?

The skill's examples do this, but passwords end up in the session buffer and host-key prompts are accepted with yes. If you need to avoid those risks, do not give the agent those tasks.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

This skill suits developers and teams running the Hive framework who need an agent to keep shell state or drive a REPL, database shell or interactive program and read the results. It is the wrong choice for simple one-off commands, for environments where the agent must not type passwords or accept host keys, or for anyone not running Hive-compatible terminal tools.

Download the skill