> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yespapa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Integration

> How to integrate YesPaPa with LLM agents and automation scripts

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:

```bash theme={null}
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)

```bash theme={null}
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)

```bash theme={null}
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:**

```json theme={null}
{"event":"approved","command":"rm -rf ./dist","source":"remote","id":"cmd_abc123"}
```

**Command approved with message (approver feedback):**

```json theme={null}
{"event":"approved","command":"rm -rf ./dist","source":"remote","message":"ok but only dist, not src","id":"cmd_abc123"}
```

**Command denied:**

```json theme={null}
{"event":"denied","command":"rm -rf ./dist","source":"remote","id":"cmd_abc123"}
```

**Command denied with reason:**

```json theme={null}
{"event":"denied","command":"rm -rf /","reason":"max_attempts","hint":"Retry with --justification to help the approver","id":"cmd_abc123"}
```

**Timeout (no response within limit):**

```json theme={null}
{"event":"denied","command":"rm -rf ./dist","reason":"timeout","id":"cmd_abc123"}
```

**Daemon not running:**

```json theme={null}
{"event":"error","command":"rm -rf ./dist","reason":"daemon_not_running"}
```

### Source values

| Source        | Meaning                                                       |
| ------------- | ------------------------------------------------------------- |
| `remote`      | Approved/denied from mobile app                               |
| `totp_stdin`  | User typed TOTP code in terminal                              |
| `grace_token` | Auto-bypassed by active grace period                          |
| `sudo_bypass` | Auto-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

```json theme={null}
{
  "command": "rm",
  "args": ["-rf", "dist"],
  "fullCommand": "rm -rf dist",
  "justification": "clearing build artifacts"
}
```

**Response:**

```json theme={null}
{
  "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

```json theme={null}
{
  "totp": "482901",
  "id": "cmd_abc123def456"
}
```

### Phase 2b: Poll for remote approval

```json theme={null}
{
  "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:

```json theme={null}
{"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:

| Column            | Description                                               |
| ----------------- | --------------------------------------------------------- |
| `id`              | Command ID (e.g., `cmd_abc123def456`)                     |
| `command`         | Full command string                                       |
| `justification`   | Agent's justification (if provided)                       |
| `status`          | `pending`, `approved`, `denied`, `timeout`, `grace`       |
| `approval_source` | `totp_stdin`, `app_approve`, `grace_token`, `sudo_bypass` |
| `message`         | Approver's feedback message                               |
| `created_at`      | When the command was intercepted                          |
| `resolved_at`     | When the command was approved/denied                      |