Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/hunvreus/heypi/llms.txt

Use this file to discover all available pages before exploring further.

Heypi is a TypeScript SDK that gives Pi a production chat shell. You write a single Node.js process; Heypi connects it to Slack, Discord, Telegram, or webhooks and handles everything that vanilla Pi leaves to you—thread persistence, human approvals, scoped file sandboxes, scheduled turns, and an admin panel. If you have ever prototyped an AI agent that fell apart the moment it reached real users, Heypi fills that gap.

​
The Problems Heypi Solves

Raw language-model agents work great in a notebook and break down in production for three predictable reasons:
  • No persistence. Every message starts a fresh context; the agent forgets who it is talking to.
  • No safety rails. Nothing stops the agent from running a destructive shell command or leaking files to the wrong channel.
  • No operational visibility. You cannot see what the agent is doing, pause a risky action, or audit what ran and when.
Heypi is designed around those three failure modes. Threads persist in SQLite. Tools run inside scoped sandboxes. Every tool call that matters can pause for a human approval before it executes.

​
Architecture at a Glance

One Node.js process hosts the entire app. Inside that process:
  • Adapters accept inbound messages from Slack, Discord, Telegram, or HTTP webhooks and route them to the handler.
  • The handler resolves the conversation thread, queues the turn, and forwards it to a Pi agent session.
  • SQLite state stores threads, messages, turns, approval records, and scheduled-job state under a single state.root directory you configure.
  • Scoped runtimes give each channel (or user, adapter, or agent) its own sandboxed workspace for file and shell operations.
┌─────────────────────────────────────────────────────────┐
│                    Node.js process                       │
│                                                          │
│  Slack ──┐                                               │
│  Discord ─┤── Adapters ── Handler ── Pi Agent session    │
│  Telegram ┤              │                               │
│  Webhook ─┘          SQLite state                        │
│                      Scoped runtimes                     │
└─────────────────────────────────────────────────────────┘

​
Packages

PackagePurpose
@hunvreus/heypiCore SDK: adapters, agent runtime, approvals, scheduling, store
@hunvreus/heypi-runtime-dockerExperimental: Docker container runtime provider
@hunvreus/heypi-runtime-gondolinExperimental: lightweight VM runtime provider
The core package is stable and self-contained. The two runtime packages are experimental previews for teams that need stronger sandbox isolation than the built-in just-bash runtime provides.

​
Requirements

Heypi requires Node.js 22 or newer. Document conversion (PDF, Office files) requires Python 3 with uv or with MarkItDown pre-installed.

​
Features

Multi-Platform Adapters

Built-in adapters for Slack (Socket Mode and HTTP), Discord, Telegram, and webhooks. All share the same approval, streaming, and busy-thread behavior.

Sandboxed Tools

The built-in just-bash runtime isolates every shell and file call to a scoped workspace. Docker and Gondolin providers add container- and VM-level isolation.

Human Approval Flows

Any tool call can pause for a named approver before it executes. Slack, Telegram, and Discord render native approval buttons; approvals are in-place and resume the turn transparently.

Scheduled Jobs

cron jobs run on a wall-clock schedule. heartbeat jobs sweep known chats after a configurable idle window—useful for daily check-ins or proactive follow-ups.

Scoped Memory

Persistent model context scoped to a channel, user, adapter, or agent. Write policy is configurable: auto, approvers-only, or off.

Admin UI

A local admin panel for inspecting threads, approvals, and scheduled jobs. Enable with admin: true in your config.

​
Next Steps

Quickstart

Install Heypi, create an agent folder, and run your first Slack agent in under five minutes.

Agent Folder

Learn the SOUL.md and AGENTS.md conventions and how to inject dynamic context.

Tools & Approvals

Add custom tools, configure sandbox rules, and route risky commands to human approvers.

Adapters

Configure Slack, Discord, Telegram, and webhook adapters with per-channel allow lists and streaming.

Build docs developers (and LLMs) love

Get started for freeTalk to us