Robota provides a TypeScript SDK for AI agents and a coding CLI built from the same public components. Build agents into your app or use the CLI in your terminal. Configure a model endpoint, tools, permissions, and sessions for your task.
Public packages · Node.js 22.12 or later · Model endpoint required
We aim to build agents that can reliably improve the systems they are built on.
01 / The shared foundation
The agent framework brings together sessions, tools, and permission checks. The coding CLI is a maintained interface built on that framework. You can also use the framework in your own Node.js app.
npm install @robota-sdk/agent-framework @robota-sdk/agent-provider-openaiimport { createQuery } from '@robota-sdk/agent-framework';
import { OpenAIProvider } from '@robota-sdk/agent-provider-openai';
const model = 'your-loaded-model-id';
const query = createQuery({
provider: new OpenAIProvider({
apiKey: 'local',
baseURL: 'http://127.0.0.1:1234/v1',
}),
model,
});
try {
console.log(await query('Reply with one sentence.'));
} finally {
await query.shutdown();
}This example requires a running OpenAI-compatible server and the ID of a model loaded on it. The local port is an example. The 'local' API key is a placeholder for a server without authentication; replace it with your server's credential if needed. A local test of the published packages verified the SDK call and cleanup. The example does not show a real model response.
Inspect the framework source02 / Coding CLI
npx @robota-sdk/agent-cliYou need Node.js 22.12+ and an API key or a running local model server. Provider costs and policies depend on the endpoint you choose.
After configuring a provider and model, enter a prompt:
Reply with one sentence.
The selected model returns a text reply. Its wording and quality depend on the model. Before asking about project files, decide whether to trust the workspace.
Read CLI setup02 / Choose a first task
Install the framework and a provider adapter, then call createQuery from a Node.js script. Use InteractiveSession when your own UI needs a longer conversation.
You need Node.js 22.12+, a configured provider endpoint, and a model ID. The example on this page uses a running local OpenAI-compatible server.
Run the CLI and configure a provider and model using a hosted API key or a running local endpoint. Decide whether to trust the workspace before the CLI loads project context.
You need Node.js 22.12+ and an API key or a running local model server. Provider costs and policies depend on the endpoint you choose.
03 / SDK and CLI capabilities
These capabilities are available in the public SDK packages or the coding CLI built from them. Each card lists the relevant packages, classes, flags, or commands and links to the detailed guide.
Choose a model for each task and continue the turn with another model if one fails.
Use provider packages for Anthropic, OpenAI, Google Gemini, DeepSeek, Qwen, and Gemma. Set baseURL to connect to other OpenAI-compatible endpoints, including gateways, Azure, vLLM, and local servers.
GuideFallbackProvider switches the turn to another model if the primary model is overloaded or fails. In the CLI, you can set model effort for each run and configure an advisor model for the agent to consult.
GuideConfigure a provider profile to use Ollama, LM Studio, or another OpenAI-compatible server on your computer or network. You run the model. The tools you enable determine what other data leaves your system.
GuideUse the Gemini provider to generate images and the separate ByteDance (ModelArk) provider to generate video. The video provider cannot serve as an agent's chat model.
GuideUse typed tools and check every call before it runs.
createZodFunctionTool checks model arguments against a zod schema before your function runs. Built-in coding tools cover files, search, shell, web fetch and web search.
GuideEach tool call is checked against deny, ask, and allow rules, then evaluated under one of five permission modes. Some destructive actions are never approved automatically, regardless of the mode.
GuideRun commands when tool, prompt, or session events occur. PreToolUse can block a call. Other hooks can record logs, support audits, or add context to the next prompt.
GuideShell commands can run inside bubblewrap on Linux and WSL2 or Seatbelt on macOS, limiting what a command can read, write, or reach on the network.
GuideProject instructions such as AGENTS.md and CLAUDE.md load only in trusted workspaces. For an untrusted repository, the CLI refuses unattended runs or starts in Restricted mode.
GuideKeep work running after you close the terminal, or divide it among agents.
Continue, resume, rename, or fork a conversation. Context usage is tracked and compacted automatically. The SDK host chooses and supplies the session store.
GuideSupervised sessions continue running after you close the terminal. A single workspace daemon provides one runtime for multiple terminals and the desktop app.
GuideDelegate work to subagents with their own context and tools. Run them in the same process or in child processes, and manage queued and running jobs in one place.
GuideRepeat a prompt at a set interval, or wake the agent later or when command output matches a condition. Keep the session read-only until you approve its plan.
GuideRewind to an edit checkpoint or fork from it. Use opt-in memory to retain approved facts across sessions, inspect context usage, and set a monthly cost limit.
GuideUse /workflows to turn a description into a workflow with the active model. Save it as JSON in the workspace, validate it, and run it, with the option to run detached.
GuideBring independent agents and people into a shared transcript. Choose the turn order, run groups in parallel, and use a Robota session as a participant or selector.
GuideBring in servers, skills, and plugins without forking the runtime.
After explicit approval, connect to stdio or remote MCP servers, including those that use OAuth sign-in. You can also expose a session as an MCP server over stdio or authenticated HTTP.
GuideDefine skills and commands in Markdown to make them available as slash commands. Agent definitions describe subagents. The CLI discovers these files in the project and your home directory.
GuideInstall plugins that bundle skills, hooks, themes and MCP servers. SDK lifecycle plugins cover history, logging, usage, limits, errors, analytics and webhooks.
GuideAllow a verified external service to send text events to a running terminal session. View or revoke those permissions from within the session.
GuideUse the same session from a terminal, script, browser, or protocol.
An interactive terminal app with a command menu, prompt history search, rebindable keys, file attachments with @path, and a plain-text screen-reader mode.
GuideRun a prompt from a script or pipe and receive text, JSON, or streaming JSON. Request output that follows a schema, or let the agent work toward a goal over multiple turns.
GuideServe the current workspace GUI on a loopback address and open it in a browser. The desktop app in the repository displays the same GUI through the workspace daemon.
GuideLet other services submit turns and receive results as server-sent events, protected by a bearer token or OAuth resource server. WebSocket, HTTP, MCP, and WebRTC transports use the same wire protocol.
GuideMessage other running sessions, hand a conversation to another session or device, and link your devices. Pair a browser to control a session together over peer-to-peer WebRTC.
GuideUse print mode in a workflow step to review a pull request or respond to a task. Gate the pipeline on an evals-as-code score.
GuideUse individual layers directly, or combine them into your own product.
ConversationAgent runs and streams turns with conversation history, tool calling, structured output, and plugins. The minimum setup is core and one provider.
GuideUse createQuery for a single query with built-in tools and permissions, InteractiveSession for a full conversation, and createAgentRuntime to assemble a host runtime.
GuideUse the framework in an SSE or WebSocket server with a full event stream for each session. Resume a saved session for each bot channel, or use a stateless runtime that stores nothing.
GuideTransportRegistry runs one agent definition across multiple transports. A settings file records which transports are enabled. No separate gateway process is needed.
GuideBuild a product from a declarative profile with assembleProduct. Use the same capability packs, slash-command modules, presets, and output styles as the coding CLI.
GuideUse the published CLI package while controlling your product's entry point, identity, assets, and packaging. It provides a product-bound CLI host, desktop-host helpers for Electron, and native binary builds.
Package READMECheck settings, providers, workspace trust, and plugins in one report. Summarize local token usage and cost without sending content, export metrics without conversation content, and run evaluations as code.
Guide04 / The coding CLI
The coding CLI is a maintained interface built on the shared framework. The same runtime supports the terminal UI, scripts, background sessions, browser GUI, and other services.
Start a session, choose a permission mode, or switch to a screen-reader mode.
In a shell
robotarobota --permission-mode acceptEditsrobota --screen-readerPrint mode returns an exit code your script can check. Goal runs continue working over multiple turns.
In a shell
robota -p "List the TypeScript files in src/"robota -p "Summarize this repository" --output-format jsoncat task.md | robota -probota --goal "make the failing tests pass"Resume earlier work, run supervised sessions in the background, and share one daemon.
In a shell
robota -crobota -r <id-or-name>robota session start --background --name nightlyrobota daemon startrobota --attachOpen the browser GUI, accept HTTP clients with a bearer token, or act as an MCP server.
In a shell
robota --serve --openPRODUCT_HTTP_TOKEN="$(openssl rand -hex 32)" robota --serve --http-port 8787robota mcp serveFrom a session, message other sessions, hand off a conversation, link devices, or pair a browser.
Inside a session
/peers/peers send <session-id> <message>/handoff <session-id>/devices init/remote-control enableDiagnose configuration, summarize local usage, check for updates, and run evals.
In a shell
robota doctorrobota usage --period 30drobota --check-updaterobota eval <definition.mjs>05 / Permissions and safety
Deny, ask, and allow rules are checked before the permission mode is applied. Choose a mode when you start a run or change it during the session.
| Mode | Reads | File edits | Shell commands |
|---|---|---|---|
plan | Yes | Refused | Refused, except built-in read-only commands |
default | Yes | Asks | Asks |
acceptEdits | Yes | Yes | Asks |
auto | Yes | Yes | Decided by a model classifier |
bypassPermissions | Yes | Yes | Yes |
{
"permissions": {
"allow": ["Bash(pnpm *)", "Bash(git status)"],
"ask": ["Bash(git push *)"],
"deny": ["Bash(rm -rf *)", "Write(.env)"]
}
}An ask rule still requires approval in bypassPermissions mode. Deleting the root, home, or working directory and writing to .git or tool configuration files are never approved automatically.
In default mode, a request that needs approval is denied if nobody responds, unless your host provides a permission handler.
Combine permission rules with the OS sandbox so an approved command still runs with limited file and network access.
06 / Architecture
The libraries under packages/ are neutral and reusable. The CLI and apps combine them for specific purposes. Each layer depends only on the layers below it.
Every package is published on npm under @robota-sdk/ and shares one version. Start with the smallest set your task needs.
The engine, one provider per vendor, and validated tools.
Sessions, permissions, background work, MCP, plugins and analysis.
Shared transcripts for independent agents and people.
Build your own product on the same runtime.
Connect a session to a protocol or user interface.
Type-only packages shared across layers.
The coding CLI, published as a self-contained bundle.
07 / Install
Published packages need Node.js 22.12 or later. The standalone binary needs nothing else installed.
Fetch and start the latest CLI with npx.
npx @robota-sdk/agent-cliInstall the CLI on your PATH with npm.
npm install -g @robota-sdk/agent-cli
robotaThe installer picks the binary for your OS and CPU from the latest release and verifies its SHA-256 checksum. Binaries are unsigned, so macOS and Windows may warn.
curl -fsSL https://raw.githubusercontent.com/woojubb/robota/main/scripts/install.sh | bashirm https://raw.githubusercontent.com/woojubb/robota/main/scripts/install.ps1 | iexThe engine plus one provider package. Add agent-tools when the agent calls tools.
npm install @robota-sdk/agent-core @robota-sdk/agent-provider-anthropic08 / Source and licensing
The public source shows how the SDK and CLI are assembled. Start with the packages and code relevant to your task.
Explore the showcaseThe code is available under AGPL-3.0. A commercial license is also available if you need different terms. Review the license conditions for your distribution or service.
The SDK and CLI do not include model inference. Hosted providers may charge for usage. Running models locally also requires compute and operating costs.
The coding CLI is a maintained developer tool built from the public components. Explore its source and the current showcase.
09 / Our long-term goal
This is the project's long-term goal, rather than a promised capability. Today, the SDK and coding CLI let you choose providers, tools, and host behavior explicitly. Reliable autonomous self-development still needs to be demonstrated through actual results as the system evolves.
10 / Before you start
No. Import the agent framework into your own Node.js host and supply a provider. The CLI is one complete interface built from the public components.
You need a provider endpoint and a suitable model. The local OpenAI-compatible example requires a running server with a loaded model. For a hosted provider, use its credentials and follow its terms.
No. A createQuery call alone does not create a persistent session. Supply a session store if your host needs to save and resume conversations.
Review workspace trust and permission modes. In default mode, unattended runs deny requests that need approval unless your host supplies a permission handler.
Not yet. The packages are 3.0.0 beta releases, and the API may change before a stable release. See the changelog for upgrade notes.
Add a query to your app or set up the coding CLI. In either case, you choose the provider and access permissions.