Prompt buttons - Buttons

Prompt buttons let you embed an instruction set directly into a button. When the button is pressed, the JSON output includes a prompt field that the calling agent can read and act on. You can use --prompt in two ways: as a standalone button that contains only instructions, or as a modifier on an existing code or HTTP button.

Standalone prompt button

A standalone prompt button has no code to execute. It just carries an instruction. Use this to encode a task, a decision procedure, or an analysis request that an agent should carry out itself.

buttons create summarize-pr \
  --prompt 'You are a code reviewer. Read the diff passed in the `diff` argument and write a summary of what changed, why it matters, and any risks. Return JSON with keys: summary, risks, verdict.' \
  --arg diff:string:required \
  -d "Summarize a pull request diff"

A standalone prompt button runs no code. Pressing it validates the declared args, then returns the instruction verbatim — the prompt is not templated, so ${arg}/BUTTONS_ARG_* substitution does not happen here. The instruction text lands in both the prompt and stdout fields, and the args you passed are echoed back under args, so the caller can hand the whole thing straight to an LLM:

buttons press summarize-pr --arg diff="$(git diff main)" --json

{
  "ok": true,
  "data": {
    "button": "summarize-pr",
    "status": "ok",
    "exit_code": 0,
    "stdout": "You are a code reviewer. Read the diff passed in the `diff` argument...",
    "prompt": "You are a code reviewer. Read the diff passed in the `diff` argument...",
    "args": { "diff": "diff --git a/... b/..." }
  }
}

Prompt as a modifier

Add --prompt to a code or HTTP button to attach supplementary instructions alongside the execution result. The code runs first, then the result and the prompt are both present in the output.

buttons create analyze-logs \
  --code 'tail -n 200 /var/log/app.log' \
  --runtime shell \
  --prompt 'Analyze the log lines in stdout. Identify error patterns, classify by severity, and suggest the most likely root cause. Return JSON.' \
  -d "Collect recent logs and instruct the agent to analyze them"

Press:

buttons press analyze-logs --json

{
  "ok": true,
  "data": {
    "button": "analyze-logs",
    "status": "ok",
    "stdout": "2026-04-10T12:00:01Z ERROR db connection timeout...",
    "stderr": "",
    "exit_code": 0,
    "prompt": "Analyze the log lines in stdout. Identify error patterns..."
  }
}

The agent receives both the raw output and the instruction in a single structured response.

Updating prompt instructions

The prompt lives at ~/.buttons/buttons/<name>/AGENTS.md — the AGENTS.md convention agents look for (a legacy singular AGENT.md is still read if present, but every write goes to AGENTS.md). Edit it directly, or recreate the button:

buttons delete summarize-pr
buttons create summarize-pr --prompt 'Updated instructions...' --arg diff:string:required

Store your prompt text in a file and pipe it in for longer instructions:

buttons create analyze-logs \
  --code 'tail -n 200 /var/log/app.log' \
  --prompt "$(cat prompts/log-analysis.txt)" \
  --runtime shell

Code buttons — add code execution alongside a prompt
Arguments — typed args validated at press time and echoed in the result (and, on code/HTTP buttons, available as BUTTONS_ARG_*)
JSON output — reading prompt programmatically

​Standalone prompt button

​Prompt as a modifier

​Updating prompt instructions

​Related

Standalone prompt button

Prompt as a modifier

Updating prompt instructions

Related