92 lines
4.4 KiB
Markdown
92 lines
4.4 KiB
Markdown
# Paperclip agent launch research
|
|
|
|
Research date: 2026-05-07
|
|
|
|
This note records factual findings only. It is not an implementation plan and does not make recommendations.
|
|
|
|
## Scope
|
|
|
|
Compared Paperclip agent launch/runtime behavior with the local Agent Teams orchestrator.
|
|
|
|
Local orchestrator inspected:
|
|
|
|
- `/Users/belief/dev/projects/claude/agent_teams_orchestrator/src/tools/shared/spawnMultiAgent.ts`
|
|
- `/Users/belief/dev/projects/claude/agent_teams_orchestrator/src/services/teamBootstrap/teamBootstrapRunner.ts`
|
|
- `/Users/belief/dev/projects/claude/agent_teams_orchestrator/src/utils/swarm/processBackend.ts`
|
|
- `/Users/belief/dev/projects/claude/agent_teams_orchestrator/src/utils/swarm/teammateRuntimeEvents.ts`
|
|
|
|
Paperclip inspected from GitHub and a shallow local clone at `/tmp/paperclip-inspect`.
|
|
|
|
## Paperclip runtime model
|
|
|
|
Paperclip agents do not run continuously. They run in heartbeat windows triggered by wakeups such as timer, assignment, on-demand, or automation.
|
|
|
|
Each heartbeat starts an adapter, gives it prompt/context, lets it run until exit, timeout, or cancellation, stores run status/tokens/errors/logs, and updates UI.
|
|
|
|
Source: https://github.com/paperclipai/paperclip/blob/master/docs/agents-runtime.md
|
|
|
|
## Paperclip process execution
|
|
|
|
Paperclip uses child processes for local adapters. Normal execution is not tmux-based.
|
|
|
|
The shared process runner uses `node:child_process.spawn`, streams stdout/stderr, records pid and process group information, supports timeout, sends graceful termination, and escalates to kill after a grace period.
|
|
|
|
Source: https://github.com/paperclipai/paperclip/blob/master/packages/adapter-utils/src/server-utils.ts
|
|
|
|
The generic process adapter is documented as executing arbitrary shell commands as child processes with env injection and exit-code based success/failure.
|
|
|
|
Source: https://github.com/paperclipai/paperclip/blob/master/docs/adapters/process.md
|
|
|
|
## Paperclip adapter examples
|
|
|
|
Claude local adapter:
|
|
|
|
- Uses `claude --print - --output-format stream-json --verbose`.
|
|
- Supports session resume with `--resume`.
|
|
- Supports model/effort/max-turns/append-system-prompt/add-dir style options.
|
|
- Parses stream JSON for terminal result, session id, and usage.
|
|
|
|
Source: https://github.com/paperclipai/paperclip/blob/master/packages/adapters/claude-local/src/server/execute.ts
|
|
|
|
Codex local adapter:
|
|
|
|
- Uses `codex exec --json ... -`.
|
|
- Supports session continuation through `resume`.
|
|
- Manages `CODEX_HOME`, injected skills/config/auth context, and fresh-session fallback paths.
|
|
|
|
Source: https://github.com/paperclipai/paperclip/blob/master/packages/adapters/codex-local/src/server/execute.ts
|
|
|
|
OpenCode local adapter:
|
|
|
|
- Uses `opencode run --format json`.
|
|
- Supports `--session`, `--model`, and `--variant`.
|
|
- Uses temp config and model/session validation paths.
|
|
|
|
Source: https://github.com/paperclipai/paperclip/blob/master/packages/adapters/opencode-local/src/server/execute.ts
|
|
|
|
## Paperclip orchestration/lifecycle
|
|
|
|
Paperclip stores heartbeat runs and events, updates agent runtime state, publishes live events, stores run logs, supports cancellation by pid/process group, and has recovery paths for lost/orphaned running runs.
|
|
|
|
Source: https://github.com/paperclipai/paperclip/blob/master/server/src/services/heartbeat.ts
|
|
|
|
It has a per-agent start lock so concurrent starts for the same agent are coalesced or blocked.
|
|
|
|
Source: https://github.com/paperclipai/paperclip/blob/master/server/src/services/agent-start-lock.ts
|
|
|
|
It also has run liveness classification/recovery paths for cases like empty or low-signal runs.
|
|
|
|
Source: https://github.com/paperclipai/paperclip/blob/master/server/src/services/run-liveness.ts
|
|
|
|
## Comparison facts
|
|
|
|
Paperclip is organized around short, resumable heartbeat runs. It waits for CLI run completion and records result/logs/state.
|
|
|
|
Agent Teams is organized around live team members, mixed providers, direct messages, tasks, work-sync, runtime evidence, and durable bootstrap/check-in proof.
|
|
|
|
Paperclip does not need the same live teammate readiness model because it does not maintain a long-running team room with continuously addressable members.
|
|
|
|
Agent Teams still supports tmux/pane backends in the orchestrator, but current app-launched teammates can use process backend with app-managed runtime evidence.
|
|
|
|
Paperclip's process lifecycle primitives are more centralized. Agent Teams has more live multi-agent protocol surface and therefore more runtime states to reconcile.
|
|
|