@arcturn/core

The Arcturn agent runtime: event loop, sessions, compaction, permissions, and sub-agents. This is the SDK — @arcturn/core is what the arcturn CLI is built on, just without a terminal in front of it.

What's in it

src/index.ts exports, among others:

• Agent / createAgent — one agent per session; createAgent wires up a JsonlSessionStore when you pass sessionDir. runLoop is the underlying event loop.
• PermissionEngine, matchRules, matchSpecifier, globToRegExp, DEFAULT_*_TOOLS, plus the path-comparison policy they use (defaultCaseInsensitivePaths, isPathLike) — path specifiers are matched with either separator and folded to the filesystem's own case rules, commands and URLs verbatim.
• compactMessages, shouldCompact, estimateTokens — compaction helpers.
• JsonlSessionStore, MemorySessionStore, and session-tree helpers (buildTree, materializeBranch, pathToLeaf, ...).
• createPlanTool, createTodoTool, createSubagentTool — built-in state/delegation tools, plus content helpers (userMessage, toolResultMessage, contentText, ...).

Everything is provider-agnostic: Agent takes an injected LLMClient (from @arcturn/types), a tool list, and optional session/permission/compaction wiring.

Install

Arcturn is not yet published to npm. Until it is, use it from a clone of the monorepo as a pnpm workspace package:

git clone https://github.com/sitharaj88/arcturn.git && cd arcturn
pnpm install && pnpm -r build

Then depend on it from another workspace package: "@arcturn/core": "workspace:*".

Usage

import { createAgent } from "@arcturn/core";
import { createClient, requireModel } from "@arcturn/ai";
import { createDefaultTools } from "@arcturn/tools";

const llm = createClient(); // resolves API keys from the environment
const { tools } = createDefaultTools({ cwd: process.cwd() });

const agent = createAgent({
  llm,
  model: requireModel("anthropic/claude-sonnet-4-5"),
  systemPrompt: "You are a focused, careful coding agent.",
  tools,
  cwd: process.cwd(),
  sessionDir: ".arcturn/sessions", // omit for an unpersisted, in-memory agent
  permissions: { mode: "default" },
});

await agent.prompt("Add input validation to the signup handler");
console.log(agent.finalText());

agent.prompt() resolves once the model stops calling tools, is aborted, or errors — it never rejects on a runtime failure; subscribe to its event stream to observe failures.

Docs

• Embedding with the SDK — mental model and package overview.
• Agent options / Events / Permissions / Sessions
• Advanced: sub-agents, MCP, VCR, hooks

License

Apache-2.0 — see LICENSE.

👤 Author

Sitharaj Seenivasan

• 🌐 Website: sitharaj.in
• 💼 LinkedIn: sitharaj08
• 💻 GitHub: sitharaj88

☕ Support

If this project helps you, consider buying me a coffee — it keeps the work going.

📄 License

Licensed under the Apache License 2.0. © 2026 Sitharaj Seenivasan.