AI Assistant

AI Assistant

The AI Assistant is a chat that knows your Board and your fleet. Open it from any page, ask what is stuck, what a card is about or what the budget looks like, and have it draft or queue cards for you. It runs in the Nautelle API through an LLM provider gateway you configure — Anthropic, OpenAI, xAI Grok or OpenRouter — with encrypted keys, an enabled-model list and monthly spend caps.

Overview

Part	What it is
LLM provider gateway	the API's single path to model providers: sealed keys, enabled models, a default model, per-provider monthly caps, metered usage
Floating assistant	a launcher on every page that opens a draggable, resizable chat window (a sheet on phones)
Conversations	personal chats that stream, with a model picker, a project picker and attachments
Tools	read the Board, fleet, queue, budget, activity, sessions and approvals; draft and queue cards; request actions a person approves

Note

The gateway is only for assistant features. Runner-driven work — the planner, card workers, design, Steward — still runs on the runner with Claude, as before.

How it works

flowchart LR
  P["You (web or Telegram)"] --> C["Assistant conversation"]
  C --> G["LLM gateway<br/>(cap check, metering)"]
  G --> M["Provider model"]
  M -- "tool call" --> T["Board tools<br/>(your role, your projects)"]
  T -- "write that needs a person" --> AR["Action request<br/>→ Approvals / Telegram"]
  T --> M
  M --> C

Loading

1. You send a message. If the conversation is on Auto, the API matches the message against your projects by name and binds the conversation to one; if several match, the assistant asks which.
2. The API calls the model through the gateway, which checks the provider's cap first and records every call it sends.
3. The model may call tools — up to 8 model calls per turn. Each tool checks your role on the project the way the web does.
4. The reply streams back. It is written in the language of your latest message and also stored in English.

Setting up providers (admin)

1. Set LLM_SECRETS_KEY in the API environment — 32 random bytes, base64 (openssl rand -base64 32). Without a valid key the gateway does not start: no AI feature runs and no key can be stored, but the rest of Nautelle runs on.
2. Open Admin › AI providers.
3. For each provider: set the API key, then Test it — the test is a call that costs nothing.
4. Enable the models you want. A model can be enabled only when Admin › Prices prices it.
5. Choose the instance's default model.
6. Set each provider's monthly cap in USD.

Provider	Default cap
Anthropic	$200 / month
OpenAI, xAI Grok, OpenRouter	$0 — disabled until you set a cap above 0

• Keys are write-only: the API shows only the last four characters and when the key was set. They are sealed with AES-256-GCM under LLM_SECRETS_KEY, which is separate from APP_ENCRYPTION_KEY.
• Provider error text is redacted before it is shown or logged.
• Setting, testing and deleting keys and changing models are written to the audit log, with the key's suffix only.
• Caps reset at 00:00 UTC on the 1st. At the cap, calls fail with a message that names the provider and the reset date. The page shows this month's spend.

Using the assistant

1. Click the assistant launcher on any page.
2. The window can be dragged by its title bar, resized from any edge, minimized (Escape) and maximized; its position and size are remembered.
3. The rail lists your conversations grouped Today / Yesterday / Previous 7 days / Earlier, with New, rename and delete.
4. In the composer, pick a model (any enabled model with a key and a cap above 0; otherwise the default) and a project (or Auto).
5. Attach context if you need to:
   • a card of a project you can see;
   • an agent session, only from a project that ships session content;
   • a file or screenshot (needs a project and operator role; images go to models that accept images).
6. Tool activity appears inline as blocks — a link to a created card, or the approval state of a requested action.

Conversations are personal: nobody else, admins included, can open yours. A title is written after the first reply by the cheapest enabled model.

What the assistant can do

Tool	Kind	What it does
list_projects, choose_project	read	list your projects; bind the conversation to one
read_board, read_card	read	the Board and a card
read_fleet, read_queue	read	orchestrator slots and the ready queue
read_budget, read_activity	read	remaining budget and recent activity
read_sessions	read	agent sessions — metadata only
read_approvals	read	pending pull requests and action requests
draft_card	no write	returns a draft card; the chat shows Edit and Queue
queue_card	write (operator)	puts the card at the top of To Do — only when you ask
request_action	request	creates a pending action request: stop the orchestrator, merge a card's PR, or handoff a card as an issue for the fleet

Important

The assistant never stops, merges or hands off anything itself. request_action only creates a pending request that a person approves in Approvals or Telegram. Reads go through the same services as the web, with your role.

In Telegram

Free text you send the bot goes to the assistant as you, and continues one conversation per chat that also appears in the web rail. /newchat starts a new one. See Telegram › Talking to the assistant.

Limits

• At most 20 turns a minute per person, and one turn at a time per Telegram chat.
• A turn that fails is removed, so a retry does not duplicate your message.
• The gateway never reads a project's filesystem; it sends only what the API already stores or what you typed.

See also

• Telegram · Claude Code Integration

Decisions: ADR-0059 · ADR-0060 · ADR-0061 · Spec: #598, #600, #608, #618