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. Published packages require Node.js
22.12 or later. This example uses Anthropic and requires an ANTHROPIC_API_KEY environment
variable. See the providers guide for other providers and local
model servers.
npm install @robota-sdk/agent-core @robota-sdk/agent-provider-anthropicSave 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 3:
npm install @robota-sdk/agent-tools zod@3Save 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-provider-anthropicWith 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 { AnthropicProvider } from '@robota-sdk/agent-provider-anthropic';
const query = createQuery({
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. 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
robotaNo 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 | iexThe 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 PRODUCT_VERSION to its tag, e.g. curl -fsSL … | PRODUCT_VERSION=v<version> bash. Binaries are
unsigned — macOS and Windows may warn.
Beta: Robota is currently
3.0.0-beta. APIs may change before the stable 3.0.0 release. 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 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, web fetch and search). 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 withagent-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 · pack-coding ← Product composition: profiles and capability packs
agent-command · agent-preset ← Slash commands, presets and output styles
agent-ui-terminal ← Terminal UI (React + Ink)
agent-transport-{ws,http,mcp,webrtc} ← Carriers over the shared wire protocol in agent-transport
↓
agent-framework ← Assembly: InteractiveSession, createQuery(), createAgentRuntime()
↓
agent-session · agent-executor ← Session lifecycle; background tasks and subagents
agent-tools · agent-tool-defaults ← Tool factories and the default tool set
agent-mcp · agent-plugin ← MCP client; lifecycle plugins
agent-provider-* ← One provider package per vendor
↓
agent-interface-* ← Type-only contracts shared across layers
agent-core ← Foundation: ConversationAgent engine, provider/tool/plugin contracts, permissions
Every package below is published on npm under @robota-sdk/, and all of them share one version.
The packages index on the docs site covers each one.
Start here (embedding):
| Package | Description |
|---|---|
@robota-sdk/agent-core |
ConversationAgent: run/runStream, history, tool calling, structured output, plugins |
@robota-sdk/agent-provider-anthropic |
Anthropic (Claude) provider |
@robota-sdk/agent-provider-openai |
OpenAI provider; any OpenAI-compatible endpoint through baseURL |
@robota-sdk/agent-provider-openai-compatible |
DeepSeek, Qwen and Gemma providers, and the shared OpenAI-compatible protocol |
@robota-sdk/agent-provider-gemini |
Google Gemini provider, including image generation |
@robota-sdk/agent-provider-bytedance |
ByteDance (ModelArk) video-generation provider |
@robota-sdk/agent-tools |
Zod-validated function tools, built-in tool factories, sandbox ports |
App assembly — sessions, permissions, runtime:
| Package | Description |
|---|---|
@robota-sdk/agent-framework |
Assembly layer: InteractiveSession, createQuery(), createAgentRuntime(), config/context loading |
@robota-sdk/agent-session |
Session: permission-gated tool execution, hooks, context tracking, compaction, persistence |
@robota-sdk/agent-executor |
Background task lifecycle, queueing and cancellation; subagent job orchestration |
@robota-sdk/agent-subagent-runner |
Optional runner that executes subagents in child processes |
@robota-sdk/agent-tool-defaults |
The SDK's default tool set (createDefaultTools) |
@robota-sdk/agent-builtin-providers |
Built-in provider definitions (createDefaultProviderDefinitions) and default role models |
@robota-sdk/agent-mcp |
MCP client: server definitions, activation, connections, tool catalog, OAuth sign-in |
@robota-sdk/agent-plugin |
Lifecycle plugins: history, logging, usage, limits, performance, errors, analytics, webhooks |
@robota-sdk/agent-session-analytics |
Session-log timing and usage analysis and reports |
@robota-sdk/agent-telemetry-otel |
OpenTelemetry spans and GenAI metrics for agent runs and live prompt traces, GenAI or agent.* names |
@robota-sdk/agent-process |
Child-process tree termination (killProcessTree) |
@robota-sdk/agent-file-authority |
Bounded, root-relative file reads for Node.js |
Multi-agent conversation — coordinate independent agents and people in a shared conversation:
| Package | Description |
|---|---|
@robota-sdk/agent-roundtable |
Selects turns, runs parallel groups, publishes to a shared transcript; no model, no provider |
@robota-sdk/agent-roundtable-robota |
Runs a Robota Session or plain Robota agent as a roundtable participant or selector |
Product composition — build your own product on the same runtime:
| Package | Description |
|---|---|
@robota-sdk/agent-product |
assembleProduct(profile): a product from a declarative profile |
@robota-sdk/agent-capability-pack |
ICapabilityPack contract and mergeCapabilityPacks |
@robota-sdk/pack-coding |
The coding capability pack (createCodingPack): coding tools, commands, subagents |
@robota-sdk/agent-command |
Slash-command modules (/help, /permissions, /mcp, /rewind, …) |
@robota-sdk/agent-preset |
Presets (named bundles of framework options) and output styles |
Transports and UI — put a session behind a protocol or a screen:
| Package | Description |
|---|---|
@robota-sdk/agent-transport |
Carrier-neutral wire protocol, session dispatch and delivery (./client, ./node) |
@robota-sdk/agent-transport-ws |
WebSocket carrier |
@robota-sdk/agent-transport-http |
HTTP carrier (Hono) |
@robota-sdk/agent-transport-mcp |
Serve a session as an MCP server: stdio, loopback HTTP, OAuth-authorized remote HTTP |
@robota-sdk/agent-transport-acp |
Serve a session to an editor as an Agent Client Protocol agent over stdio |
@robota-sdk/agent-transport-webrtc |
Peer-to-peer WebRTC transport for remote control and the device mesh |
@robota-sdk/agent-remote-pairing |
Pairing and DTLS-fingerprint channel binding for peer-to-peer connections |
@robota-sdk/agent-ui-terminal |
Terminal UI (React + Ink) |
Contracts — type-only packages shared across layers:
| Package | Description |
|---|---|
@robota-sdk/agent-interface-session |
Interactive sessions, interaction channels, events, turns, records |
@robota-sdk/agent-interface-session-mobility |
Peer messaging and session handoff between sessions and devices |
@robota-sdk/agent-interface-command |
Commands, command results, plugin adapters, capability descriptors |
@robota-sdk/agent-interface-execution |
Background tasks, job groups, subagent jobs, execution workspaces |
@robota-sdk/agent-interface-analytics |
Usage snapshots, per-source totals, run-trace timelines |
@robota-sdk/agent-interface-transport |
Transport adapters, admission, access tokens, external events |
@robota-sdk/agent-interface-tui |
Terminal UI interaction contracts |
Agent interface:
| Package | Description |
|---|---|
@robota-sdk/agent-cli |
robota: interactive terminal AI coding assistant, published as a self-contained bundle |
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:
- The GUI packages (
agent-ui-web,agent-gui-web,agent-transport-webrtc-web) behind the desktop app,robota --serve --open, and the browser remote client. agent-provider-replay, a provider that replays a recorded session for offline tests.
pnpm install
pnpm build
pnpm testDevelopment 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 AppImageThe 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.