Félagi

Huskarl and Félagi meet in two ways:

• The bots work for Félagi. huskarld becomes a runtime in Félagi, the bots become agents there, and an issue assigned to a bot becomes work for the bot in Huskarl. What goes back is the bot's own words. That is most of this page.
• A bot keeps track of your own Félagi tasks. With a personal API token, a bot (Dev Desk) sees the issues assigned to you, reminds you of what is due, and proposes comments, statuses and hours. See Your own tasks.

Connect

Create a daemon token in the Félagi workspace. It starts with fdt_. Then:

huskarld felagi connect https://felagi.example.com fdt_…
huskarld felagi status
huskarld felagi disconnect

• The server must be reached over https://, or locally on http://127.0.0.1… or http://localhost….
• The connection is tried before it is saved: Huskarl registers with Félagi first.
• The token is stored in the Keychain under the service no.huskarl.felagi, with the server address as the account.
• The settings are saved in ~/.huskarl/felagi.json: the server, an ID for this machine (daemon_id) and the machine's name (scutil --get LocalHostName). If you connect again, the ID and the name are kept.
• disconnect deletes the token and the file.

status answers with one of three:

not connected
connected to https://felagi.example.com (workspace acme), 2 task(s) in hand
https://felagi.example.com: not connected: Félagi answered 401: …

"In hand" means tasks waiting for the bot to be free, running, or waiting for you.

There is no setting for Félagi in the app yet. Everything is done in the terminal.

What happens

The daemon has its own thread for Félagi as long as it runs:

• Registration. Each bot is registered as an agent with ID, name and role. If the bots change, they are registered again (checked every 30 seconds).
• Heartbeat every 15 seconds. If Félagi has forgotten the machine (410), it registers again.
• Issues are fetched every few seconds (HUSKARL_FELAGI_TICK_MS, default 2000, fetched every other round). An issue for a bot that no longer exists is reported back as failed.
• Start. The issue is started when the bot is free. If it is busy, Huskarl tells Félagi every 90 seconds ("Waiting for the bot to finish what it is doing."), so the issue is not taken back.
• Along the way, what the bot writes is sent to Félagi, and "Still working." if 90 seconds have passed without anything.

What the bot gets

The issue becomes a prompt: identifier and title, priority, description, "Done when:" with the acceptance criteria, the workspace's instructions and the instructions for the agent there. All of this is wrapped as outside text (source "Félagi ACME-7"). The bot does the issue with its own tools and rules, and finishes with a summary. Memories it writes in the run are held back.

The daily budget applies: an issue from Félagi is not a message you sent yourself.

What Félagi sees, and does not see

Félagi gets:

• the bots' ID, name and role
• what the bot writes in its replies
• the names of the tools it uses, without mcp__huskarl__, for example gmail_read_message
• notices from Huskarl in the thread (as system, or error on failure)
• the summary and the cost when the issue is done.

Félagi does not get:

• what the tools read: mail, web pages, inboxes
• the bot's instructions and memory
• the logins.

Waiting for approval

If the run creates proposals, the issue waits in Félagi until you have decided all of them:

1. When the run is done and something is waiting, Huskarl reports await with "Waiting for approval in Huskarl: ; …". The lease is released.
2. You approve or reject in Huskarl, as usual.
3. When everything is decided, Huskarl reports resume, gets a new lease and completes the issue.

The summary is the bot's last reply, with "Decided in Huskarl:" and one line per proposal: "Approved: …", "Rejected: …", or "Approved, outcome unknown: …" for one that failed or became uncertain.

Waiting issues are kept in the table felagi_tasks (migration 14), so they survive a restart of the daemon.

Cancellation and errors

• If Félagi asks to stop, the bot is interrupted and Huskarl confirms (cancel-ack).
• If Félagi answers 404, 409 or 410 for an issue, the issue is gone for Huskarl (cancelled, done or taken back). The bot is stopped if it is working on it, and the issue is forgotten.
• If the run does not get going, the issue is reported as failed ("The bot could not start." or "The run did not start."). If it ends without completing: "The run ended: failed.".
• When Félagi cannot be reached, the thread tries again after a while. The error shows in huskarld felagi status.

Protocol 4

Huskarl speaks Félagi's daemon protocol 4, over POST <server>/api/daemon/…: register, heartbeat, tasks/claim, tasks/<id>/start, messages, complete, fail, await, resume and cancel-ack. Every request has Authorization: Bearer fdt_…, X-Felagi-Client: huskarld/<version> and X-Felagi-Client-Capabilities: await,actors. Requests about a specific issue have X-Felagi-Lease.

The server side is on the protocol-4 branch in Félagi (version 0.96.0). See phase-5.md for what has changed there.

Your own tasks

The second way uses Félagi's public API (/api/v1) with a personal token, fat_…, which is not the daemon token above: it is yours, for one workspace.

1. In Félagi → Settings → API tokens, make a token with write for the workspace you work in. A read token is refused: the bot could see but never propose anything.
2. Félagi shows it once, with .env lines (FELAGI_URL, FELAGI_TOKEN, FELAGI_WORKSPACE). Copy them.
3. In the bot's settings in Huskarl, paste them in the Félagi field under Connections, and click Connect.

The daemon asks Félagi who the token is before it keeps it, then keeps the token and the address in the Keychain under no.huskarl.felagi-api, with <your email> · <workspace> as the account. The token alone works too when the daemon already works for that Félagi (it takes the address from there). From the terminal: pbpaste | huskarld connect <bot> felagi.

An issue is named by its key (ACM-7) or number; anything else is refused before it can become a proposal. Comments, statuses and hours are seen by your team and end up on timesheets, so each waits for you, and the bot is told to propose hours only for time you gave it. What is read from Félagi is outside text.

Félagi has no reminders of its own; Dev Desk's routines are them. Its morning routine starts with your issues that are overdue or due within three days, and at 15:30 on weekdays it says what you have logged today and asks what to log.

Not yet

• protocol-4 is not merged and rolled out in Félagi. Huskarl needs a Félagi that has it.
• Settings for Félagi in the app.
• A last turn for the bot after you have decided the proposals. Today the summary is the bot's reply from before the approval, with the decisions below.