Skip to content

Every OpenState tool — 22 structural code calls and 14 state and lifecycle tools, in every install

Read the function, not the file.

A coding agent with only a file reader works in whole files: it reads the file to change one function, reads it again when the line numbers move, and edits text it matched by eye. OpenState’s structural tools let it search for a definition, read just that definition, and change it through a preview it can check before anything is written.

openstate_ast_search→openstate_read_symbol→preview→apply

Where the tools and the state run

Tools, session recovery and automatic capture

HostSession captureCapsule deliveryState + structural tools
OpenCodeautomatic, from the host’s eventsgiven to the agent at the start of every session and after each compactionnative
Claude Code, Codex, Museon-demand replay of the host’s stored sessionson demand, via openstate_capsule36 tools via MCP
Other standard MCP clients (Kiro, GitHub Copilot, Cursor)replay of OpenCode, Claude Code, Codex and Muse sessions stored for the same projecton demand, via openstate_capsule36 tools via MCP

Every host gets all 36 tools. A session started in one agent can be picked up in another: any of them can replay the OpenCode, Claude Code, Codex and Muse histories stored for the same project.

Measured in the maintainer’s projects, August to October 2026

Fewer tokens per commit.

Measured on the maintainer’s own session history: cost moved with adoption; it is not a controlled study. Method and evidence →

Why it costs less: the agent reads the definition, not the file.

The difference

Units of code instead of files and line numbers.

The agent needs toWith a file reader and a text editorWith OpenState’s code tools
Find codeGrep output, or files opened to lookEach match with its file and line, for a definition, an identifier or literal text
Read one functionThe whole file, or a range of lines it has to guessThat complete function, and nothing else in the file
Change itRewrite text it matched by eyeA preview showing the change, then an apply that writes only that change
Cope with a file that changedDepends on the editor: some ask for a fresh read, others write over the changeRefuses a preview that no longer fits; applies a text edit whose anchor is still unique and says so
Cope with two matchesAsks for more surrounding text; the agent has to find the matches itselfRefuses, and lists every match so the agent can choose
Rename a function everywhereGrep for the name, open each file, edit each match by handOne preview listing every change across the files, then one apply
Move a function to another fileCopy it out, paste it in, delete the original, fix the spacingOne preview and one apply; blank lines stay right at both ends
Edit a file with Windows line endingsText typed with plain line breaks may not match the fileMatches with line_endings=normalize and keeps the file’s endings

How the agent uses them

Find, read, preview, apply.

01 FIND

Search

openstate_ast_search for the name or the text. The answer is a list of places, not file contents.

02 READ

Read one unit

openstate_read_symbol for a definition, openstate_read_text_region for prose and configuration.

03 PREVIEW

See the change

The matching preview tool returns the planned change and an identity. It writes nothing.

04 APPLY

Write it once

The apply tool writes exactly what the preview showed, and refuses a second use of the same identity.

The skill and the MCP server’s instructions tell the agent this order. In OpenCode you can go further: installing with OPENSTATE_STRUCTURAL_TOOLS=enforce denies the built-in read, grep and edit tools so every read and edit goes through the structural tools.

What the write path guarantees

Refusal instead of damage.

The tools

22 structural code calls = 8 readers + 7 preview/apply pairs

Find and read: eight tools that search, read and navigate without writing anything.

openstate_ast_searchDefinitions, identifiers or literal text, each match with file and line
openstate_read_symbolOne complete definition from one file
openstate_read_text_regionA bounded region around a unique piece of text
openstate_symbol_overviewThe symbols in a file or directory
openstate_find_declarationWhere a name is declared
openstate_find_referencing_symbolsDeclarations and references of a name
openstate_find_implementationsRust impl blocks for a type or trait
openstate_diagnosticsThe repository’s Rust cargo check for one file

Change, each as a preview and an apply. Searches, reads and previews are always free. Applies are free for the first 30 on each machine; after that they need a license.

openstate_edit_symbol_previewPreview replacing a whole definition
openstate_edit_symbol_applyWrite a previewed symbol replacement
openstate_insert_symbol_previewPreview inserting a definition before or after another
openstate_insert_symbol_applyWrite a previewed insertion
openstate_delete_symbol_previewPreview deleting a definition by its syntax-tree boundary
openstate_delete_symbol_applyWrite a previewed deletion
openstate_move_symbol_previewPreview moving a definition to another place or file
openstate_move_symbol_applyWrite a previewed move
openstate_rename_symbol_previewPreview renaming an identifier across its matches
openstate_rename_symbol_applyWrite a previewed rename
openstate_edit_text_previewPreview replacing a unique piece of text in any text file
openstate_edit_text_applyWrite a previewed text replacement
openstate_create_file_previewPreview creating a file that does not exist yet
openstate_create_file_applyWrite a previewed file creation

14 state and lifecycle tools

Session state and replay, completion notifications, and engine maintenance.

openstate_capsuleThe short resume summary: objective, decisions, blockers, next actions
openstate_stateEverything currently true: decisions, finished, in-progress and failed work, blockers
openstate_reportWhat is broken, stuck or unresolved right now
openstate_report_timelineThe same facts, session by session
openstate_whyWhere a fact came from, and what supports it
openstate_closeClose a fact that is wrong or done, with a reason
openstate_sessionsThis repository’s OpenCode, Claude Code, supported Codex and Muse sessions
openstate_assessReplay one of those sessions into the project’s memory
openstate_checkpointSave the state to disk now
openstate_exportExport the whole state and capsule as one JSON file
openstate_resetClear the state, after checking it can be rebuilt
openstate_restartSave, then check the state loads in a fresh engine
openstate_doctorEngine health: status, fact counts, last save
openstate_toastTurn OpenCode’s completion notifications on or off

Symbol tools work in Rust, Python, TypeScript, TSX, JavaScript, Go, C, C++, Java, C#, Bash, Kotlin, Lua, PHP, Ruby, Scala, Solidity and Swift. Built on ast-grep, which the installer bundles. In OpenCode they come through the plugin; in Claude Code, Codex, Muse, Cursor, Kiro, GitHub Copilot and other MCP hosts, through the bundled MCP server.