Robota — An adaptable foundation for AI agents

Our agents develop and advance our agents. We are building toward agents that can carry their own development forward on a dependable, adaptable foundation. VISION.md defines this direction; reliable autonomous self-evolution remains an ambition to build and demonstrate.

Today, Robota provides composable TypeScript libraries with strict types, multi-provider support, tool calling and a plugin/event architecture. The SDK and maintained interfaces belong to the same environment. @robota-sdk/agent-cli delivers a terminal agent with coding capabilities, assembled from the same neutral building blocks you can embed in your own application.

Evaluating with an AI agent? Start at llms.txt — the consumer map (minimal package set, capabilities, behavior contracts).

Install agent-core and a provider package to run an agent. This Node.js example requires Node.js 22.12 or later and an ANTHROPIC_API_KEY environment variable. Packages declare that minimum for Node installations; runtime requirements depend on the entry and host. See the providers guide for other providers and local model servers.

npm install @robota-sdk/agent-core @robota-sdk/agent-provider @anthropic-ai/sdk

Save this example as agent.mjs:

import { ConversationAgent } from '@robota-sdk/agent-core';
import { AnthropicProvider } from '@robota-sdk/agent-provider/anthropic';

const agent = new ConversationAgent({
  name: 'MyAgent',
  aiProviders: [new AnthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY })],
  defaultModel: {
    provider: 'anthropic',
    model: 'claude-sonnet-4-6',
  },
  systemMessage: 'You are a helpful assistant.',
});

const response = await agent.run('Hello!');
console.log(response);

Run node agent.mjs. The model's response appears in the console. The text depends on the model.

Runtime migration and compatibility

createZodFunctionTool validates the model's arguments against a zod schema before your function runs, and types the function's input from that schema. In addition to the packages above, install agent-tools and Zod 4:

npm install @robota-sdk/agent-tools zod@4

Save this example as weather.mjs:

import { ConversationAgent } from '@robota-sdk/agent-core';
import { AnthropicProvider } from '@robota-sdk/agent-provider/anthropic';
import { createZodFunctionTool } from '@robota-sdk/agent-tools';
import { z } from 'zod';

const getWeather = createZodFunctionTool(
  'getWeather',
  'Get the current weather for a city',
  z.object({ city: z.string() }),
  async ({ city }) => `It is sunny in ${city}.`,
);

const agent = new ConversationAgent({
  name: 'WeatherAgent',
  aiProviders: [new AnthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY })],
  defaultModel: { provider: 'anthropic', model: 'claude-sonnet-4-6' },
  tools: [getWeather],
});

const answer = await agent.run('What is the weather in Seoul?');
console.log(answer);

Run node weather.mjs to see the response.

Any OpenAI-compatible endpoint works too — AI gateways, Azure, vLLM, local servers — through the OpenAI provider's baseURL (see the providers guide).

agent-framework provides createQuery with built-in tools and permission checks. Install it with the Anthropic provider:

npm install @robota-sdk/agent-framework @robota-sdk/agent-tools @robota-sdk/agent-provider @anthropic-ai/sdk

With ANTHROPIC_API_KEY set, save this example as query.mjs. It shuts down the session when the query finishes:

import { createQuery } from '@robota-sdk/agent-framework';
import { createNodeFrameworkHost } from '@robota-sdk/agent-framework/node';
import { AnthropicProvider } from '@robota-sdk/agent-provider/anthropic';
import { createDefaultTools } from '@robota-sdk/agent-tools/defaults';

const query = createQuery({
  host: createNodeFrameworkHost({ createDefaultTools }),
  cwd: process.cwd(),
  provider: new AnthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY }),
  model: 'claude-sonnet-4-6',
});
try {
  console.log(await query('List all TypeScript files in src/'));
} finally {
  await query.shutdown();
}

Run node query.mjs to see the response.

createQuery runs in the default permission mode: with nobody to approve, a tool call that would ask for permission is denied. Without projectAccess, a query runs Restricted: it uses its tools in cwd but loads no project context, settings, memory or session files. See the SDK guide for sessions, permission modes, and InteractiveSession.

# Try the CLI built from these libraries (no install needed)
npx @robota-sdk/agent-cli

# Or install globally
npm install -g @robota-sdk/agent-cli
robota

No Node.js? Install the standalone binary (macOS / Linux / Windows — nothing else required):

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/woojubb/robota/main/scripts/install.sh | bash

# Windows PowerShell
irm https://raw.githubusercontent.com/woojubb/robota/main/scripts/install.ps1 | iex

The installer detects your OS and CPU, downloads the matching binary from the latest GitHub release, verifies its SHA-256 checksum, and installs robota to ~/.robota/bin (on Windows, %LOCALAPPDATA%\robota\bin, which it adds to your user PATH; on macOS/Linux it prints the PATH line to add if needed). To install a specific release, set PROJECT_RELEASE_VERSION to its version or tag, e.g. curl -fsSL … | PROJECT_RELEASE_VERSION=<version> bash. The macOS binaries are signed and notarized; the Windows binary is unsigned, so Windows may warn.

APIs may change. See CHANGELOG.md for upgrade notes.

macOS users: Korean/CJK IME input may crash macOS Terminal.app. Use iTerm2 instead.

• Multi-provider agents with fallback — Anthropic, OpenAI, Google Gemini, DeepSeek, Qwen and Gemma, plus OpenRouter and any OpenAI-compatible endpoint. FallbackProvider (agent-framework) moves a turn to another model when the primary is overloaded or failing; the CLI exposes it as --fallback-model. Providers guide
• Tools with runtime validation — zod-validated function tools, plus built-in coding tools (shell, read, write, edit, glob, grep and web fetch). Building agents
• Permissions, hooks and sandboxing — permission modes (plan, default, acceptEdits, bypassPermissions, auto), allow/ask/deny rules, lifecycle hooks, and an OS-level sandbox for shell commands (bubblewrap on Linux/WSL2, Seatbelt on macOS). Permissions and hooks
• Sessions and a workspace daemon — saved, resumable and forkable sessions; background sessions that outlive the terminal; and one long-lived runtime per workspace (robota daemon start) that the desktop app and the full terminal UI (robota --attach) connect to. Sessions and daemon
• MCP, both directions — connect to MCP servers (stdio or remote, including OAuth sign-in) with agent-mcp, and serve a Robota session as an MCP server with agent-transport/mcp (robota mcp serve). MCP guide
• Devices and remote control — link your own devices, send messages and files between sessions, hand a session off to another device, and co-drive a session from a browser over pairing-gated peer-to-peer WebRTC. Devices and remote
• Plugins and events — lifecycle plugins for conversation history, logging, usage, limits, performance, error handling, execution analytics and webhooks, on the same plugin contract you can implement yourself. Plugins guide

Libraries below, products on top. Everything under packages/ is universal and neutral; apps and the CLI are opinionated assemblies of the libraries. Each layer builds only on the layers below it — see ARCHITECTURE.md for the full picture.

agent-cli                              ← Product interface: terminal AI coding assistant
agent-product                          ← Product composition: profiles, capability packs, slash commands, presets, the coding pack
agent-ui-terminal · agent-ui-web       ← Terminal UI (React + Ink); browser session surface (React)
agent-transport                        ← Wire protocol and carriers: ws, http, mcp, acp, webrtc, link
  ↓
agent-framework                        ← Assembly: InteractiveSession, createQuery(), createAgentRuntime()
  ↓
agent-session · agent-executor         ← Session lifecycle; background tasks and subagents
agent-tools                            ← Tool factories and the default tool set
agent-mcp · agent-plugin               ← MCP client; lifecycle plugins
agent-provider                         ← One subpath per provider vendor
  ↓
agent-interface · agent-os               ← Type contracts shared across layers; Node host primitives
agent-core                             ← Foundation: ConversationAgent engine, provider/tool/plugin contracts, permissions

Every package below is published on npm under @robota-sdk/ and has its own version. The packages index on the docs site covers each one.

Start here (embedding):

App assembly — sessions, permissions, runtime:

Multi-agent conversation — coordinate independent agents and people in a shared conversation:

Product composition — build your own product on the same runtime:

Transports and UI — put a session behind a protocol or a screen:

Contracts — type contracts shared across layers:

Agent interface:

Full documentation lives at docs.robota.io.

• Getting Started and the Quick Start
• Building Agents
• SDK Usage
• Providers
• Permissions and Hooks
• Sessions and Daemon
• The GUI and the Desktop App
• Devices and Remote Control
• MCP
• CLI Reference
• Examples
• Packages
• Development

This repository holds the Robota agent SDK, providers, transports, the CLI, and related apps (desktop app, browser remote client, docs site, marketing site, blog).

The /workflows command uses a separately maintained workflow library bundled into the CLI.

Some workspace packages are private and never published to npm on their own:

• agent-gui-web, the GUI web app that the desktop app loads and robota --serve --open serves.
• agent-local-host, Node host authority for owner-protected local runtime state.
• agent-organization-host, an operator-owned organization broker with workload verification and durable hierarchical budgets.
• agent-provider-replay, a provider that replays a recorded session for offline tests.

pnpm install
pnpm build
pnpm test

Development needs Node.js 22 (22.14 or a later 22.x release) and pnpm 8.15.4. See CONTRIBUTING.md for the workflow, the checks a pull request must pass, and the commit format.

To package the built-in desktop app locally on Linux, install Bun and run these commands from a clean checkout:

pnpm install --frozen-lockfile
pnpm build
bun packages/agent-cli/scripts/build-bun.mjs linux-x64
pnpm --filter @robota-sdk/agent-app dist:app --linux AppImage

The AppImage is written to apps/agent-app/release/. A generated product uses the same build commands in its generated workspace. The Bun build also accepts --entry <compiled-host-entry> and --artifact-name <basename>; set PRODUCT_DESKTOP_BINARY=<compiled-binary-path> when running dist:app to bundle that binary in the desktop app.

Robota is dual-licensed under the GNU AGPL-3.0 or a commercial license. See LICENSING.md.