README.md

heypi

Pi-native chat agents for teams.

heypi connects one Pi agent to Slack, Discord, Telegram, local applications, or trusted webhooks. It adds conversation routing, runtime isolation, approvals, memory, attachments, schedules, and operational audit records without replacing Pi's model loop.

Documentation · Quickstart · Discord

Create an agent

npm create heypi@latest -- codex-tag my-agent
cd my-agent
cp .env.example .env
npm run dev

Use as a library

npm install @hunvreus/heypi

import { host, loadAgent, local, modelFromEnv, runHeypi } from "@hunvreus/heypi";

const agent = loadAgent("./agent", {
	model: modelFromEnv(),
	runtime: host({ workspace: "./workspace" }),
});

await runHeypi(agent, [local()]);

Set HEYPI_MODEL to a Pi model ID such as openai/gpt-5.4-mini and provide that model provider's credentials. Replace local() with Slack, Discord, Telegram, or webhook for network ingress.

Packages

• @hunvreus/heypi: agent lifecycle, adapters, approvals, and host/Docker runtimes.
• @hunvreus/heypi-runtime-just-bash: confined in-process interpreter.
• @hunvreus/heypi-runtime-gondolin: local QEMU micro-VM.
• @hunvreus/heypi-runtime-vercel: managed Vercel Sandbox.
• @hunvreus/heypi-runtime-cloudflare: Cloudflare Sandbox SDK adapter.
• create-heypi: project scaffolder.

The canonical documentation source is packages/heypi/docs. The complete hosted documentation is at heypi.dev/docs.

Development

Requires Node.js 22 or later and pnpm 10.

pnpm install
pnpm check
pnpm typecheck
pnpm test
pnpm build