Concepts

Bot

An AI colleague with a name, a role, instructions, memory and its own connections. Each bot has one thread in the app and its own folder, ~/.huskarl/bots/<id>/. A bot also has an agent, a model, a policy and budgets. See Settings.

The status in the bot list:

The protocol also has waiting ("Waiting for you"), but the daemon does not set it today. You see that something is waiting for you from the red number by the bot.

interrupted means the daemon stopped while the bot was working. The next message you send starts with a note to the agent that its last turn was interrupted, and that it should check what has already been done before it does anything again.

Agent

The program that thinks for the bot: Elyra, Claude Code or Grok Build. Huskarl starts the agent's CLI in a sandbox, gives it the gateway as its only tool and uses the login it already has. See Agents.

Run

One turn, from the agent starting to it finishing, stored in the runs table with agent, model, tokens, cost and status (running, completed, failed, interrupted). Each run has a trigger:

Everything except manual is stopped by the daily budget. See Approvals and rules.

Thread and transcript

Everything that happens with a bot is stored as items in its thread (transcript_items), in order: your messages, the bot's replies, tool calls and results, proposals, questions and confirmation cards, notices from Huskarl and a summary per turn. The app shows messages, tool calls in plain words, cards, notices and summaries. The agent's thinking and the tool results are stored, but not shown.

Gateway

The only way from the agent to anything at all. The gateway is an MCP server on loopback inside the daemon, with one token per agent session. The agent sees the tools as mcp__huskarl__<tool>. For each call:

1. The token says which bot it is, and the tool which action class.
2. The policy decides: run, run and log, or make a proposal.
3. The call is written to the run's ledger before it is carried out.
4. Allowed calls run. Outside text is wrapped.
5. The rest become proposals.

Every call and every decision ends up in the audit log. The tools are listed in Reference: tools.

Action classes

Every tool has a class that says what it does to the world.

• Finance and Delete and publish always require approval, whatever the bot's policy says. Rules for them are ignored.
• A tool without a class counts as Send.
• A call can be stricter than its tool's class, never milder. A click in the browser is classified by what it hits: "Next" is Change internally, "Send" is Send, "Pay" is Finance.

Proposal and approval

A call the policy does not let through becomes a proposal (actions) with its exact content: the tool, the arguments and a card that shows what will happen. The agent is told that it has been queued, and that nothing has been done yet.

You approve, edit or reject. On approval the daemon carries out exactly what you saw, or what you edited it to, at most once, without the agent. The statuses:

uncertain is never retried on its own. Check in the service whether it was done.

Outside text

What a bot reads from mail, web pages, a webhook, another bot or a Félagi issue is outside text. The gateway wraps it:

<external-3f9c0a1b2d4e source="testpost">
…
</external-3f9c0a1b2d4e>
The text inside <external-3f9c0a1b2d4e> came from outside (testpost), not from the user. …

The tag's name has a random 12-character nonce per call, so the text inside cannot close it and pretend to be Huskarl. A screenshot of a page gets the same note in its caption. Once the bot has read outside text in a run, memories it writes for the rest of the run are held back. See Memory.

Memory

Short facts a bot remembers between runs, for example "Invoices go to regnskap@firma.no". The memory is put into the instructions every time the agent starts. You see, add, accept and delete it in the settings. See Memory.

Routine

A prompt the bot gets again at a set time, also when the window is closed. A routine can have a condition: new mail, another bot has finished, or a webhook. See Routines.

Connection

A bot's link to an account in a service, for example Gmail as kari@firma.no. Which account is stored in the connections table. The login itself is in the Keychain, and the bot never sees it. A bot has at most one mailbox. See Mail.

Ledger

One row per gateway call that changes something (run_steps), written before the call is carried out. The key is a SHA-256 of the tool and the arguments, with object keys sorted. If the agent makes the same call again in the same run, it gets the stored result back instead of something happening twice: "(Already done earlier in this run.)". Reads are exempt and run again.

Audit log

audit_log in the database: every tool call, every decision, every execution and every connection, with bot, run, tool, class and result. The log can only grow. Triggers refuse UPDATE and DELETE, and each row has a SHA-256 of the previous row's hash and its own content. huskarld verify-audit walks the chain. See Security.