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

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).

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, then three tables, each sorted by count with the largest first:

  1. 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.
  2. By event: count, errors, median and 95th percentile of the time in milliseconds.
  3. 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.

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, and the three tables as the arrays by_client, by_event and by_purpose.

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.