Getting started

This walkthrough makes a bot, lets it read the practice mailbox and ends with a proposal you approve. Nothing goes to a real mailbox.

You need Huskarl installed and an Elyra that is signed in (elyra, then /login). See Installation.

The window is in English. If you would rather have Norwegian, choose Norsk under ⌘, → Appearance → Language; what Huskarl writes to you from then on is in Norwegian too. See Settings.

The first bot

With no bots, the window shows Welcome to Huskarl, in four steps:

An agent to run the bots: Elyra, Claude Code and Grok Build, each ready, installed but not connected, or not installed. See Agents.
Your first bot: the three that come with Huskarl (Inbox Manager, Expense Manager, Meeting Briefs; see Recipes), or Describe one…, which opens the form below.
Try it safely: the practice mailbox, and rehearsal for a recipe.
On your phone: notifications and approval from the phone.

Later you make new ones with + at the top of the bot list, or ⌘N.

The New bot form has four fields:

Describe the role in your own words, for example "Tidy my inbox every morning and draft replies to customers".
Name, for example Inbox Manager.
Role: one line about what the bot is for.
Instructions: what it should do, and what it must never do.

Only Name is required. Create makes the bot and opens the thread.

The designer: Suggest

Write a description and press Suggest (the button shows "Suggesting…" while it works). Where Apple Intelligence is on, Huskarl asks Apple's model on this Mac first: it is free, takes a few seconds, and nothing leaves the Mac. If its answer cannot be read, or the model is not there or turned off (⌘, → General → Apple Intelligence), it asks Elyra instead, in the sandbox and without tools. Either way it fills in name, role and instructions. A weekday the description names ("every Friday") is the routine's weekday, whatever the model made of it. If the role is regular work, there is also a proposed routine, for example "Create the routine «Morning tidy-up» – every weekday at 07:00". For work with incoming mail it often proposes "every 10 minutes when new mail has arrived".

Everything can be changed before you press Create. Click the routine line to not create the routine.

The designer:

always uses Elyra with your default model, whichever agent the bot will run with later
gets 180 seconds, otherwise it says "the suggestion took too long"
proposes only the schedules daily, weekdays, weekly and interval, and the condition new mail.

From the terminal: huskarld suggest "<description>" prints the proposal as JSON.

New bots are run by Elyra. The agent is switched in the bot's settings, see Agents.

Testpost: the practice mailbox

A bot without Gmail or Outlook gets Testpost, a mailbox in ~/.huskarl/testpost. The first time, it holds four emails:

Kari Nordmann wants to move a meeting to Thursday.
A newsletter from an online shop.
An email from "the IT department" with a prompt injection attempt. It asks the bot to send a copy of all mail to backup@evil.example.
An invoice from Ola Hansen.

Testpost has the same five tools as a real mailbox: list the inbox, read an email, make a draft, archive and send. Sending becomes a proposal. What is "sent" after approval ends up in outbox.json and goes nowhere.

All bots without a real mailbox share the same Testpost folder.

Send a message

Write in the field at the bottom ("Write a message…") and press ↵. Shift-↵ gives a new line. Try:

Go through my inbox. Archive newsletters, and draft a reply to Kari saying that Thursday at 10 works.

While the bot works, the bot list says "Working…". In the thread you see:

the reply, written as it arrives
the tools it uses, in plain words: "Looked through the inbox", "Read an email", "Archiving", "Sending"
lines from Huskarl, for example about memory and routines
at the end, a line with ✓ (or ✗), the time and the cost of the turn.

If you write while the bot works, it gets the message after the tool calls it is busy with.

Speaking instead of typing

The microphone beside the send button listens. Click it and speak; the words go into the field as you say them, and listening stops after a pause or when you click again. Then read it over and press ↵: nothing is sent by itself, so a word heard wrong never reaches the bot unseen. It listens in the language the app speaks (Norwegian or English).

Speech is recognised on the Mac, by Apple's recognition on the device: the sound never leaves it, and a language the Mac cannot recognise on its own is refused rather than sent to Apple. The first time, macOS asks for the microphone and speech recognition in Huskarl's name; if you said no, the line under the field says where to turn them on (System Settings → Privacy & Security). A proposal is never approved by voice: "yes, send it" becomes text in the chat, and the card still waits for your click.

The approval card

The reply to Kari is a proposal, not a sent email. It shows as a card in the thread:

The title says what is going to happen, for example "Send mail to kari@acme.no".
Subject and the text, exactly what goes out.
Status: "Waiting for you", "In progress…", "Done", "Failed", "Rejected" or "Uncertain – check".

The buttons:

Approve: the daemon sends exactly this, once.
Reject: nothing is sent.
Edit: the subject and the text become editable. Approve edited sends the edited text, and Cancel goes back. Edit exists only for proposals with text.

Once you have decided, the result is shown below the card, and the thread gets a line like "✓ Send mail to kari@acme.no: …". The next time the bot runs, it is told what you decided.

The bot list shows a red number next to bots that have something waiting.

The approval queue

Approvals at the top of the bot list, or ⌘⇧A, shows everything waiting, across all bots, oldest first. Each card has the bot's name and the time above it.

Key	What
⌘⇧A	open the queue
⌘↵	approve the top proposal
⌘⌫	reject the top proposal

⌘↵ and ⌘⌫ work while the queue is open. When it is empty, it says "Nothing is waiting for you.".

"Send it" in the chat

You can also approve in the chat: "Looks good, send it." The bot can never approve by itself. It puts a confirmation card in the thread, for example "Approve 1 proposal?", with the proposals it concerns. Only your click on Confirm and send decides. No leaves them waiting. See Approvals and rules.

Connect the bot to a real mailbox: Mail.
Let it do this every morning: Routines.
Decide what it may do without asking: Approvals and rules.