Skip to main content
@obversa/engine-claude-agent-sdk runs requests through the Claude Agent SDK: each request is a fresh SDK query() call, so every step starts with a clean context. Use it instead of the Claude CLI engine when you want Claude to reach a memory adapter as a tool, or when the SDK’s process model suits your host better.

​
Install

Included in @obversa/obversa. Each query runs clean by default: with your own login and the repository’s settings and instruction files, but without your own settings, hooks, plugins, skills and MCP servers. Set clean: false to run it the way Claude Code runs for you: the plugin then loads the setting sources Claude Code loads (user, project and local). Either way it adds only what the step needs.

​
Requirements

  • Claude Code signed in on the machine that runs the engine. The SDK uses its sign-in, and the plugin has no API key option.
  • The plugin is tested with Claude Agent SDK 0.3.241, the version it depends on.

​
Identity

The plugin reports provider: 'anthropic', with the model family read from the model name. It runs the model the request names, or defaultModel when the request names none.

​
Quickstart

Construct the engine with a default model:
examples/engine-claude-agent-sdk-binding.ts
This engine has no admit, so it reports its identity when it runs, not before; a plan that asks for engine checks treats it as unsupported and says whether that blocks the run. Run it with npx tsx engine-claude-agent-sdk-binding.ts:
Output
Pass the engine to run() in engines, or bind it to a graph node.

​
Give Claude memory

Pass any adapter that implements the Memory contract from @obversa/api as the memory option, such as openGitMemory from Git Memory, and Claude reaches it as an MCP tool. AGENT_SDK_MEMORY_TOOL_DESCRIPTION is the tool’s description, and AGENT_SDK_MEMORY_INSTRUCTIONS the warning that memory content is untrusted data. agentSdkMemoryAllowedTools and agentSdkMemoryToolResult are the pieces that wire the tool to a Memory adapter.

​
Options

​
permissionMode

default, acceptEdits, bypassPermissions, plan, dontAsk or auto. In the read workspace mode Claude gets only the Read, Grep and Glob tools the request names; in none it gets no tools. Both modes block Bash, Edit, Write, the sub-agent tools and every MCP tool. With clean: false the SDK also loads your own settings, and they can’t restore those tools. Your own hooks run too, though, and a hook can write files; a clean run leaves your hooks out.

​
clean

true loads only the repository’s settings (settingSources: ['project']) and turns on strictMcpConfig. Your own settings, hooks, plugins, skills, MCP servers and ~/.claude/CLAUDE.md stay out. The repository’s settings and instruction files still apply, and the run keeps your login. Its row in the engines table: runs on your setup, clean mode available, read-only held in clean mode. On your own setup the model’s tools stay read-only, but your own hooks still run and can change files. Clean mode also leaves out the repository’s own MCP servers, because the switch that keeps yours out keeps every server out.

​
The rest

​
Errors

  • EngineError kinds as the API lists them.

​
API

  • AgentSdkEngine: the engine class. AgentSdkEngineOptions: its options. Quickstart.
  • agentSdkToolOptions, agentSdkPermissionOptions, agentSdkSystemPrompt: how a request becomes SDK options.
  • agentSdkMemoryAllowedTools, agentSdkMemoryToolResult, AGENT_SDK_MEMORY_INSTRUCTIONS, AGENT_SDK_MEMORY_TOOL_DESCRIPTION: the memory tool. Give Claude memory.
  • toolPacer: the pacing behind minToolIntervalMs.

​
Next steps

  • Claude CLI Engine: the same sign-in through the CLI, with the seat helper for workflow().
  • Git Memory: the adapter in the snippet above.