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