CLI

Installing the package also installs the lousho command. It scaffolds projects, checks your setup, runs an agent locally, serves it over MCP, runs evals, builds a deployable artifact and launches the Agent Forge dashboard. Run it with npx lousho <command> inside a project that has the SDK installed.

Command	What it does	Details
`lousho init [dir]`	Scaffold a project: an agent with an example tool, an offline test, `.env.example`; installs dependencies and runs `git init`.	Installation
`lousho doctor [spec] [--json]`	Check Node, peer packages, provider keys, and optionally a spec file; prints a fix for every problem.	Installation
`lousho dev <path>`	Local dev server for a spec file, an agent directory or a TS agent: chat UI with a session per tab and streamed events, hot reload on save.	Below
`lousho chat <path>`	Terminal REPL for a spec file, an agent directory or a TS agent: streams replies, shows tool calls, asks for approvals and questions.	Below
`lousho acp <path>`	Serve a spec file, an agent directory or a TS agent to an editor (Zed and other ACP clients) over the Agent Client Protocol on stdio.	ACP
`lousho add <name>`	Install a tool, skill, channel, schedule or memory slot from a JSON registry into an agent directory, after showing its permission manifest.	Registry
`lousho mcp <spec>`	Serve the agent as an MCP server (stdio, or HTTP with `--http`).	Configuration
`lousho eval [globs...]`	Run `*.eval.ts` files under vitest; print a summary and write JUnit/JSON reports.	Evals
`lousho build --target=<t> --agent=<spec>`	Build a deployable Node server, Docker image or Cloudflare Worker.	Deployment
`lousho studio`	Launch Agent Forge, the visual dashboard, on one local port.	Agent Forge

Every command that takes a <spec> reads an agent spec file (.yaml, .yml or .json, see Configuration).

Usage

lousho init [dir] [--provider P] [--template T] [--yes] [--no-install] [--no-git] [--package-manager PM] [--force]
lousho dev <spec.yaml|spec.json|agent-dir|agent.ts> [--port N] [--host H] [--no-schedules]
lousho chat <spec.yaml|spec.json|agent-dir|agent.ts> [--model provider/model] [--session id] [--store sqlite:<file>]
lousho acp <spec.yaml|spec.json|agent-dir|agent.ts> [--model provider/model]
lousho add <name> [--registry <url-or-path>] [--dir <agent-dir>] [--yes] [--overwrite] [--dry-run]    (or --list)
lousho build <agent-dir|spec> --target=<name> [--out=<dir>]    (or --agent=<path>)
lousho studio [--port N] [--host H] [--prod|--dev]
lousho mcp <agent.yaml|json> [--http --port N --host H]
lousho doctor [agent.yaml|json] [--json]
lousho eval [globs...] [--tag t] [--junit path] [--json path] [--strict] [--judge] [--record | --replay | --drift [--drift-usage]] [--url <base> [--token <bearer>]]

Every command parses its flags the same way (Node’s parseArgs, strict): --flag value and --flag=value both work, the last of a repeated flag wins (--tag accumulates), -- ends the flags, and -h / --help prints the command’s usage and exits 0. An unknown flag, a flag without its value (it never takes the next flag as its value) or an extra argument fails with LOUSHO_CONFIG_INVALID and the usage line. A value that starts with - needs the = form: --model=-x. npm create lousho-agent my-agent runs lousho init with the same arguments. To scaffold against an unreleased build of the SDK, pass --sdk-path (see Installing from a local build).

`lousho dev`

npx lousho dev agent.yaml                  # a spec file
npx lousho dev ./my-agent                  # an agent directory
npx lousho dev src/agent.ts                # a TypeScript (or JavaScript) module
npx lousho dev agent.yaml --port 4000 --host 0.0.0.0
npx lousho dev ./my-agent --no-schedules   # do not fire the directory's cron schedules

For an agent directory, channels/ are mounted under /channels and schedules/ are started (and both are swapped on reload, the old schedules stopped first); --no-schedules starts none. See Agent directories. Serves a chat UI on GET /, GET /health, GET /dev/status and the chat endpoints below (1MB body limit). What <path> is follows from the path:

Path	Loaded with
`.yaml`, `.yml`, `.json`	`loadSpec()` + `specToAgent()` (Configuration)
a directory	`loadAgentDir()` (Agent directories)
`.ts`, `.mts`, `.js`, `.mjs`, `.cjs`	the module’s default export, or its `agent` export: a `SimpleAgent` (what `createAgent()` returns) or a `createAgent()` options object

Any other extension, a missing path, or a module with no agent export fails with a coded error (LOUSHO_SPEC_UNSUPPORTED_FORMAT, LOUSHO_CONFIG_INVALID) and its fix. A .ts module is imported by the running Node (22.19 or later strips types, so relative imports need their file extension); use .js for code that needs a transpiler. Chat sessions. The chat UI keeps one session per browser tab (its id is in sessionStorage; “New session” starts another) and shows the streamed turn: text as it arrives, tool calls with their arguments and results, errors, and tokens and cost from run.done. A tool call that needs approval shows Approve / Reject buttons; an ask_question call shows its options as buttons plus a free-text field. The same endpoints work from curl or your own page:

Endpoint	What it does
`POST /chat` `{ "sessionId", "input" }`	Runs `agent.session({ id: sessionId }).stream(input)` and streams the turn as SSE: one `data: <AgentEvent JSON>` per event (Streaming), then `event: done`. History is kept per `sessionId` (1-128 characters of `A-Za-z0-9_-`).
`GET /chat/:sessionId`	The session’s transcript: `{ sessionId, messages, pending }`; `pending` is `{ status, approvalId? }` while a turn waits on an approval, else `null`.
`POST /chat/:sessionId/approvals/:id` `{ "approved", "note"? }` or `{ "answer" }`	Decides the pending approval (`agent.approvals.resolve()`), or answers a question (`agent.approvals.answer()`), and streams the continued turn as SSE. It can pause again with another `approval.requested`. `404` when `id` is not pending.
`POST /chat` `{ "message" }`	Deprecated: no session, no streaming. Returns the agent’s `ExecutionResult` as JSON, with a `Deprecation: true` header.

Sessions live in an in-process memoryStore() (gone when lousho dev stops), or in the agent’s own store when a module’s createAgent() options set one. The continuation of an approval is not streamed token by token: the endpoint runs it with agent.approvals.resolve() and sends the turn’s tool results and text as events once it finishes. lousho build servers (node-server, docker) serve these same endpoints from the same code, with sessions in a store chosen by LOUSHO_STORE and optional bearer auth: see Deployment: HTTP API. Hot reload. The agent is rebuilt a moment (100 ms) after a file changes, without restarting the server or dropping the port:

a spec: the spec file;
a directory: everything under it (instructions.md, the config file, tools/, skills/, subagents/), except node_modules and .git;
a module: the file and the local files it imports (relative import / require specifiers, found once at startup; no bundler).

Directory and module files are imported with a ?t=<time> cache-busting query, so an edited tool or agent file is re-evaluated. A file imported by that file (a shared helper) stays cached by Node: restart lousho dev after editing one. The console logs what reloaded. The new agent is built (and ready(), so MCP servers connect) before it replaces the old one, and the old one is then close()d. If the rebuild fails, the last good agent keeps answering, the error is logged and shown in a banner on the chat page (and as error in GET /dev/status); the next good edit clears it. Sessions survive a reload: the store outlives the agent swap, so the next message continues the conversation on the new agent. An approval that was pending on the old agent is not known to the new one (404); start a new session. Directories and modules are your code and run with your permissions; only run lousho dev on ones you trust.

--port - default 3737.
--host - default 127.0.0.1 (localhost only). Pass e.g. --host=0.0.0.0 to opt in to LAN access.

`lousho chat`

npx lousho chat agent.yaml                          # a spec file
npx lousho chat ./my-agent --model openai/gpt-4o    # an agent directory, on another model
npx lousho chat src/agent.ts --store sqlite:.lousho/chat.db --session support

A terminal REPL: each line you type is one turn of a session. <path> is loaded like lousho dev loads it (spec file, agent directory or .ts/.js module, see lousho dev); a missing path or bad extension fails with the same coded error (LOUSHO_CONFIG_INVALID, LOUSHO_SPEC_UNSUPPORTED_FORMAT), and so does an invalid --session id (LOUSHO_SESSION_ID_INVALID).

> look up cats
[lookup] {"q":"cats"}
  -> found cats
Cats are great.
[usage] 20 in / 6 out tokens, $0.0004
> email the report to sam
Approve send_email({"to":"sam@example.com"})? [y/N] y
  -> sent
Done, the report is on its way.

Text is written as the model produces it. Each tool call is one dim line, [tool_name] {args}, followed by -> result (or -> error: ...).
A tool call that needs approval asks Approve <tool>(args)? [y/N]: y or yes runs it, anything else rejects it and the model carries on. An ask_question call (askQuestion: true) prints the question with numbered options; answer with the number or with free text.
After each turn [usage] shows the tokens and, when every model used has known pricing, the cost (~ marks estimated tokens).
Errors from the SDK print with their [LOUSHO_...] code and fix, and the session continues.

Command	What it does
`/new`	Start a new session (the old one is kept in the store).
`/model <provider/model>`	Rebuild the agent on another model; the session continues. A failure keeps the current model.
`/compact`	Compact the session’s transcript now (old tool results are pruned) and print the before/after size.
`/clear`	Empty the session’s transcript; the session id stays.
`/history`	Print the session’s transcript.
`/quit`	Leave (Ctrl-D works too).

Option	Meaning
`--model provider/model`	Use this model instead of the one the target names. Applies to spec files, agent directories and `createAgent()` options exports; a module that exports an already built agent keeps its model.
`--session id`	Open this session (1-128 characters of `A-Za-z0-9_-`); default is a new `chat-<id>`.
`--store sqlite:<file>`	Keep sessions in a SQLite file (`SqliteStore`), so `--session id` continues a conversation after a restart. Default: in memory. Pending approvals are not restored after a restart.

The REPL itself is runChatRepl() in src/cli/chatRepl.ts; it takes the input lines, an output stream and an agent factory, so it can be tested with scripted lines and a mockModel agent and no terminal.

`lousho build`

npx lousho build --target=node-server --agent=agent.yaml        # or docker / cloudflare-worker
npx lousho build ./my-agent --target=node-server                # an agent directory (node-server, docker)

Writes the artifact to --out (default .lousho/build/<target>) and prints the command to run or deploy it. Building needs tsup (npm install --save-dev tsup). Targets, the HTTP API they serve and the Workers limits are in Deployment.

`lousho studio`

npx lousho studio            # http://127.0.0.1:4750
npx lousho studio --port 5000

Starts one local server for the Agent Forge API and UI. Agents and run state are stored under .lousho/ in the current directory. See Agent Forge for the walkthrough.

Get started

Build an agent

Compose agents

Run it reliably

Put it in front of people

Test and observe

Ship

Usage

`lousho dev`

`lousho chat`

`lousho build`

`lousho studio`

​Usage

​lousho dev

​lousho chat

​lousho build

​lousho studio

Usage

`lousho dev`

`lousho chat`

`lousho build`

`lousho studio`