How @housecall works

Someone asks an IT question in chat. @housecall searches your docs, may call a tool, and answers in the same thread with links to the pages it used.

Conversations

One chat thread is one conversation. @housecall remembers what was said earlier in it.

• Slack: every answer goes in a thread under the message. A new top-level DM starts a new conversation; replies in its thread continue it.
• Microsoft Teams: a personal chat with the app is one conversation.
• Google Chat: a DM is one conversation.

In channels and spaces, @housecall answers when mentioned, in the thread of the message.

Docs

@housecall answers from your IT docs: a folder of Markdown files, a Google Drive folder or a Confluence space. Each answer links the pages it used. If no doc covers the question, it says so instead of guessing.

It copies them into a local search index and syncs on startup and every docs.sync_interval_minutes.

Anyone who can message @housecall can read what its docs credentials can see, so give it a low-privilege account.

Screenshots

People can post screenshots with their question. @housecall downloads the images in the message it answers and shows them to the model:

• PNG, JPEG, GIF and WebP only. Other formats are noted to the model as “could not be read”.
• At most 10 MB and 25 megapixels per image, and at most 4 images per turn.
• Each is shrunk to at most 1568 px on the long edge and 1 MB, or the model’s limits if those are smaller.

Other files, such as PDFs, are named to the model but not read.

When mentioned in a Slack or Google Chat thread, @housecall also reads the images the person who mentioned it posted in that thread since its last reply. Teams has no thread history, so there the image must be in the message that mentions @housecall. Images posted by other people show as [image].

The model sees images only with the newest message. In later requests they show as [image], and the model works from what it said about them. Images are stored only in the conversation, in data/session.sqlite. A thread’s messages are handled in the order they arrive.

The model must take image input. For openai and anthropic this comes from pi-ai’s model catalog; for openai_compatible it is on unless you set model.images: false (see Configuration). Otherwise nothing is downloaded, and the model is told the person attached images it cannot see, so it can ask them to describe it.

Each platform needs permission to read files. See Slack, Microsoft Teams, and Google Chat. In the console, /image <path> [message] attaches a local image.

Tools

Tools let the model look things up or make changes. For example, a tool can:

• Check a laptop in your device management, like Kandji or Jamf, when someone says it’s slow.

• Search Jira, or open a ticket for the person asking. The starter’s src/extensions/jira.ts does this.

• Lock a lost laptop or sign someone out of Okta, once they approve it.

• Request a loaner laptop, as in the code extension example.

• Read tools, such as searching tickets, run right away.

• Write tools, such as opening a ticket, wait for approval.

Tools come from two places:

• MCP servers, listed in config/config.yaml. No code. Every MCP tool is a write tool unless you list it in read_only.
• Code extensions, TypeScript files you import in src/main.ts. You mark which tools write.

Approval

Before a write tool runs, @housecall posts a card in the thread and the requester confirms or denies it. The requester is the person whose message led to the tool call.

Approval is the requester confirming what they asked for. It is not an IT sign-off, so a write tool must act only on the requester or check permissions itself. See Approvals.

Restarts

@housecall stores conversations and approvals as it goes. After a restart or crash it picks up where it left off: unfinished answers resume, and pending approval cards still work.

Messages sent while @housecall is stopped are not answered. People need to ask again.

Where data lives

Your project and the package

Your project is the starter you cloned. You own everything in it: config, docs, extensions, and the Docker files. The engine is the @ithousecall/chat npm package, which src/main.ts starts:

import { start } from "@ithousecall/chat";
import jira from "./extensions/jira.ts";

await start({ config: "config/config.yaml", data: "data", extensions: [jira] });

To upgrade, run npm install @ithousecall/chat@latest, commit package.json and package-lock.json, and rebuild the image. Your files stay as they are. See Operations.