@leoustc/piterm

piterm is a local terminal runtime for running shell commands and non-interactive coding-agent prompts from a CLI or a small web terminal.

The default runtime agent is Codex in exec/json mode:

codex exec <flags> --json <prompt>

Pi is used only for login/backend setup.

Install

npm install -g @leoustc/piterm

Requires Node >=22.19.0.

Login

piterm login

This opens the vendored Pi login flow, equivalent to pi /login, so credentials can be reused by multiple piterm installs.

Run Commands

Run a shell command:

piterm "ls -lF"

Use a dedicated runtime folder:

piterm --agentdir ./local "hello"

Without a command, or with -i, piterm opens an interactive prompt:

piterm
piterm -i

Interactive mode reads one command per line and exits on exit, quit, or Ctrl-D.

Web Terminal

Start the local web terminal:

piterm -d --port 8000 --agentdir ./local --debug

Then open:

http://localhost:8000/

The web terminal can:

• run shell commands with runCommand
• send prompts with runPrompt
• stream command output through SSE
• show agent thinking/result streams
• upload files and attach them to the next prompt
• render agent results as markdown

The daemon binds to 127.0.0.1 by default. Use --host only when you intentionally want to expose it elsewhere.

Uploads And Memory

Uploaded files are saved under:

<agentdir>/uploads/

After upload, the web input gets a #filename reference. Each prompt writes request context through the agent memory module:

<agentdir>/
  AGENTS.md
  .session.id
  uploads/
  memory/
    MEMORY.md
    HINTS.md
    DONOT.md
    log/YYYY-MM-DD.jsonl
    notes/YYYY-MM-DD.jsonl
    memory/YYYY-MM-DD.jsonl

The daily log JSONL stores the requestId, prompt text, and uploaded file paths. The agent prompt receives the memory module paths, so the agent can inspect the log when the user says things like check this image.

At runtime, piterm copies src/RUNTIME-AGENTS.md to <agentdir>/AGENTS.md if it does not already exist.

Agent Recovery

piterm first runs a command directly as a shell command. If it fails, piterm falls back to the configured agent.

The runtime agent is always started in non-interactive exec mode. If execution fails because the flags are wrong, the configured agent is asked to rewrite only the flags, then piterm retries the same prompt.

Useful environment variables:

PITERM_AGENT=codex
PITERM_AGENT_FLAGS=--skip-git-repo-check
PITERM_AGENT_JSON_FLAG=--json
PITERM_AGENTDIR=./local

HTTP API

POST / accepts command or prompt requests. Responses stream as Server-Sent Events by default.

Command request:

{"command":"ls -lF"}

Prompt request:

{"prompt":"review this folder"}

Set "stream": false or send Accept: application/json for a single JSON response.

POST /upload accepts multipart/form-data uploads and returns saved file paths.

JavaScript API

const piterm = require('@leoustc/piterm');

await piterm.runCommand('echo hello');
await piterm.runPrompt('review this folder');

Local Development

Build a local binary:

make build

Run the web terminal from local/:

make run
make r

Run interactive mode from local/:

make interactive
make i

Run tests:

make test
make workflow

Dry-run the package:

make pack

Publish:

make login
make release

make release checks that npm whoami is authenticated as the package scope owner before publishing @leoustc/piterm.

License

MIT