paperclip/doc/spec/agents-runtime.md

Agent Runtime Guide

Status: User-facing guide
Last updated: 2026-02-17
Audience: Operators setting up and running agents in Paperclip

1. What this system does

Agents in Paperclip do not run continuously.
They run in heartbeats: short execution windows triggered by a wakeup.

Each heartbeat:

1. Starts the configured agent adapter (for example, Claude CLI or Codex CLI)
2. Gives it the current prompt/context
3. Lets it work until it exits, times out, or is cancelled
4. Stores results (status, token usage, errors, logs)
5. Updates the UI live

2. When an agent wakes up

An agent can be woken up in four ways:

• timer: scheduled interval (for example every 5 minutes)
• assignment: when work is assigned/checked out to that agent
• on_demand: manual wakeup (button/API)
• automation: system-triggered wakeup for future automations

If an agent is already running, new wakeups are merged (coalesced) instead of launching duplicate runs.

3. What to configure per agent

3.1 Adapter choice

Common choices:

• claude_local: runs your local claude CLI
• codex_local: runs your local codex CLI
• process: generic shell command adapter
• http: calls an external HTTP endpoint

For claude_local and codex_local, Paperclip assumes the CLI is already installed and authenticated on the host machine.

3.2 Runtime behavior

In agent runtime settings, configure heartbeat policy:

• enabled: allow scheduled heartbeats
• intervalSec: timer interval (0 = disabled)
• wakeOnAssignment: wake when assigned work
• wakeOnOnDemand: allow ping-style on-demand wakeups
• wakeOnAutomation: allow system automation wakeups

3.3 Working directory and execution limits

For local adapters, set:

• cwd (working directory)
• timeoutSec (max runtime per heartbeat)
• graceSec (time before force-kill after timeout/cancel)
• optional env vars and extra CLI args

3.4 Prompt templates

You can set:

• promptTemplate: used for every run (first run and resumed sessions)

Templates support variables like {{agent.id}}, {{agent.name}}, and run context values.

4. Session resume behavior

Paperclip stores resumable session state per (agent, taskKey, adapterType). taskKey is derived from wakeup context (taskKey, taskId, or issueId).

• A heartbeat for the same task key reuses the previous session for that task.
• Different task keys for the same agent keep separate session state.
• If restore fails, adapters should retry once with a fresh session and continue.
• You can reset all sessions for an agent or reset one task session by task key.

Use session reset when:

• you significantly changed prompt strategy
• the agent is stuck in a bad loop
• you want a clean restart

5. Logs, status, and run history

For each heartbeat run you get:

• run status (queued, running, succeeded, failed, timed_out, cancelled)
• error text and stderr/stdout excerpts
• token usage/cost when available from the adapter
• full logs (stored outside core run rows, optimized for large output)

In local/dev setups, full logs are stored on disk under the configured run-log path.

6. Live updates in the UI

Paperclip pushes runtime/activity updates to the browser in real time.

You should see live changes for:

• agent status
• heartbeat run status
• task/activity updates caused by agent work
• dashboard/cost/activity panels as relevant

If the connection drops, the UI reconnects automatically.

7. Common operating patterns

7.1 Simple autonomous loop

1. Enable timer wakeups (for example every 300s)
2. Keep assignment wakeups on
3. Use a focused prompt template that tells agents to act in the same heartbeat, leave durable progress, and mark blocked work with an owner/action
4. Watch run logs and adjust prompt/config over time

7.2 Event-driven loop (less constant polling)

1. Disable timer or set a long interval
2. Keep wake-on-assignment enabled
3. Use child issues, comments, and on-demand wakeups for handoffs instead of loops that poll agents, sessions, or processes

7.3 Safety-first loop

1. Short timeout
2. Conservative prompt
3. Monitor errors + cancel quickly when needed
4. Reset sessions when drift appears

8. Troubleshooting

If runs fail repeatedly:

1. Check adapter command availability (claude/codex installed and logged in).
2. Verify cwd exists and is accessible.
3. Inspect run error + stderr excerpt, then full log.
4. Confirm timeout is not too low.
5. Reset session and retry.
6. Pause agent if it is causing repeated bad updates.

Typical failure causes:

• CLI not installed/authenticated
• bad working directory
• malformed adapter args/env
• prompt too broad or missing constraints
• process timeout

9. Security and risk notes

Local CLI adapters run unsandboxed on the host machine.

That means:

• prompt instructions matter
• configured credentials/env vars are sensitive
• working directory permissions matter

Start with least privilege where possible, and avoid exposing secrets in broad reusable prompts unless intentionally required.

10. Minimal setup checklist

1. Choose adapter (claude_local or codex_local).
2. Set cwd to the target workspace.
3. Add bootstrap + normal prompt templates.
4. Configure heartbeat policy (timer and/or assignment wakeups).
5. Trigger a manual wakeup.
6. Confirm run succeeds and session/token usage is recorded.
7. Watch live updates and iterate prompt/config.