Open Agent SDK (TypeScript): an in-process agent loop without the Claude CLI

The problem: agent code that drags a CLI along

Most TypeScript agent libraries that target Claude models do not implement the loop themselves. They shell out to the Claude Code CLI, which means your deployment needs a Node binary, a globally installed CLI, a writable home directory for its config, and a subprocess that has to survive cold starts. In a Lambda function or a distroless container that is a real constraint, not a stylistic one.

@codeany/open-agent-sdk takes the other route. The package description says it "Runs the full agent loop in-process, no local CLI required." The loop, the tool dispatch, the permission checks and the MCP client all live in your process. The README positions it as an alternative to claude-agent-sdk and lists the deployment targets it cares about: cloud, serverless, Docker, CI/CD.

The audience is narrow and specific. You are writing TypeScript, you want tool-using agents rather than a single chat completion, and you have decided the CLI dependency is the thing you cannot ship. If you are happy running Claude Code interactively, this SDK solves a problem you do not have.

What runs in your process: query, createAgent and the tool registry

There are two entry points and they share one implementation. query() is the streaming form: you pass a prompt and options, and you consume an async iterable of messages, filtering on message.type. createAgent() is the blocking form: it returns an object with prompt(), getMessages() and close(), and prompt() resolves to a result carrying text, num_turns and usage tokens.

Around that core sit four extension surfaces. Tools are either low-level defineTool() objects with a JSON Schema inputSchema and a call() function, or Zod-schema tools wrapped by tool() and mounted on an MCP server created with createSdkMcpServer(). Skills are prompt templates registered with registerSkill() and exposed to the model through a Skill tool; the README says five ship in the box: simplify, commit, review, debug and test. Hooks are a registry keyed by lifecycle event, created with createHookRegistry(), and the README lists 20 events including PreToolUse, PostToolUse, SessionStart, PreCompact and SubagentStart. Subagents are declared inline in query options as named entries with a description, a prompt and a restricted tool list.

The provider layer is the part worth reading twice. The SDK depends on @anthropic-ai/sdk and speaks Anthropic's message format, but apiType: "openai-completions" routes through OpenAI-compatible endpoints instead. The README states that apiType is auto-detected from the model name, and that models containing gpt-, o1, o3, deepseek, qwen or mistral switch automatically. That is a string heuristic. It will do the right thing for the names it lists and nothing for a fine-tune or a proxy that renames the model, and in those cases you set apiType explicitly.

Install and first run with an OpenAI-compatible endpoint

The README gives one install command and one required environment variable. Node 18 or newer is declared in the engines field of package.json, so check that before anything else.

npm install @codeany/open-agent-sdk
export CODEANY_API_KEY=your-api-key

To point at an OpenAI-compatible endpoint rather than Anthropic, the README shows four variables. CODEANY_API_TYPE selects the wire format, CODEANY_BASE_URL sets the endpoint, CODEANY_MODEL names the model.

npm install @codeany/open-agent-sdk
export CODEANY_API_TYPE=openai-completions
export CODEANY_API_KEY=sk-...
export CODEANY_BASE_URL=https://api.openai.com/v1
export CODEANY_MODEL=gpt-4o

The repository also ships a .env.example with CODEANY_API_KEY, an optional CODEANY_MODEL and an optional CODEANY_BASE_URL, with a commented example pointing at https://openrouter.ai/api.

For a first real call, use the blocking API. The README's example creates an agent with an explicit model, asks a question about the current project, and prints the answer plus turn and token counts.

import { createAgent } from "@codeany/open-agent-sdk";

const agent = createAgent({ model: "claude-sonnet-4-6" });
const result = await agent.prompt("What files are in this project?");

console.log(result.text);
console.log(
  `Turns: ${result.num_turns}, Tokens: ${result.usage.input_tokens + result.usage.output_tokens}`,
);

What you should see is result.text containing the model's answer and a turn count on the next line. If the agent reports no files, the tool list is the thing to check: this call passes no options, so it runs with whatever the default tool set is, and the README does not enumerate that default.

The repository has fourteen numbered example files under examples/, from 01-simple-query.ts through 14-openai-compat.ts, plus examples/web/. The test script in package.json runs 01-simple-query.ts through tsx, and test:all loops over every example, so you can read a working call for each feature instead of assembling one. The README does not document a CLI, so there is nothing to install beyond the package.

Permissions and the bypassPermissions default trap

The README's first streaming example pairs allowedTools: ["Read", "Glob"] with permissionMode: "bypassPermissions". Read and Glob do not write, so the combination is harmless there. Copy that snippet into an agent whose tool list includes a shell or a write tool and you have disabled the checks on exactly the tools that needed them. The README is truncated mid-sentence at the permissions section, so the full list of permissionMode values is not documented in the README; treat "bypassPermissions" as the only confirmed value and read examples/10-permissions.ts for the rest.

Hooks are the other half of this. A PreToolUse handler receives input.toolName and can return { block: true } to stop execution before the tool runs. Your own handler therefore runs before the call, which makes it the right place for path checks and command allowlists. PostToolUse fires after completion, and PostToolUseFailure exists for the error path. None of this is a sandbox: a hook is a function in your process, and a tool that reaches the filesystem or the network reaches it with your process's rights.

Read-only agents are expressible, and the README starts to show it in the permissions section before the text cuts off. The pattern is to restrict the tool list at construction and keep the permission mode strict, rather than to allow everything and filter afterwards.

Where this SDK is the wrong choice

Version 0.2.4 is the only version in the repository's package.json, and no releases are listed. A 0.x version number is a statement about API stability, and nothing here contradicts it. If you need a frozen interface with a deprecation policy, this is not that yet.

Subprocess isolation is the second gap, and it is a consequence of the design rather than a bug. Because the loop runs in-process, a tool that crashes the process takes your service with it. The claude-agent-sdk approach of driving a separate CLI gives you a process boundary for free. If your threat model assumes the agent's tools are untrusted, running them in your own event loop is the wrong shape, and no hook fixes that.

The third case is session continuity. The README shows multi-turn conversation through a single agent object and agent.getMessages(), which is in-memory state. There is no documented way to persist a session, resume it in another process, or read Claude Code's on-disk session files. If your product depends on resuming a conversation after a restart, the README is silent on how, and you would be building that layer yourself.

Finally, the provider heuristic. apiType auto-detection is a substring match on the model name. A self-hosted endpoint serving a renamed model will not match, and the README does not describe what happens then, only that you can set apiType explicitly.

Against claude-agent-sdk and the OpenAI Agents SDK

The README names claude-agent-sdk as the thing this replaces, and the difference is architectural rather than cosmetic. claude-agent-sdk drives the Claude Code CLI as a subprocess; this SDK implements the loop in TypeScript inside your process. That changes what you deploy (no CLI binary), how you debug (a stack trace instead of a subprocess), and how much isolation you get (none, versus a process boundary). It also changes which model providers you can reach, because the CLI path is Claude-only while this SDK adds an openai-completions route to OpenAI, DeepSeek, Qwen, Mistral or any compatible endpoint.

OpenAI's own Agents SDK is the other comparison people will make, and the related searches show it clearly: OpenAI Agents SDK TypeScript, Python, Java, tutorial. That SDK is tied to OpenAI's platform and its own primitives. This one is provider-neutral by configuration, MIT licensed, and speaks Anthropic's message format as its native shape with OpenAI compatibility layered on. The practical difference is which side you write against: with the OpenAI SDK you write to OpenAI's abstractions, with this one you write to a tool registry, hook registry and MCP client that resemble Claude Code's model.

The Go port is worth noting for polyglot teams. The README links open-agent-sdk-go as the same project in another language, which suggests the authors intend the API surface to stay aligned across both.

Licence, maintenance and what an upgrade costs

The licence is MIT, declared in package.json and in the LICENSE file at the repository root. MIT permits commercial use, modification and redistribution with the copyright notice retained. That is the whole of what the README supports; questions about your own compliance obligations belong with your legal team, not with this page.

The last push to the default branch was on 2026-07-26. There are no releases listed, so the package version in package.json, 0.2.4, is the reference point, and there is no changelog in the repository to read upgrade notes from. Upgrading means reading the diff yourself or pinning the version.

The dependency surface is small and worth counting before you adopt: @anthropic-ai/sdk, @modelcontextprotocol/sdk, zod and zod-to-json-schema, with tsx and typescript as dev dependencies. That is a lean tree for an agent runtime, and it means an upgrade of this package is mostly an upgrade of those four. The cost that is not visible from the outside is API churn. At 0.2.x, a minor bump can rename an option or change a hook payload shape, and with no published release notes the only way to find out is to run the examples after upgrading. The test:all script exists for exactly that purpose.

Editorial conclusion

Adopt it if you are building a Node 18+ service, a serverless function or a container image and you do not want a Claude Code binary in the build. Avoid it if you need a stable 1.x API surface or you depend on Claude Code's own session files, slash commands and terminal UX, because none of that is in the README. Verify first that your model name is one the auto-detection recognises, that every tool you expose is safe under permissionMode: "bypassPermissions", and that the 0.2.4 export surface covers the hooks and skills you plan to register.

Frequently asked questions

Official sources

1. codeany-ai/open-agent-sdk-typescript on GitHub
2. Issues
3. License: MIT
4. README