Agent

First run from your terminal#

Install the CLI, log in, then start the agent. Login selects your workspace automatically and the agent inherits it, no workspace id to copy, no extra setup.

# 1. Install (see CLI → Installation for details)
uv tool install stimulir

# 2. Log in, this selects your workspace automatically
stimulir login

# 3. Start the agent, bare `stimulir`, or with an opening task
stimulir
stimulir agent "Add a /health endpoint and wire it into the router"

From there it works like a coding agent in your shell: it streams its reasoning, proposes tool calls, and runs them on your machine after you approve. A typical first exchange looks like:

$ stimulir agent "What changed in the last commit?"

stimulir › I'll look at the latest commit.

  ⏵ bash: git show --stat HEAD
    Run this command? [y]es / [n]o / [a]lways  y

  … 3 files changed, 47 insertions(+), 12 deletions(-)

stimulir › The last commit refactored the auth middleware, it splits
token validation into its own module and adds tests. Want the details?

Ways to start#

Run stimulir with no subcommand in a terminal, or stimulir agent with an optional opening prompt, to launch an interactive agent session:

# Interactive REPL, drop into an agent session
stimulir

# Same thing, with an opening prompt
stimulir agent "Add a health check endpoint and wire it into the router"

The agent uses the same login and active workspace as the rest of the CLI. Run login first, it selects your workspace for you.

How it runs#

The agent always runs connected: the server-side agent (Pi) runs the reasoning loop in the cloud and emits tool intents; this CLI executes those intents, bash commands, file reads and writes, globs, on your local machine, prompting you for approval. The transcript is stored server-side, so every session shows up in the Engineering workspace with full traces.

# Server runs the loop, your machine executes tool calls
stimulir agent "Refactor the auth module"

# Resume an existing session by key
stimulir agent --session <session-key>

Attach as a local executor#

A session started in the web or desktop app can hand local execution to your terminal. In the app's chat composer, open the "Continue in: Local" dropdown, then attach this machine:

# List recent sessions and pick one to attach to
stimulir attach

# Attach directly to a known session
stimulir attach <session-key>

attach is pure executor mode, there is no REPL. The agent keeps running server-side and its tool calls execute locally, with approval prompts, until you press Ctrl-C. With no session key, the CLI lists recent sessions for you to choose from.

One session, two bodies#

The conversation and transcript live server-side; execution is a separate, swappable body. The same session can be driven by:

• Cloud execution, tool calls run in a managed sandbox in the cloud.
• Local execution, tool calls run on your machine, via the connected CLI or stimulir attach.

Because the transcript is shared, you can switch a session between Cloud and Local mid-conversation in the web app, or pick it up from your terminal, without losing context. Whichever body is active, the work is appended to the one session.

Local execution & approvals#

When tool calls execute locally, approvals always happen on your machine. Each intent, a shell command, a file write, is shown before it runs. Your local execution power is exactly whatever your own machine and login allow; nothing runs that you have not approved.

• Approve once, run a single intent.
• Always allow, auto-approve a category of intents for the rest of the session.
• Destructive commands always prompt, even under "always allow", commands that delete or overwrite are re-confirmed every time.

Local-executor protocol#

Connected and attach modes speak a small bridge protocol over the Console platform API at https://api.stimulir.com. It is documented here so an advanced user could build their own executor. Endpoints authenticate with your session token and the X-Business-Profile-Id header, the same as the rest of the platform API.

The attach → stream → intent → result cycle

• attach, register this machine as the local executor for the session.
• stream, open a Server-Sent Events stream of the running turn.
• results, post the output of a tool intent the executor ran locally.
• messages, send a new user message into the session (used by the connected REPL).

The executor attaches, opens the stream, runs each tool_intent it receives locally (after approval), posts the result back, and the server continues the turn, repeating until the turn completes.

SSE frame types

The stream endpoint emits these event frames:

• hello, stream is established.
• ping, keep-alive heartbeat.
• assistant_delta, incremental assistant output.
• tool_intent, a tool call for the local executor to run.
• turn_complete, the turn finished.
• turn_error, the turn failed.

Next#

See the Command Reference for the full flag list, or Installation to set up login.