Command line
besydr <command> [options]
besydr --version prints the version. besydr --help and besydr <command> --help print the built-in help.
| Command | Platforms | What it does |
|---|---|---|
serve |
all | Run the server that agents talk to. |
connect |
all | Join the shared server over standard input and output. |
restart |
Linux, macOS | Stop the running server and start this program's server. |
install |
Linux, macOS | Add Besydr to Claude Code, Codex, OpenCode or pi. |
uninstall |
Linux, macOS | Remove Besydr from one of those clients. |
hook |
Linux, macOS | Run one hook or event. The client calls this, not you. |
licence |
all | Show the licence standing, or install a licence. |
config |
all | Show where the config file and data are, and which key variables are set. |
stats |
all | Show what Besydr did: totals by client, event and purpose of model call. |
serve
besydr serve [--stdio | --socket <path> | --http <address:port>]
Runs the server. It loads the config file first (writing it if it does not exist), and copies octomind's lessons if that applies (see Learning). The three options are alternatives; give at most one.
| Option | Meaning |
|---|---|
| none | Listen on the Unix socket from [server] socket, by default besydr.sock in the data directory. If another Besydr already listens there, this one prints besydr: already running on <path> and exits. The server exits after idle_exit_minutes without a connection or background work, and when it receives SIGINT or SIGTERM. |
--stdio |
Talk over standard input and output, one JSON object per line. |
--socket <path> |
Listen on this Unix socket instead of the configured one. |
--http <address:port> |
Listen for HTTP requests. The address must be a loopback address (127.0.0.1 or [::1]) because the server has no authentication. |
On Windows the socket is not available: use --stdio or --http.
You rarely run serve yourself. The first hook or connect that finds no server starts one in the background. A hook that finds a server of an older version replaces it with its own, once, by itself, but only when no other client is connected to that server (see restart).
connect
besydr connect
For an agent that starts Besydr as a child process, as octomind does. It joins the shared server over standard input and output and starts the server if none is running. It prints only what the server sends. On Windows it runs a server of its own over standard input and output (the same as serve --stdio).
restart
besydr restart
Stops the server that listens on the configured socket and starts the server of this program, so a newly installed version takes over. The old server stops the same way as when it receives SIGTERM. If no server is running, it only starts one. It prints one line saying which of the two it did, and fails if the old server is still listening after 10 seconds.
restart stops the server even when other clients are connected: their running requests are cut. A hook that finds a server of an older version does the same by itself, but only when it is the only client connected, so it never cuts another client's work. pi and OpenCode keep one connection to the server for a whole session, so while one of them runs, a hook leaves the old server alone. After an update, run besydr restart and restart those clients. You also need restart after a rebuild with the same version number.
A server from before restart existed does not know the request to stop. restart then fails and says so; stop that server's process by hand once, then run restart again.
install and uninstall
besydr install <client> [--print]
besydr uninstall <client> [--print]
<client> is claude, codex, opencode or pi. install adds Besydr's hooks (Claude Code, Codex) or copies its plugin file (OpenCode, pi). uninstall removes them. --print shows the file that would be written, or for uninstall on OpenCode and pi, the file that would be deleted, and changes nothing. Details, paths and backups are in Install.
hook
besydr hook --client <claude|codex|opencode|pi> <hook name>
Run by the client at each hook or event, for example SessionStart. It reads the hook's JSON on standard input and prints the answer in the form the client expects. It never fails: on any error it prints nothing, exits with code 0, and appends the reason to hook.log in the data directory. install writes these commands into the client's settings; you do not need to run it by hand.
licence
besydr licence
besydr licence install <file or text>
Without a subcommand, prints the standing of the licence and where it was read from. install takes the besydr.licence file from the purchase email, or the licence text itself, which starts with besydr-licence-v1.. It checks the licence and keeps it in the data directory. See Licence.
config
besydr config
Prints the config file path, the data directory, the model and the decision model, and for each of the two, one line per key variable its provider reads, marked set or not set. It never prints a value. If the config file does not exist, this command writes it first, as every command that reads the config does. See Configuration.
stats
besydr stats [--days <N>] [--json]
Prints what Besydr did, from the activity log activity.jsonl in the data directory (see Configuration). It reads that file and needs no running server. If the file does not exist yet, it prints no activity recorded yet (<path>). A line it cannot read, and a line older than the period, is skipped.
The output starts with one line giving the period and the path of the log. A summary follows with what Besydr cost and what it achieved. It has one line for each of these that has data, so a log with no results shows only the first two:
- sessions seen in the period;
- what Besydr spent: model calls, tokens in and out, and cost in US dollars;
- how many tokens of the agent's context condensing saved, and from how many condensed results;
- completion checks: how many ran, passed and failed;
- tool calls stopped: how many tool calls the authorizer blocked;
- lessons: how many were saved (lessons, experiences and orientation notes together), how many were recalled into a prompt, and how many of those the agent used.
Then come three tables, each sorted by count with the largest first:
- By client (the agent that sent the events): sessions, events, errors, median and 95th percentile of the time an event took in milliseconds, model calls, tokens in and out, and cost in US dollars. A model call counts for the client of its session. A call of a session with no event in the period is listed under
unknown. - By event: count, errors, median and 95th percentile of the time in milliseconds.
- By purpose of model call: calls, tokens in and out, cost, and the milliseconds the agent waited, which is the summed time of the calls it waited for.
After the three tables comes a fourth, Results, with one row for each part of Besydr that counted something in the period (for example gate, recall, distill). A row lists its counts as name count pairs sorted by name, such as fail 1, pass 3, runs 4. A part that counted nothing has no row. The names are the ones Besydr uses in its own session report.
Percentiles use the nearest rank: the 95th percentile of 20 events is the second slowest.
| Option | Meaning |
|---|---|
--days <N> |
Count the last N days. Default 7. |
--json |
Print one JSON object instead of tables: from, to, log, the summary (a part with no data is left out), the three tables as the arrays by_client, by_event and by_purpose, and results as an array of rows with a mechanic and its outcomes counts. |
Colour
The commands that print text for a person to read use colour: stats, config, licence, restart, install and uninstall. One rule covers all of them: bold marks a section title, cyan marks a label (the name before a value), green, red and yellow carry meaning, and faint marks what matters least. Table headers, notes, zeros and empty cells are faint. Good news is green (a passed check, a saving, a success message), bad news is red (errors, a loss, a failed check) and warnings are yellow.
Colour is on when the output goes to a terminal. It is off when the output is piped or redirected to a file, with besydr stats --json, when the NO_COLOR environment variable is set to a non-empty value, and when TERM is dumb. Setting CLICOLOR_FORCE=1 turns it on in all of those cases, except --json, which never has colour. The commands that programs read (hook, connect, serve) never print colour.
Exit codes
A command that fails prints besydr: <reason> on standard error and exits with a non-zero code, except hook, which always exits with 0.