Bosun Documentation

An AI agent inside Odoo Community Edition: chat with your data, approve every change, run it on your own hardware or any provider.

docs build 2026-06-11 · covers bosun, bosun_discuss, bosun_accounting, bosun_tasks, bosun_inventory, bosun_purchase, bosun_sales, bosun_marketing, bosun_doc_import · Odoo 17 + 18 CE

Getting started

1. Place the bosun module (and any packs) in your addons path and install from Apps. Dependencies: base, web, mail; the Accounting pack adds account; the Work Week pack adds project, calendar; the Document Import pack adds account, purchase, sale. Every app nests under one shared Bosun menu.
2. Open Bosun → Providers and create your first provider (next section).
3. Click Test Connection. A success toast means you are live.
4. Open Bosun → Chat and click a suggested prompt.

Quick start: your first Monday

The fastest way to understand Bosun is to spend a Monday morning with it. You do not configure anything or learn commands. You sit down, open Bosun → Chat (or just DM the Bosun contact in Discuss), and talk. Bosun already knows your role from your Odoo login, and the start-of-week and start-of-month suggested prompts are waiting in an empty chat. Here is a realistic first half hour.

1. See what is actually on your plate

You start with the obvious question, and Bosun reads it straight from Odoo:

you:    What's on my plate this week?
bosun:  6 open task(s):
        #41 Rebuild wholesale pricing spreadsheet | 120m | deep | Sales
        #44 Reconcile May bank statement          | 90m  | deep | Finance
        #47 Email 3 wholesale leads               | 30m  | shallow
        ...

Anything new that comes to mind, you just say. Bosun estimates the effort and the focus type, shows a confirmation card, and files it. No form.

you:    Remind me to follow up with the label printer about the
        reprint, and I need to redo the Q2 forecast.
bosun:  Add task: "Follow up with label printer on reprint"
        about 20 min, shallow focus.        [ Approve ]  [ Change ]
        Add task: "Redo Q2 forecast"
        about 90 min, deep focus, project Finance.   [ Approve ]

2. Let Bosun lay out the week

Once the list is right, hand it the calendar. Bosun schedules deep work into your morning focus window, caps how many deep blocks land in a day, keeps lunch clear, and books around the meetings already on your calendar. You see the whole plan before a single event is created.

you:    Plan my week
bosun:  Book 5 task(s) onto your calendar:
        Mon 09:00-11:00  Rebuild wholesale pricing spreadsheet (deep)
        Tue 09:00-10:30  Reconcile May bank statement (deep)
        Tue 14:00-15:30  Redo Q2 forecast (deep)
        Mon 14:00-14:30  Email 3 wholesale leads (shallow)
        ...                            [ Approve ]  [ Deny ]

3. Work the business questions, not the menus

With the week framed, you turn to the things you would normally click through five screens for. With the Accounting pack installed, the accounting context answers from your live books:

you:    Who owes us money, oldest first, past 60 days?
bosun:  3 customers past 60 days, $14,820 total:
        Northgate Cafe   $7,300   78 days overdue
        Pier 9 Catering  $4,920   64 days overdue   [open]
        ...
you:    What's our cash position right now?
you:    Any strange-looking transactions I should review before I approve payments?

When you decide to act, the same chat does it, and the safety rail is automatic. "Mark the Northgate invoice paid" returns a card naming the exact invoice and amount; nothing moves until you approve, and every action is written to the audit log.

4. The same chat grows with you

Bosun only offers what it can actually do. Each pack you install lights up a new context and a new set of tools, while the conversation stays the same. The roadmap extends this Monday straight into operations:

Providers & models

A provider is one model endpoint. Create several and switch anytime; chats record token usage per provider.

Test Connection sends one tiny message and reports success or exactly what to fix (wrong key, unreachable server).

Using the chat

• Suggested prompts appear in an empty chat. Some are cyclical: month-end, new-month, and Friday prompts surface only in their window. Admins edit them under Bosun → Suggested Prompts.
• Tabs: switch between conversations; + New starts one. Tabs name themselves from your first message, and you can double-click a tab to rename it (Enter saves, Esc cancels).
• Context prefix (autogeneralaccountingtasksinventorypurchasesalesmarketing): a compact chip at the left of the message box scopes which tools the model sees, which keeps it sharp. In auto, Bosun routes each question itself and the chip shows the chosen category with (auto) beneath it. Click the chip to pin a context; a clearly off-topic question still switches ("add X to my tasks" works from any context) and the pinned context catches everything else. general is the exception: pinning it strictly limits Bosun to the core tools. Suggested prompts follow the active context. Contexts appear as their packs are installed.
• Slash commands: type / in the message box to switch context fast: an autocomplete lists the contexts (/inventory, /sales, …); Tab or Enter completes it. The slash only sets the context; it is not sent as a message.
• find_product (free, core): ask for a product by a loose name or code from any context ("find the 4oz 3-pack") and Bosun resolves it (id, sale price, cost, and on-hand), so you never have to type the exact name.
• It finds the data, you do not name the table (free, core): you never need to know Odoo's technical model names. Ask "how are the email campaigns doing?" and Bosun looks up the right model itself (discover_model) instead of guessing or giving up.
• It follows you: Bosun also lives as a native Discuss chat window. See The co-pilot chat.

The co-pilot chat (Discuss)

Click the gold compass in the top bar and Bosun opens as a native Discuss chat window: it floats over every screen, follows you as you navigate, and persists like any other chat. Same agent, same permissions, same approval rules. The full-screen page stays available under the Bosun menu.

• It knows what you are looking at. Open a sales order and ask "who is the customer on this?" or "mark this paid": "this" means the record on your screen.
• Open it for me. Ask Bosun to "open", "show me", or "pull up" a record or a filtered list and your main screen navigates there while the chat stays put.
• Approvals stay in the chat. A proposed change shows an Approve / Deny card right inside the window, token-bound to the exact change shown. Nothing runs until you approve.
• Drop a file, get a draft. Attach a PDF or a phone photo of an invoice (the paperclip; on mobile that includes the camera) and say what it is: "vendor bill from Acme". Bosun acknowledges immediately, reads it out-of-band with the Document Import pack, and posts the draft Vendor Bill / Purchase Order / Sale Order back into the chat when it is ready, then opens it for review. If you do not say the type, it asks. Chat drops only ever create DRAFTS: a "receipt" becomes a draft bill, never an auto-posted payment. iPhone HEIC photos are handled (install pillow-heif on the server).
• Slash commands. Type / in the chat: /new starts a fresh conversation (also in the window's menu as "New Bosun conversation"); /help lists what Bosun can do.
• Shortcuts. Type :campaigns, :lowstock, :late, or :cash and it expands to a full question.
• Voice messages record and play back as audio (native Discuss); Bosun does not transcribe them yet.

Requires the Bosun Discuss module; the file-drop lane needs the Document Import pack (a bridge module installs itself when both are present and runs the queue as you, with your own access rights).

Approvals & audit

The trust rules are enforced in code, not in a prompt:

• Reads answer instantly. Bosun acts with your own Odoo permissions, never above them.
• Writes always stop at a card stating the exact change. The card is token-bound: what you approve is what runs. For money flows the proposal pins the exact record and amount at proposal time; if anything changes before you click Approve, execution refuses.
• Everything lands in the audit log (Bosun → Action Log): who asked, what ran, what changed, who approved, token cost. Log rows cannot be forged or edited by users.
• If you ignore a card and keep typing, the proposal is auto-declined and recorded. Reopening a chat re-shows an unanswered card.

Accounting pack paid

Conversational accounting over your live books. Sample prompts:

• "What was our biggest expense this month?"
• "Any strange-looking transactions I should review?" (vendor-history outliers, possible duplicates, round numbers, first bills from new vendors)
• "Who owes us money past 60 days?" · "What is our cash position?" · "Which vendors did we spend the most with?"
• "Mark the Stone Brewing bill paid": Bosun finds the bill, shows a card with the exact bill number and amount, and registers the payment only on your approval.

Inventory & Purchase packs paid

The supply chain, conversationally. Two packs that install separately and link up on their own (receiving a PO crosses both; the bridge installs itself when both sides are present). Sample prompts:

• "What's running low right now?" (reorder rules plus negative forecasts) · "How much corn do we have on hand?" · "What receipts are expected this week?" · "Trace where that lot went"
• "Which purchase orders are late?" · "Where's my order from M-Star?" (line by line, with received quantities) · "What do we pay Pacific Packaging for the large bags?"
• "Order 50 cases of corn from M-Star": Bosun resolves the vendor and every product, shows the resolved lines on a card (anything it could not match is flagged as skipped), and creates a draft RFQ on approval. Confirming the order and emailing it to the vendor are separate approvals; the email card names the exact recipient address.
• "The M-Star shipment arrived, two boxes short on bags": Bosun finds the open receipt, shows every line with the shortfall applied, asks create-backorder or skip, and validates only what you approved. If the receipt changed between the card and your click, it refuses and asks again.
• "Reorder everything below minimum": replenishment runs; the resulting RFQs stay in draft for review.
• "Zero out the quantity on hand for ICE, BAG-C4 and BAG-C10": Bosun resolves each product, shows a single card listing every one with its current count and the new target, and on one approval performs a real inventory adjustment for all of them. Zeroing with no location named clears every internal location holding the product.

Sales pack paid

Conversational pricing. Sets a product's own prices, and is careful to keep them distinct from pricelist rules.

• "Change the sale price of the 4oz 3-Pack to $27": Bosun resolves the product, shows a card with the current price and the new one, and writes the Sales Price (list_price) on approval. If the price moved since the card, it refuses and asks again.
• "Set the cost of the large printed bags to $0.45": writes the Cost (standard_price); under Average Costing this is valuation-sensitive and the card says so.
• These are the product's OWN Sales Price and Cost, not a pricelist item (a customer or quantity specific rule), which is a separate record.

Marketing pack paid

Your email marketing, answered in plain language from Odoo's Email Marketing app. Read-only: it reports on campaigns and audiences, it does not send. Sample prompts:

• "How are the recent email campaigns doing?": one line per campaign, newest first, with how many were sent and the open, click, and bounce rates.
• "Which campaign had the best open rate?" · "How did the July 4th email do?" (full stats for one campaign: recipients, sent, delivered, opened, clicked, replied, bounced, and the rates).
• "How big is each mailing list?" · "How many subscribers do we have?" (each audience with its contact, emailable, and opted-out counts).

Campaign statistics are named differently across Odoo versions; the pack reads whatever your version exposes, so the numbers are right whether you are on 17 or 18, where a hand-written query would break.

Document Import pack paid

Turn a PDF or a phone photo of a business document into a draft Odoo record. You upload the file under Bosun → OCR, a vision-capable model reads it, pulls out the structured fields, and builds a draft you review before anything posts.

1. Scan: PDFs with a real text layer are read directly; true scans and photos go to the vision model, tiled so even large pages stay within GPU limits.
2. Extract: partner, reference, date, and line items come back as structured data, with a buyer/seller hint that decides the document type.
3. Create: a draft Purchase Order, Sale Order, or Vendor Bill, matching or creating the partner and matching each product from a token-searched shortlist (with plural tolerance). The original file is attached to the new record's chatter for verification. A receipt that was already paid can be posted and paid in one step from a chosen "Paid With" journal.

It runs on any OpenAI-compatible vision endpoint (local llama.cpp / Ollama, OpenAI, OpenRouter). PDF support needs pip3 install PyMuPDF on the Odoo host; images work without it. Steps run from buttons, or unattended on a bundled cron (off by default).

Landed costs (auto-install bridge). When a document states extra charges (freight, handling, marketplace fees), the bridge drafts a stock.landed.cost the moment the purchase receipt is validated: one cost line per charge, the landed-cost product chosen by the model from your landed_cost_ok shortlist, left in draft for a human to validate. A per-vendor marketplace fee percent (for example an Alibaba transaction fee) can default from the vendor and apply per PO. The bridge installs itself only when both Document Import and Landed Costs are present.

Work Week pack paid

Throw tasks at Bosun in plain language. It guesses the effort in minutes, the energy (deep focus vs shallow routine), and a project; the approval card shows the guesses; approve or tell it what to change. Then:

you:    Plan my week
bosun:  Book 5 task(s) onto your calendar:
        Wed 09:00–11:00  Rebuild wholesale pricing spreadsheet (deep)
        Thu 09:00–10:30  Reconcile May bank statement (deep)
        ...                       [ Approve ]  [ Deny ]

The scheduler honors your presets, set per user (Settings → Users → Bosun tab):

It schedules around existing calendar events, books tagged events, and never double-books a task. Cycle prompts drive the rhythm: "Plan my week" surfaces at month start, the Friday review (what gets punted, what moves to Monday) at week's end.

Administration

• User profiles (Settings → Users → Bosun tab): a company role and typical workflows, injected into every conversation so answers fit the person. If the role is blank, Bosun infers it from the user's access groups, and it always enriches with observed usage ("mostly anomaly_scan, aging_followups").
• Usage (Bosun → Usage): a pivot of users × weeks × tokens and a graph of calls per tool. Adoption and cost at a glance, no external services.
• Suggested Prompts (Bosun → Suggested Prompts): inline-editable list with ordering, category, and cycle (always / end of week / start or end of month / quarter / December).
• Privacy model: users see only their own conversations; admins see the full audit log but not other people's chats.

Retention: Bosun forgets on your schedule

Transcripts are working chatter; the audit log is the record. They age on separate clocks:

Conversations holding an unanswered approval card are never purged, and every purge is itself an audit entry.

Discuss bridge

DM the Bosun contact in Odoo Discuss from any screen, desktop or mobile. The docked chat window persists while you navigate, replies can deep-link you to records, and anything needing approval hands off to the Bosun panel where the card is waiting. Discuss messages follow the same retention schedule as other transcripts.

Questions, pilot access, or a missing page: hello@practicalbusinessmachines.com