Build an agent into your TypeScript application with the SDK. Or work in your terminal with the coding CLI built from the same public components. Configure a model endpoint, tools, permissions, and sessions for the task at hand.
Public packages · Node.js 22.12 or later · Bring a model endpoint
Our direction: agents that can reliably advance the systems they are built on.
01 / The shared foundation
The agent framework assembles sessions, tools, and permission checks. The coding CLI is one maintained interface built on it. You can use the framework from your own Node.js application.
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 static example requires a running OpenAI-compatible server and a model ID loaded there. The local port is illustrative. The 'local' API key is a placeholder for servers without authentication; replace it with your server's credential if required. A published-package loopback check verified the SDK call and cleanup; no real model answer is shown.
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, type a normal prompt:
Reply with one sentence.
Look for a text reply from the selected model; its wording and quality depend on that 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. Move to 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, configure a provider and model with a hosted key or running local endpoint, then decide whether to trust the workspace before project context is loaded.
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 / Everything in the foundation
Every capability below is part of the public SDK packages or the coding CLI built from them. Each card names the package, class, flag, or command to look for and links to the guide that owns the details.
Choose the model per task, and keep a turn going when one fails.
Provider packages for Anthropic, OpenAI, Google Gemini, DeepSeek, Qwen and Gemma, plus any OpenAI-compatible endpoint (gateways, Azure, vLLM, local servers) through baseURL.
GuideFallbackProvider moves a turn to another model when the primary is overloaded or failing. The CLI adds per-run model effort and an advisor model the agent can consult.
GuidePoint a provider profile at an Ollama, LM Studio or other OpenAI-compatible server on your own machine or network. You run the model; enabled tools decide what else leaves it.
GuideThe Gemini provider includes image generation, and a separate ByteDance (ModelArk) provider generates video. The video provider is not a chat model for an agent.
GuideTyped tools, with every call checked 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.
GuideEvery tool call passes deny, ask and allow rules, then one of five permission modes. A few destructive actions are never approved automatically in any mode.
GuideRun commands on tool, prompt and session events. PreToolUse can block a call; other hooks log, audit, 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 a trusted workspace. An untrusted repository refuses unattended runs or starts them Restricted.
GuideLong-running work that survives the terminal and splits across agents.
Continue, resume, rename or fork a conversation. Context is tracked and compacted automatically; the SDK host supplies the session store it wants.
GuideSupervised sessions keep running after the terminal closes. One workspace daemon serves several terminals and the desktop app from a single runtime.
GuideDelegate work to subagents with their own context and tools, in process or in child processes, and manage queued and running jobs from one place.
GuideRepeat a prompt on a cadence, wake the agent later or when command output matches, and keep a session read-only until you approve its plan.
GuideRewind or fork from edit checkpoints, keep approved facts across sessions with opt-in memory, inspect context use, and set a monthly cost budget.
Guide/workflows designs a workflow from a description with the active model, saves it as JSON in the workspace, validates it and runs it, optionally detached.
GuideCoordinate independent agents and people in one shared transcript: select turns, run parallel groups, and plug a Robota session in as a participant or selector.
GuideBring in servers, skills, and plugins without forking the runtime.
Connect to stdio or remote MCP servers, including OAuth sign-in, after explicit approval. Or serve a session as an MCP server over stdio or authenticated HTTP.
GuideMarkdown skills and commands become slash commands; agent definitions describe subagents. They are discovered 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.
GuideGrant a verified outside service permission to send text events into a running terminal session, and list or revoke those grants from the session.
GuideThe same session behind a terminal, a script, a browser, or a 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 one prompt from a script or pipe, get text, JSON or streaming JSON, request schema-shaped output, or work toward a goal over several turns.
GuideServe the GUI for the current workspace on loopback and open it in a browser. The desktop app in the repository shows the same GUI over the workspace daemon.
GuideLet other services submit turns and stream results as server-sent events, behind a bearer token or as an OAuth resource server. WebSocket, HTTP, MCP and WebRTC carriers share one wire protocol.
GuideMessage other live sessions, hand a conversation to another session or device, link your own devices, and co-drive a session from a paired browser over peer-to-peer WebRTC.
GuideRun print mode in a workflow step to review a pull request or answer a task, and gate a pipeline on an evals-as-code score.
GuideUse the layers directly, or assemble a product of your own on them.
ConversationAgent runs and streams turns with history, tool calling, structured output and plugins. It is the minimal set: core plus one provider.
GuidecreateQuery runs one-shot queries with built-in tools and permissions; InteractiveSession drives a full conversation; createAgentRuntime assembles a host runtime.
GuidePut the framework behind an SSE or WebSocket server with a full event stream per session, resume a saved session per bot channel, or run a stateless runtime that persists nothing.
GuideTransportRegistry runs one agent definition behind several transports, with their enabled state kept in a settings file; there is no separate gateway process.
GuideassembleProduct builds a product from a declarative profile. Capability packs, slash-command modules, presets and output styles are the parts the coding CLI uses.
GuideDepend on the published CLI package and own the entry, identity, assets and packaging: a product-bound CLI host, desktop-host helpers for an Electron app, and native binary builds.
Package READMECheck settings, provider, trust and plugins in one report; summarize local token use and cost without sending content; export content-free metrics; run evals as code.
Guide04 / The coding CLI
The CLI is the maintained interface on the shared foundation. The same runtime powers the terminal UI, scripts, background sessions, the 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 exits with a code your script can check. A goal run keeps working over several 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 serveInside a session: message peers, hand off a conversation, link devices, 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 first, then the permission mode. Set the mode per run or change it inside a 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 asks in bypassPermissions. Removing the root, home or working directory, and writing into .git or tool configuration, are never approved automatically.
In default mode, a request that needs approval is denied when nobody answers it, unless your host supplies a permission handler.
Combine permission rules with the OS sandbox so an approved command still runs with limited file and network access.
06 / Architecture
Everything under packages/ is neutral and reusable; the CLI and apps are opinionated assemblies of those libraries. Each layer builds 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.
Put a session behind a protocol or a screen.
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-cliKeep 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 / Know the fit
A public codebase lets you inspect how the SDK and CLI are assembled. Start with the package and source that match your task.
Explore the showcaseThe code is offered under AGPL-3.0, with a commercial licensing path for uses that need different terms. Review the license for your distribution or service.
The SDK and CLI do not include model inference. A hosted provider can charge for usage; local inference has its own compute and operating costs.
The coding CLI is the maintained example of these public components composed into a developer tool. Browse its source and the current showcase.
09 / Direction, not a guarantee
That is the long-term direction of the project. Today, the usable foundation is an SDK and coding CLI with explicit providers, tools, and host decisions. Reliable autonomous self-development must be demonstrated through actual outcomes as the system evolves.
10 / Before you start
No. Import the agent framework into your own Node.js host and inject a provider. The CLI is one complete interface built from public components.
You need a provider endpoint and a suitable model. A local OpenAI-compatible example requires its server and model to be running; a hosted provider needs its own credentials and terms.
No. A simple createQuery call is not a durable session. Supply a session store when your host needs save and resume behavior.
Review project trust and permission modes. In default mode, an unattended request for approval is denied unless your host provides a permission handler.
Not yet. The packages are 3.0.0 beta releases and APIs may change before a stable release; the changelog records upgrade notes.
Choose the embeddable query or set up the coding CLI. Both paths begin with the provider and access decisions you control.