Agent

First run from your terminal#

Install the CLI, log in, pick a workspace, then start the agent. The agent inherits that login and active workspace — no extra setup.

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

# 2. Log in and select the workspace the agent should act in
stimulir login
stimulir workspace use <workspace-id>

# 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 and pick a workspace first.

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 and workspaces.