How Deskhand works

Someone asks an IT question in chat. Deskhand 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. Deskhand 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, Deskhand answers when mentioned, in the thread of the message.

Docs

Deskhand copies your docs sources (a local folder, a Google Drive folder, or a Confluence space) into a local search index. It syncs on startup and every docs.sync_interval_minutes. The model searches that index, and answers link to the original page.

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

Tools

Tools let the model look things up or make changes.

• 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, Deskhand 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

Deskhand 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 Deskhand 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 deskhand npm package, which src/main.ts starts:

import { start } from "deskhand";
import jira from "./extensions/jira.ts";

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

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