Binary and sidecar

The binary

cargo install anyagent
anyagent list            # installed agents: login state, models, commands, capabilities
anyagent chat claude     # prompt, stream, permissions allowed; /set model sonnet
anyagent serve           # the API as JSON lines on stdin and stdout
echo "one-line title for this diff" | anyagent chat codex   # one turn, then exits

list and chat are for a terminal. serve is for an app: it speaks the same Runtime and Session calls as one JSON object per line, so a TypeScript, Python, Swift, or Go app spawns the binary and talks to it. The crate stays the only place with logic.

your app ──stdin──►  anyagent serve  ──►  anyagent crate  ──►  claude / codex / acp agents
your app ◄─stdout──  replies · events · session errors · closed

Frames

Six shapes. Every command carries an id you choose; its reply carries the same id back, so several commands can be in flight.

Direction	Frame	When
out	`{"hello": {"protocol": 1, "anyagent": "0.0.5"}}`	first line
in	`{"id": 1, "cmd": "open", "agent": "claude", "dir": "."}`	any command
out	`{"id": 1, "ok": {..SessionInfo..}}`	the command’s result
out	`{"id": 1, "error": {"kind": "AuthRequired", "message": "..", "login": [..]}}`	it failed
out	`{"event": {..Event..}}`	one per event; `event.session_id` names the session
out	`{"session": "s1", "error": {..}}`	that session’s stream failed; `closed` follows
out	`{"closed": "s1"}`	that session’s stream ended

Events are the crate’s own serialization, unchanged: a variant with fields is {"kind": {"TextDelta": {"message_id": "m1", "text": "hi"}}}, and a unit variant is a bare string, {"kind": "ContextCompacted"}. What the sidecar guarantees:

The ok reply to open is written before any frame for that session.
Frames for one session keep the crate’s sequence order; sessions interleave.
A session error is terminal. The running turn has already ended with TurnEnded { stop: Failed }; closed follows the error, after the engine’s last bookkeeping events.
closed is written exactly once per opened session.
EOF on stdin closes every open session, even one whose open was still in flight, writes their closed, and exits 0. Closing is “close stdin, wait”. A stdout that stops accepting writes ends serve with that error.
A line that is not a command gets {"id": null, "error": {"kind": "BadFrame", ..}} and the loop continues.
The reader must keep up. A session whose events are not read within 1024 of production is closed by the crate, the same rule a Rust caller lives with.

Commands

One command per public call. agent is a catalog id such as "claude"; a catalog agent at an exact path is {"id": "claude", "path": "/opt/claude"}; a custom ACP agent is {"acp": {"name": "..", "path": "..", "args": [..]}}.

cmd	fields	ok
`discover`		`DiscoveryReport`
`probe`	agent, dir? (default: temp dir), env?, args?, config_home?	`AgentDetails`
`plan_usage`	agent, env?, args?, config_home?	`PlanUsage`
`open`	agent, dir, resume?, fork?, fork_at?, permission_mode?, mcp_servers?, configure?, instructions?, output_schema? (JSON schema), env? (object), args? (array), config_home?, record_wire?	`SessionInfo`
`generate`	prompt, attachments?, plus everything `open` takes	string
`prompt`	session, text, attachments?	`Delivery`
`answer`	session, request, answer	null
`configure`	session, option, value	null
`cancel`	session, clear_queue?, turn? (cancels only if it is the running turn)	null
`rollback`	session, turns, scope	null
`dequeue`	session, prompt	null
`compact`, `close`	session	null
`info`	session	`SessionInfo`

answer is one of {"Permission": "AllowOnce"}, {"Question": [..]}, {"Deny": {"message": ".."}} (deny once with a reason), or "Cancel" (withdraw the request). An error body is kind, message, and the variant’s own fields: agent for NotInstalled, login for AuthRequired, status and stderr for ProcessExited, detail for the rest. Two kinds are the sidecar’s own: BadFrame and UnknownSession (with session). A command on a closed session gets the crate’s SessionClosed. probe and plan_usage take open’s option fields too; resume or fork on them is InvalidConfiguration. plan_usage uses only env, args and config_home of them.

Types for other languages

packages/schema.json is a JSON schema (draft 7) of every wire type, generated from the Rust types with just schema and checked by tests/schema.rs. The command type is Frame; every output line is a Line; events are Event and EventKind; errors are ErrorBody. Feed it to a generator:

npx json-schema-to-typescript packages/schema.json      # TypeScript
datamodel-codegen --input packages/schema.json           # Python TypedDicts
python3 packages/typegen.py                              # Swift enums and Go structs, ours

Testing an app without agents

A build with --features mock accepts serve --mock <script.json>: the real engine over a scripted agent. The scripts every wrapper’s tests use are in packages/mock-scripts/, with a README mapping each test case to its file.

cargo build --features mock
echo '{"id": 1, "cmd": "discover"}' | ./target/debug/anyagent serve --mock packages/mock-scripts/turn.json

Packages

Language	Install	Status
TypeScript / Node ≥ 22.6	`npm install anyagent-ts`	ready; the binary comes from an `@anyagent-ts/<os>-<arch>` package, no postinstall
Python ≥ 3.11	`pip install anyagent-py`	ready; the binary is inside the wheel and lands on the venv’s PATH
Swift ≥ 6 / macOS ≥ 13	`.package(url: "https://github.com/spotta85/anyagent", from: "0.0.5")`	ready; the app bundles the binary as an auxiliary executable
Go ≥ 1.23	`go get github.com/spotta85/anyagent/packages/go`	ready; the binary sits next to the program or on PATH

Linux builds need glibc 2.28 or newer: Ubuntu 20.04, Debian 10, RHEL 8 and up.

import { Runtime, is } from "anyagent-ts";

const rt = await Runtime.start();
const session = await rt.open("claude", { dir: process.cwd() });
await session.prompt("explain this repo");
for await (const ev of session.events()) {
  if (is(ev, "TextDelta")) process.stdout.write(ev.kind.TextDelta.text);
  if (is(ev, "RequestOpened") && "Permission" in ev.kind.RequestOpened) {
    await session.answer(ev.kind.RequestOpened.Permission.id, { Permission: "AllowOnce" });
  }
  if (is(ev, "TurnEnded")) break;
}
await session.close();
await rt.close();

import asyncio, os
from anyagent import Runtime, kind_of

async def main():
    rt = await Runtime.start()
    session = await rt.open("claude", dir=os.getcwd())
    await session.prompt("explain this repo")
    async for ev in session.events():
        kind = kind_of(ev)
        if kind == "TextDelta":
            print(ev["kind"]["TextDelta"]["text"], end="", flush=True)
        if kind == "RequestOpened" and "Permission" in ev["kind"]["RequestOpened"]:
            await session.answer(ev["kind"]["RequestOpened"]["Permission"]["id"], {"Permission": "AllowOnce"})
        if kind == "TurnEnded":
            break
    await session.close()
    await rt.close()

asyncio.run(main())

import Anyagent

let rt = try await Runtime.start()
let session = try await rt.open("claude", OpenOptions(dir: FileManager.default.currentDirectoryPath))
_ = try await session.prompt("explain this repo")
turn: for try await ev in session.events() {
    switch ev.kind {
    case .textDelta(let d): print(d.text, terminator: "")
    case .requestOpened(.permission(let p)): try await session.answer(p.id, .permission(.allowOnce))
    case .turnEnded: break turn
    default: break
    }
}
try await session.close()
await rt.close()

import anyagent "github.com/spotta85/anyagent/packages/go"

rt, err := anyagent.Start(anyagent.Options{})
session, err := rt.Open("claude", anyagent.OpenOptions{Dir: cwd})
session.Prompt("explain this repo")
for ev, err := range session.Events() {
	if err != nil {
		log.Fatal(err)
	}
	if d := ev.Kind.TextDelta; d != nil {
		fmt.Print(d.Text)
	}
	if r := ev.Kind.RequestOpened; r != nil && r.Permission != nil {
		choice := anyagent.PermissionChoiceAllowOnce
		session.Answer(r.Permission.ID, anyagent.Answer{Permission: &choice})
	}
	if ev.Kind.TurnEnded != nil {
		break
	}
}
session.Close()
rt.Close()

session.info and session.status stay current; a session error throws from the for await (raises from the async for in Python, throws from the for try await in Swift, is yielded once by Events in Go); rt.generate(agent, { dir }, prompt) is one-shot text; rt.probe(agent, { dir, env }) and rt.planUsage(agent, { config_home }) take the launch options. Runtime.start({ bin, mock }) runs the package over a mock script. Every package passes the same eleven tests over the mock scripts on macOS, Linux, and Windows in CI (Swift: macOS and Linux); the TypeScript package also runs ten live on claude and codex. packages/README.md lays the four packages side by side.

Writing a wrapper

The wrapper is a pipe: spawn, write lines, route lines by id or session_id, buffer events per session. These rules keep every wrapper honest, and the same eleven subprocess tests run in each.

Rule	Why
Register a session inside the line reader, before the next line is read	Buffered lines can arrive before an awaiting `open()` resumes
Keep `session.info` and `status` live from `SessionUpdated` and `StatusChanged`	Capability checks go stale after `configure`
A session error makes that session’s iterator raise, then end; `closed` ends it cleanly	Apps see `AuthRequired` and `ProcessExited` where they read
Process death rejects every pending call and fails every iterator with `ProcessExited`	No hanging promises
`close()` is graceful and idempotent: close stdin, wait up to 5 s, then kill	The sidecar closes sessions on EOF
Per-session queues cap at 4096; past it, fail the session with `ConsumerLagged` and close it. Never pause reading stdout	One slow consumer must not stall the others; memory stays bounded
Offer `kindOf(event)` for both object and string forms of `kind`	Unit variants are strings
Errors keep `kind`, `message`, and every extra field	Apps show the real login instructions
Never interpret events beyond the second rule	Rules live in the crate
Check the hello: a first line that is not a frame, or another `protocol`, fails start with `ProtocolFailed` and kills the binary	A wrong `ANYAGENT_BIN` must neither hang nor crash the app

Getting started

Using anyagent

Internals

Binary and sidecar

The binary

Frames

Commands

Types for other languages

Testing an app without agents

Packages

Writing a wrapper

​The binary

​Frames

​Commands

​Types for other languages

​Testing an app without agents

​Packages

​Writing a wrapper

The binary

Frames

Commands

Types for other languages

Testing an app without agents

Packages

Writing a wrapper