Huskarl documentation
AI colleagues on your own Mac: bots with a role, a memory and logins of their own, which do office work and deliver the result in a chat thread. Written in Rust, with the window in GPUI. macOS on Apple Silicon only.
| If you want to | Read |
|---|---|
| install Huskarl and have the daemon start by itself | Installation |
| make the first bot and try it on the practice mailbox | Getting started |
| know what a bot, a run, a proposal and an action class are | Concepts |
| decide what a bot may do without asking, and what it may cost | Approvals and rules |
| connect a bot to Outlook / Microsoft 365 or Gmail | |
| let a bot triage issues, sum up pull requests and draft release notes | GitHub |
| let a bot hand coding tasks to agents in Elyra Workspace | Elyra Workspace |
| let a failed command in eterm tell a bot, and see waiting proposals in eterm | eterm |
| let a bot work at set times, on new mail, after another bot, on a webhook, on files in a folder or before a meeting | Routines |
| see, accept and delete what a bot remembers | Memory |
| give a bot its own browser, watch it and take over | Browser |
| run a bot with Elyra, Claude Code or Grok Build | Agents |
| let one bot give the others tasks | Chief |
| share a bot, or make one from someone else's | Recipes |
| get a report, a letter or a sheet from a bot | Documents |
| let the bots take issues from a Félagi workspace | Félagi |
| be told when you are not looking at the window, also on your phone | Notifications and menu bar |
| find a message again, or see how the agents have done | Search and statistics |
| know what each field in the settings does | Settings |
| understand what stops a bot from doing something you do not want | Security |
| know what each plan costs and gives | Plans and prices |
find the right huskarld command |
Reference: CLI |
find an environment variable or a file under ~/.huskarl |
Reference: configuration |
| see which tools a bot has, and which class each of them is in | Reference: tools |
| talk to the daemon over the socket | Reference: IPC |
| understand how Huskarl is built | Architecture |
| build, test or make a release | Development |
| work out why something does not work | Troubleshooting |
What it is
Two programs. Huskarl.app is the window: the bot list on the left and the
thread with the chosen bot in the middle. huskarld is the daemon that runs
the bots. It keeps going when the window is closed, runs routines at night and
is the only one that writes to the database.
Each bot is run by an agent CLI you already have: Elyra, Claude Code or Grok Build. The agent reaches nothing but Huskarl's own tools (the gateway), runs in a sandbox and gets onto the network only to its own model provider. Everything that goes out in your name, costs money, deletes or publishes becomes a proposal you approve. It is the daemon that carries out what you approved, exactly once, without the agent taking part.
What it is not
- Not a cloud service. The bots, the database and the logins are on your Mac. What goes out goes to the model provider, to the services you have connected, and to ntfy or Félagi if you turn them on.
- Not a model. Huskarl has no model keys and runs no model itself. It uses the login in the agent you have.
- Not for other platforms. Only macOS 13 or later on Apple Silicon.
- Not finished. See below.
Not yet
- Making, changing or deleting a routine yourself in the app. You ask the bot for it in the chat, or get a routine from the proposal when you make the bot.
- A budget in kroner. The daily budget is in dollars, the way the agents report cost.
- Chrome for Testing shipped with the app. The bots' browser uses a Chrome or Chromium you have installed.