All documentation

Mechanics

This page describes what Besydr does while you work with an agent. Each section says what starts the mechanic, what you or the agent see, and which setting turns it off. Settings are in Configuration.

Terms used here:

  • A turn is one request of yours and everything the agent does until it stops.
  • A notice is a short message that the client shows to you. Which clients can show one is listed in Clients.
  • A note is text that Besydr adds to the agent's context. You do not necessarily see it.
  • The writing model and the decision model are the two models described in Configuration.

Besydr's supervision is always on in this release. The switches below turn single mechanics off. Several mechanics call a model, so they use your model account (the hub or your own provider). /info in octomind lists the calls, time and cost of each mechanic that ran in the session; see the last section.

Completion check

Setting: [gate] enabled (default on).

  • Trigger: when you send a request, Besydr starts writing a checklist in the background: observations that would show the request is fulfilled, written from the request before any work. When the agent stops at the end of a turn that you started, Besydr compares the checklist with what the agent did.
  • What it compares: your request, the checklist, the agent's tool calls and their results, the file changes, and the last command's output. Before it asks the model, a free check looks for the case where the agent changed something and no successful check ran after the change; that result goes to the model as a hint, not as a rejection.
  • Outcomes:
    • Pass: the turn ends.
    • Gaps: the agent is sent back to work with the list of gaps as its next instruction. Unchanged gaps after new evidence stop the retries early.
    • Unsettled: the evidence is thin. With unsettled_advisory on, the agent gets one note per user turn and the check runs again. It does not block.
    • Indeterminate: the check model was unavailable or answered in an unusable form. The turn ends and is recorded as unverified.
  • Limits: at most 3 checks per turn. No check runs while the agent has background work pending, when the turn was stopped, or for turns the agent started on its own.
  • What you see: a message when the agent is sent back, and the gaps in it. The agent sees the gaps as its next instruction. Where the client cannot continue a turn, the gaps are given as a note instead; all four hook clients can continue a turn.
  • Limit of the method: the check is as good as the writing model. It is not a code review.
  • Off: gate.enabled = false. The checklist is still written while plan.enabled or authorizer.enabled is on.

Standing rules and reminders

Setting: none. Always on.

  • Trigger: you state a rule for the rest of the session, such as "from now on, never push to main".
  • What happens: Besydr keeps your exact words as a standing rule, repeats it with every later request, and asks the client to keep it through a compaction (the client folding old messages into a summary). A rule is only kept if its text occurs verbatim in your message. It stays until you revoke it in words that quote the rule. Besydr holds at most 8 standing rules of at most 200 characters each; the oldest goes first.
  • Besydr treats three other things the same way: the checklist of the current request, constraints stated in your latest request, and whether you allowed or forbade running checks (for example "do not run tests").
  • What the agent sees: a block of text near the end of its context, headed "Re-anchor on your task".
  • Off: no switch.

Loop and no-progress notes

Setting: none. The thresholds are fixed.

  • Trigger: after each round of tool calls, Besydr compares the results with earlier ones. It signals when the same calls return the same results for 3 rounds in a row, when 5 rounds bring nothing new, or when several commands failed and none of those calls later succeeded.
  • What the agent sees: a short note suggesting a different approach or a report that it is blocked. The note is advice; it never blocks a call. Repeated notes become less frequent.
  • Off: no switch. Use advise below to change what the note says.

Advice note

Setting: [advise] enabled (default off).

  • Trigger: a loop or failure signal after at least four recorded actions in the turn. It never fires on no-progress and never on a timer.
  • What happens: one call to the writing model reads your request, the last tool results and any earlier records of the same stuck pattern, and writes a short observation that cites a result by number. It writes no command and no code. It may also decline. A note that cites a missing result, runs past 120 words, or contains a code block or a command line is dropped and the plain note is sent instead.
  • Measurement: one in four eligible signals gets the plain note on purpose, so the effect of advice can be compared later. Every signal is appended to advise.jsonl in the data directory with the check's verdict that followed. Nothing acts on that log yet.
  • Off: advise.enabled = false.

Tool admission

Setting: [authorizer] enabled (default off).

  • Trigger: before a round of tool calls, in clients that let Besydr deny a call.
  • What happens: Besydr allows the call unless the writing model finds a concrete conflict with your words or the agent's role, and a second, independent check confirms the conflict. When the model is unavailable, times out or is unsure, the call is allowed.
  • What the agent sees: for a confirmed conflict, a denied call with a reason that quotes your words.
  • Limit: a model-based check can be wrong in both directions.
  • Off: authorizer.enabled = false.

Condensing of large tool output

Setting: [condense] enabled (default on), tokens_threshold (default 5000), adaptive (default off).

  • Trigger: a plain-text tool result larger than the threshold (estimated tokens). Smaller results pass unchanged and are never shown to the model. A result under 512 tokens is never a candidate.
  • What happens: one call per round of tool calls decides, for the large results only, what the agent needs for the task. All relevant: the result is kept in full. Partly relevant: only the needed lines are kept. The model names line ranges and Besydr copies those lines from the original, so the model rewrites nothing. Not relevant: the result is replaced by a fixed notice. Error and diagnostic lines are kept.
  • Recovery: the full original is saved to a file first, and the shortened result names the path so the agent can read any cut part.
  • When it applies: only where the client lets Besydr replace a tool's output (Claude Code: Bash results only; OpenCode and pi: every tool, pi except failed calls; not in Codex) and the agent can read the saved file. Without both, results are left as they are.
  • With adaptive on, the trigger moves during the session between 0.5 and 2 times the configured value, following the savings seen so far.
  • Off: condense.enabled = false, or tokens_threshold = 0.

Plan

Setting: [plan] enabled (default on).

  • Trigger: the agent signals, alongside real work, that the task has dependent phases or is easy to lose track of. The agent has no tool to change the plan itself.
  • What happens: a separate model call makes one decision from the request, the recent work and the evidence: create a plan, advance a phase, hold or revise. Plan steps can name a condition that Besydr can check, for example that a file exists. When a condition stops being true, Besydr notes it to the agent and revises the plan. The completion check clears a finished plan.
  • What you see: in octomind, /plan shows the plan. Claude Code, Codex, OpenCode and pi give Besydr no way to read or change the agent's plan, so Besydr keeps its own plan for those sessions.
  • Off: plan.enabled = false.

Hindsight

Setting: [hindsight] enabled (default off), model.

  • Trigger: the agent hands a turn back to you.
  • What happens: a small model that runs on your CPU reads the turn's events and estimates how likely your next message is a correction, and of what kind (for example "not done" or "unrequested"). The numbers act on nothing. They go to the debug log, appear as a notice, are counted in /info, and are appended to hindsight.jsonl in the data directory next to the completion check's verdict. The model is fetched from the Hugging Face repository named in model (set HF_TOKEN for a private one) or read from a local folder.
  • Off: hindsight.enabled = false.

Lessons

Setting: [learning] enabled (default on), [decision] recall.

Besydr extracts lessons from sessions and adds the ones that fit the current request to the agent's context. This has its own page: Learning.

Sections of project documents

Setting: [inject] enabled (default off), and the limits in the same table.

A project's AGENTS.md or CLAUDE.md often points to longer documents, for example docs/migrations.md, that the agent does not open on its own. With this mechanic on, Besydr reads those documents and adds the section that fits the file the agent is working on.

  • Which documents: the files that AGENTS.md and CLAUDE.md reference, and the files those reference, down to max_depth. AGENTS.md and CLAUDE.md files in subfolders count too, for work below their folder. A file whose name starts with .env, ends with .pem or .key, or contains secret or credential is never read, and a file outside the project is never kept.
  • Trigger: a tool call that names a file, such as a read or an edit, or a request of yours that names a file path. Sections that name that path are candidates.
  • What happens: Besydr adds each chosen section to the agent's context as a note. The note states the document, the line range and the reason, for example you edited db/schema.sql. No model is called.
  • What is left out: a document the client already loaded in full, a document the agent read itself, and a section that is still in the conversation unchanged. When the document changes, its section is sent again and marked as a replacement. When a compaction removes a section that was added in the current turn, it is sent again.
  • Limits: at most 3 sections and 1200 tokens at one point, 3000 tokens per turn and 12000 tokens in the conversation at once. All four are settings.
  • When it applies: only where the client sends Besydr the text of project files on request. In this release that is octomind.
  • Limit: Besydr does not look inside a document for keys or passwords. Keep them out of documents that AGENTS.md references.
  • Off: inject.enabled = false, the default.

Status view

Setting: none.

When a client asks for status, Besydr returns rows: the Besydr version, the client and its version, the number of sessions in memory, the licence standing, whether the project is a personal or a team project, then one row per mechanic that ran in this session (model calls, wall time, tokens, cost and results), then a total. In octomind these rows appear in /info.

A project counts as a team project when two or more different committer addresses appear in the last 90 days of its git history. No repository, no commits, or a git that fails all count as a personal project. This setting is shown only; nothing else in Besydr reads it in this release.