- Archive
- /
- Foreman Assistant
- /
- Getting Started with Foreman Assistant
Getting Started with Foreman Assistant
Learn how to open Foreman Assistant, start a chat, send your first message, and enable the optional floating widget for quick AI access.
Open the chat
There are three entry points:
- Sidebar link — click AI Chat under AI & API in the left sidebar.
- Direct URL — navigate to
/foreman-assistant. - Floating widget — once you opt in (below), click the bubble at the bottom-right of any page, or press Ctrl + Shift + K.
When you first arrive at the full-page, a sidebar shows your conversations (empty on first use) and the main panel offers a New chat button plus a row of quick-prompt buttons to get you started.
Send your first message
- Click New chat or the + icon in the sidebar.
- Type a question in the composer at the bottom — anything from "list my projects" to "summarise pending access requests for Hub XYZ".
- Press Enter to send. Use Shift + Enter for a newline.
You'll see three things happen in sequence:
- A purple Thinking pill appears briefly if the model is reasoning through the request (collapsible — click to expand the chain-of-thought).
- One or more tool call indicators show as the AI queries Foreman ("Looking up projects…", "Searching files…", etc.).
- The AI's response streams in token-by-token in a light slate bubble. A subtle scroll-to-bottom button appears if you scroll up mid-stream.
The first message in a new conversation auto-sets the chat title from the text you send. You can rename it later from the widget header (click the title).
Enable the floating widget
The floating bubble is off by default so you don't see it unless you want to. To turn it on:
- Go to Account → Manage → Profile.
- Scroll to AI Chat mini-widget.
- Tick Enable the floating mini-widget.
- Click Save changes.
Once enabled, a small chat icon appears at the bottom-right of every authenticated page. It sits quietly until you click it — at which point the widget panel slides in, restoring the most recent conversation where you left off.
You can also enable it from inside the full-page by clicking Minimize in the top-right — this both persists the preference and drops you back onto your previous page with the widget open.
Keyboard shortcuts
| Keys | Action |
|---|---|
| Ctrl + Shift + K | Toggle the widget open (requires widget to be enabled) |
| Escape | Close the widget (when not typing in an input) |
| Enter | Send the current message |
| Shift + Enter | Newline inside the message |
| Tab / ↑↓ / Enter | Navigate the slash-command or @ mention palette (see Slash Commands & @ Mentions) |
| / (at start of message) | Open the slash-command palette |
| @ | Open the project-mention palette (MCP-enabled projects) |
The composer bar
The box at the bottom of the chat is where you type. It expands to fit multi-line input up to ~200px tall and then starts scrolling. A few features are tucked in:
- Paperclip icon — open the file picker to attach images, PDFs, CSVs, Word/Excel docs, or text files. You can also drag files directly onto the composer. See Attachments in AI Chat.
- Send (paper plane) / Stop (red square) — the button swaps between Send and Stop depending on whether a response is streaming.
- Always-on typing — the text box stays editable even while the AI is replying. You can draft your next question; the Send button unlocks the moment the response finishes.
- Footer line — displays either your monthly token usage, your tier name, or a short "Foreman Assistant may not always be accurate." reminder.
- Slash commands — type
/at the start of a message to get a floating palette of commands and pre-built prompts. - Project mentions — type
@to tag a specific MCP-enabled project (e.g.@acme). Foreman resolves the alias to its project and hub before the message is sent, so the AI operates on the right project without a lookup round-trip. See Slash Commands & @ Mentions.
Widget size modes
The floating widget has three sizes, cycled with the expand/contract button in the widget header:
| Mode | Width × Height | Good for |
|---|---|---|
| Compact | 380 × 560 | Quick questions, mobile-ish screens |
| Expanded | 560 × 720 | Normal back-and-forth, reviewing tool output |
| Full height | 600 × (100vh − 2rem) | Long sessions, reading large AI replies |
On phones and small tablets (< 480 px wide), the widget takes over the full viewport regardless of mode.
Quick prompts on the empty state
When you open a brand-new conversation, the main panel shows six starter chips:
- List my projects
- Search for files
- Check access requests
- Show scheduled jobs
- Browse project folders
- Help with Foreman
Click any chip to send it as your first message. They're there to help you discover what the AI can reach.
Notifications when you step away
The widget can notify you with a browser notification when a long AI response finishes and your tab isn't focused. First time you open the empty state, a small banner asks you to enable notifications — click Enable. You can also toggle notifications from the bell icon in the widget header at any time.
Browser notifications require OS-level permission and are skipped if the tab is currently focused.
Experimental status
Foreman Assistant is labelled Experimental everywhere — in the full-page header (orange chip) and the widget header (amber pill). This is because:
- The AI can produce inaccurate information, even when it calls real tools.
- Tool results are summarised, and summarisation can drop relevant details.
- Response quality varies by model and prompt.
- Features may change or be rolled back without notice during the experimental period.
Always verify outputs that matter — especially if you plan to act on them (push issues, remove members, bulk operations, etc.).
See Also
- Foreman Assistant Overview — capabilities and high-level tour.
- Attachments in AI Chat — uploading files for the AI to analyse.
- Slash Commands & @ Mentions — fast shortcuts, pre-built prompts, and project pinning.
- Managing Conversations — pin, archive, edit, regenerate, fork.
- AI Tools & MCP Integration — what's under the hood.