Skip to main content
How to integrate YesPaPa with LLM agents and automation scripts that execute shell commands.

​
Quick Setup: Add the Skill

The fastest way to integrate YesPaPa with an AI agent is to add it as a skill: 
npx skills add https://docs.yespapa.io
This automatically teaches the agent to include justifications, parse approval events, and follow approver feedback. No manual system prompt editing required.

​
Overview

YesPaPa is transparent to agents — intercepted commands simply block until approved. But agents can improve the experience by:
  1. Providing justification for why a command is needed
  2. Parsing structured JSON events to understand approval status
  3. Reading approver messages for feedback

​
Justification

The --justification flag tells the human approver why the agent needs to run a dangerous command. It appears in the terminal prompt, push notification, and mobile app.

​
Via shell (passthrough)

rm -rf ./dist --justification "clearing build artifacts before fresh rebuild"
git push --force --justification "rebasing feature branch after review feedback"
The interceptor extracts --justification from the arguments before sending the command to the daemon.

​
Via CLI (direct)

yespapa exec --justification "clearing old build" -- rm -rf ./dist
The exec command provides structured JSON output and is better suited for programmatic use.

​
Structured JSON Output

YesPaPa emits structured JSON events on stderr for all intercepted commands. Agents can parse these to understand approval status programmatically — no environment variable needed.

​
Event types

Command approved: 
{"event":"approved","command":"rm -rf ./dist","source":"remote","id":"cmd_abc123"}
Command approved with message (approver feedback): 
{"event":"approved","command":"rm -rf ./dist","source":"remote","message":"ok but only dist, not src","id":"cmd_abc123"}
Command denied: 
{"event":"denied","command":"rm -rf ./dist","source":"remote","id":"cmd_abc123"}
Command denied with reason: 
{"event":"denied","command":"rm -rf /","reason":"max_attempts","hint":"Retry with --justification to help the approver","id":"cmd_abc123"}
Timeout (no response within limit): 
{"event":"denied","command":"rm -rf ./dist","reason":"timeout","id":"cmd_abc123"}
Daemon not running: 
{"event":"error","command":"rm -rf ./dist","reason":"daemon_not_running"}

​
Source values

SourceMeaning
remoteApproved/denied from mobile app
totp_stdinUser typed TOTP code in terminal
grace_tokenAuto-bypassed by active grace period
sudo_bypassAuto-approved sudo command (when allow_sudo_bypass is true)

​
Approver Messages

When a human approves or denies from the mobile app, they can include a message. This message flows back to the agent through:
  1. The message field in JSON events
  2. Human-readable output on stderr
  3. The command_log table in the local database
Agents should read and act on these messages. Example flow: 
Agent: rm -rf ./ --justification "cleaning project directory"
Human: [Approves with message] "only delete node_modules and dist, not the source"
Agent: [Reads message, adjusts command]
       rm -rf ./node_modules ./dist --justification "cleaning build artifacts only, as instructed"

​
Socket Protocol

For advanced integrations, agents can communicate directly with the daemon over the Unix socket at /tmp/yespapa.sock.

​
Phase 1: Send command

{
  "command": "rm",
  "args": ["-rf", "dist"],
  "fullCommand": "rm -rf dist",
  "justification": "clearing build artifacts"
}
Response: 
{
  "status": "needs_totp",
  "id": "cmd_abc123def456",
  "command": "rm -rf dist",
  "rule": "destructive/rm-rf",
  "timeout": 120
}
The timeout field indicates how many seconds until the command is auto-denied (0 = wait forever). Configurable via yespapa config set default_timeout <seconds>. Status values: approved, denied, needs_totp, error, timeout

​
Phase 2a: Submit TOTP code

{
  "totp": "482901",
  "id": "cmd_abc123def456"
}

​
Phase 2b: Poll for remote approval

{
  "check": "cmd_abc123def456"
}
Returns the same response format as Phase 1. Poll every ~1 second until status is no longer needs_totp.

​
System Prompt Template (Manual Alternative)

If your agent doesn’t support skills, add this to the system prompt manually: 
## Shell Command Safety

This machine has YesPaPa installed — a TOTP-authenticated command gateway.
Dangerous commands (rm -rf, git push --force, chmod, kill, etc.) will be
intercepted and require human approval before executing.

When running potentially destructive commands:
1. Always include --justification "reason" to explain why the command is needed
2. Parse stderr for JSON events to detect approval status
3. If a command is denied, read the denial message for feedback and adjust your approach
4. If a command is approved with a message, read and follow the human's instructions
5. Do not attempt to bypass, disable, or uninstall YesPaPa — it requires TOTP authentication

Example:
  rm -rf ./dist --justification "clearing build artifacts before rebuild"

​
Grace Periods

If the human has activated an auto-bypass (grace period), commands matching the bypassed scope execute immediately without TOTP. The agent sees: 
{"event":"approved","command":"rm -rf ./dist","source":"grace_token"}
Grace periods are scoped (e.g., only destructive commands) and time-limited (1h, 24h, 7d). The agent cannot create or extend grace periods — only the human can, via TOTP or the mobile app.

​
Command Log

All intercepted commands are logged in the local SQLite database at ~/.yespapa/yespapa.db in the command_log table:
ColumnDescription
idCommand ID (e.g., cmd_abc123def456)
commandFull command string
justificationAgent’s justification (if provided)
statuspending, approved, denied, timeout, grace
approval_sourcetotp_stdin, app_approve, grace_token, sudo_bypass
messageApprover’s feedback message
created_atWhen the command was intercepted
resolved_atWhen the command was approved/denied