Skip to main content
Scratchpad tools give agents a shared workspace for collecting notes, drafting content, and coordinating findings before taking action. Instead of writing a comment or review immediately, agents can accumulate results in a scratchpad and publish only when ready.

​
Available tools

ToolParametersDescription
write_scratchpadname, contentCreate or overwrite a scratchpad.
append_scratchpadname, contentAppend to a scratchpad. Creates it if it doesn’t exist.
read_scratchpadnameRead the full content of a scratchpad.
list_scratchpads(none)List all scratchpad names in the current workspace.

​
Naming rules

Names support letters, numbers, hyphens, and underscores only — no slashes or spaces. Examples: findings, review-summary, security_notes, chunk-1

​
Collecting results before publishing

Agents often need to gather information across multiple files, tests, or analysis steps before producing a final output. Scratchpads act as a staging area — agents write findings as they go, then read the scratchpad to compose a polished comment, review, or ticket update. 
steps:
  - id: "code-review"
    name: "Code Review"
    action: "agent.run"
    params:
      agentId: "code-reviewer"
      instruction: |
        Review the PR changes. As you analyze each file, append your findings
        to the scratchpad "review-notes" using append_scratchpad.
        When done, read the scratchpad and post a single, organized review comment on the PR.
This pattern avoids scattered, incremental comments — the agent builds up a complete picture first, then publishes once.

​
Multi-agent collaboration

In an agent.session, multiple agents share the same scratchpads. Each agent can append its findings independently, and the coordinator can read everything to produce a consolidated result. Use append_scratchpad when multiple agents contribute — it prevents agents from overwriting each other’s work. 
steps:
  - id: "review-session"
    name: "Review Session"
    action: "agent.session"
    params:
      goal: "Review the PR for security, performance, and correctness"
      agentIds: ["security-expert", "performance-expert", "code-reviewer"]
      instruction: |
        Each agent: append your findings to the scratchpad "review-findings".
        When all reviews are done, read the scratchpad and post a combined review comment.

​
Passing context between workflow steps

Scratchpads persist across steps within a workflow run. An agent in one step can write a scratchpad that agents in later steps read — without relying on {{outputs}} templates. This is useful when:
  • The data is too large or structured for step output templates
  • Multiple steps need to build up a shared document incrementally
  • You want a later step to consume structured content directly
steps:
  - id: "analyze"
    name: "Analyze Codebase"
    action: "agent.run"
    params:
      agentId: "senior-developer"
      instruction: |
        Analyze the repository structure and write a summary to the scratchpad "analysis".
        Include key components, dependencies, and areas of concern.

  - id: "review"
    name: "Review Session"
    action: "agent.session"
    params:
      goal: "Review the code based on the analysis"
      agentIds: ["code-reviewer", "security-expert"]
      instruction: |
        Read the scratchpad "analysis" to understand the codebase context.
        Append your findings to "review-findings".
        When done, read "review-findings" and post a summary comment on the PR.

​
Content format

Scratchpads store plain text — but you control the format by instructing the agent what to write. You can use Markdown, JSON, JSONL, or any other text format that fits your workflow. For example, instruct an agent to append one JSON line per finding to make it easy for a later step to parse, or use Markdown for a human-readable draft.

​
When to use scratchpads vs step outputs

ScratchpadsStep outputs ({{outputs}})
Best forDrafting content, multi-agent collaboration, large or structured dataSimple values passed to the next step
FormatAny text (Markdown, JSON, JSONL, plain text)String from agent response
Multiple writersYes, via append_scratchpadNo — one step, one output
Readable byAny agent in any stepTemplate expressions in step params