Local state

Local state tools store agent working context under the resolved plugin data directory. They are useful when information should persist across tool calls, subagents, reviews, or sessions without creating ad-hoc files in the project.

Data directory

Stateful tools use this resolution order:

$OPENCODE_DATA_DIR
paths.dataDir from trusted global squad.json
$OPENCODE_CONFIG_DIR/data or ~/.config/opencode/data

See Local paths for the trust model.

Scratchpads

Tool	Side effects	Purpose
`scratchpad_session`	None.	Returns the current scratchpad session ID.
`scratchpad_read`	Reads plugin-managed state.	Reads scratchpad content.
`scratchpad_write`	Writes plugin-managed state.	Replaces or appends scratchpad content.
`scratchpad_patch`	Writes plugin-managed state.	Applies exact replacement patches to scratchpad content.

Scratchpads are for temporary session notes, planning, and agent-to-agent context. They are not a substitute for project documentation.

Handoffs

Tool	Side effects	Purpose
`handoff_prepare`	None.	Explains how to prepare concise persistent handoff content.
`handoff_write`	Writes plugin-managed state.	Writes a persistent handoff for future sessions.
`handoff_list`	Reads plugin-managed state.	Lists recent handoffs.
`handoff_read`	Reads plugin-managed state.	Reads a handoff, defaulting to the most recent one.

Handoffs are Markdown files with frontmatter under:

<dataDir>/handoffs

They expose stable hashes, titles, timestamps, and project metadata so future sessions can recover context without relying on fragile conversation history.

Review context

Tool	Side effects	Purpose
`review_context_init`	Writes plugin-managed state.	Initializes review context storage.
`review_context_put`	Writes plugin-managed state.	Stores review context snippets.
`review_context_get`	Reads plugin-managed state.	Retrieves stored review context.

Review context is for coordinated code-review workflows where several agents need to share findings, file references, or intermediate analysis.

Git hygiene

State tools write to plugin-managed data directories, not the project checkout. Still, do not copy secrets, credentials, or generated state into Git-tracked files.

On this page