{"id":49852329,"url":"https://github.com/yourpapai/papai","last_synced_at":"2026-05-16T18:10:34.608Z","repository":{"id":341746964,"uuid":"1171287587","full_name":"yourpapai/papai","owner":"yourpapai","description":"Proactive personal AI agent with scheduled nudges, smart suggestions, and context-aware assistance","archived":false,"fork":false,"pushed_at":"2026-05-14T07:55:57.000Z","size":10640,"stargazers_count":7,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-14T09:50:34.975Z","etag":null,"topics":["ai-agent","bun","cron","drizzle-orm","event-driven","grammyjs","llm","personal-assistant","proactive-ai","productivity","rrule","self-hosted","sqlite","telegram-bot","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yourpapai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-03T04:07:46.000Z","updated_at":"2026-05-14T07:56:00.000Z","dependencies_parsed_at":"2026-04-01T21:01:57.050Z","dependency_job_id":"cf3dc591-0723-4b81-88f7-3779fb9edb82","html_url":"https://github.com/yourpapai/papai","commit_stats":null,"previous_names":["wkich/papai","yourpapai/papai"],"tags_count":80,"template":false,"template_full_name":null,"purl":"pkg:github/yourpapai/papai","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yourpapai%2Fpapai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yourpapai%2Fpapai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yourpapai%2Fpapai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yourpapai%2Fpapai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yourpapai","download_url":"https://codeload.github.com/yourpapai/papai/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yourpapai%2Fpapai/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33034788,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T13:14:54.681Z","status":"online","status_checked_at":"2026-05-14T02:00:06.663Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","bun","cron","drizzle-orm","event-driven","grammyjs","llm","personal-assistant","proactive-ai","productivity","rrule","self-hosted","sqlite","telegram-bot","typescript"],"created_at":"2026-05-14T17:05:20.425Z","updated_at":"2026-05-14T17:05:23.624Z","avatar_url":"https://github.com/yourpapai.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PAPAI — Personal Adroit Proactive AI\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/logo.png\" alt=\"PAPAI logo\" width=\"600\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003eNatural language task management for Telegram, Mattermost, and Discord\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/yourpapai/papai/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/yourpapai/papai/ci.yml?branch=master\u0026label=CI\u0026style=flat-square\" alt=\"CI Status\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/yourpapai/papai/security\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/yourpapai/papai/ci.yml?branch=master\u0026label=CodeQL\u0026style=flat-square\u0026logo=github\" alt=\"CodeQL\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/yourpapai/papai?style=flat-square\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://bun.sh\"\u003e\u003cimg src=\"https://img.shields.io/badge/bun-1.3%2B-black?style=flat-square\u0026logo=bun\" alt=\"Bun Runtime\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#quick-start\"\u003eQuick Start\u003c/a\u003e ·\n  \u003ca href=\"#features\"\u003eFeatures\u003c/a\u003e ·\n  \u003ca href=\"#architecture\"\u003eArchitecture\u003c/a\u003e ·\n  \u003ca href=\"#configuration\"\u003eConfiguration\u003c/a\u003e ·\n  \u003ca href=\"#deployment\"\u003eDeployment\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Features](#features)\n- [Quick Start](#quick-start)\n- [Architecture](#architecture)\n- [Configuration](#configuration)\n- [Usage](#usage)\n- [Development](#development)\n- [Testing](#testing)\n- [Deployment](#deployment)\n- [License](#license)\n\n## Overview\n\nPapai (**P**ersonal **A**droit **P**roactive **AI**) is a chat bot that enables natural language task management through any OpenAI-compatible LLM. Deploy it on Telegram, Mattermost, or Discord, connect it to Kaneo or YouTrack, and manage work through conversational task operations.\n\nThe bot interprets natural-language requests, invokes capability-gated tools through LLM tool-calling, and replies with task details, updates, summaries, and search results. Personal settings remain user-scoped, while DM `/setup` and `/config` can also target shared group settings for groups the user manages. Conversation history, memory, and memo storage are isolated by storage context. Telegram forum topics and Mattermost threads get separate thread-scoped context; Discord currently does not.\n\n---\n\n## Features\n\n| Category             | Capability                                      | Description                                                          |\n| -------------------- | ----------------------------------------------- | -------------------------------------------------------------------- |\n| **Tasks**            | Create, Update, Search, List, Get, Delete       | Full task lifecycle through natural language                         |\n| **Comments**         | Add, Read, Update, Delete, Reactions            | Task discussions with provider-specific reactions                    |\n| **Relations**        | Blocks, Duplicates, Related, Subtask            | Cross-task dependencies and associations                             |\n| **Projects**         | List, Create, Update, Delete, Team              | Workspace organization and team management                           |\n| **Statuses**         | CRUD, Reorder                                   | Board/status column management                                       |\n| **Labels**           | List, Create, Update, Delete, Assign            | Categorization and filtering                                         |\n| **Attachments**      | List, Upload, Remove                            | Attach task files directly from chat messages where supported        |\n| **Collaboration**    | Watchers, Votes, Visibility                     | Provider-dependent coordination surfaces                             |\n| **Work Tracking**    | Count tasks, log work, update work, remove work | Task counts and time tracking where supported                        |\n| **Identity**         | Link chat identity to tracker identity          | Enables reliable “assign to me” and similar flows in groups          |\n| **History**          | Thread-aware chat history lookup                | Search the main group chat from a thread when more context is needed |\n| **Web Fetch**        | Public URL fetch, summary, excerpt              | Fetch and summarize public web pages and PDFs                        |\n| **Memory**           | Conversation history, summary, facts            | Context-aware multi-turn interactions                                |\n| **Memos**            | Save, search, list, promote                     | Quick notes with keyword or semantic lookup                          |\n| **Recurring Tasks**  | Template schedules                              | Reusable recurring task automation                                   |\n| **Deferred Prompts** | One-shot, delayed, cron                         | Scheduled proactive assistance                                       |\n| **Instructions**     | Context-specific guidance                       | Per-chat custom instructions                                         |\n\n### Platform Support\n\n| Platform       | Group Message Model                | Threads                                                                  | Command Menu | Buttons      | File Receive | File Replies | Notes                                                                                      |\n| -------------- | ---------------------------------- | ------------------------------------------------------------------------ | ------------ | ------------ | ------------ | ------------ | ------------------------------------------------------------------------------------------ |\n| **Telegram**   | Sees group messages directly       | Forum topics supported and can create a topic on mention in forum groups | Yes          | Yes          | Yes          | Yes          | Best support for bot command menus and forum-topic flows                                   |\n| **Mattermost** | Sees group messages directly       | Thread/root-post aware                                                   | No           | No callbacks | Yes          | Yes          | Username resolution supported                                                              |\n| **Discord**    | DMs plus guild-channel `@mentions` | No separate thread-scoped support today                                  | No           | Yes          | No           | No           | Uses embeds for rich `/context` output; requires Message Content intent for content access |\n\n### Task Provider Support\n\n| Provider     | Auto-Provisioning | Relations | Statuses | Labels | Comments | Reactions | Team | Watchers / Votes / Visibility | Attachments | Work Items | Count |\n| ------------ | ----------------- | --------- | -------- | ------ | -------- | --------- | ---- | ----------------------------- | ----------- | ---------- | ----- |\n| **Kaneo**    | Yes               | Yes       | Yes      | Yes    | Yes      | No        | No   | No                            | No          | No         | No    |\n| **YouTrack** | No                | Yes       | Yes      | Yes    | Yes      | Yes       | Yes  | Yes                           | Yes         | Yes        | Yes   |\n\nYouTrack task creation can require workflow-specific custom fields. Papai exposes a `customFields` input on task creation for those project-specific requirements.\n\n---\n\n## Quick Start\n\n### Prerequisites\n\n- [Bun](https://bun.sh) 1.3+\n- One supported chat platform: Telegram, Mattermost, or Discord\n- One supported task provider: Kaneo or YouTrack\n- OpenAI-compatible API credentials for your chosen model provider\n\n### 30-Second Setup\n\n```bash\ngit clone https://github.com/yourpapai/papai.git\ncd papai\nbun install\ncp .env.example .env\n```\n\nEdit `.env`:\n\n```bash\n# Required for all setups\nCHAT_PROVIDER=telegram          # or: mattermost, discord\nTASK_PROVIDER=kaneo             # or: youtrack\nADMIN_USER_ID=123456789         # Your platform user ID\n\n# Platform-specific\nTELEGRAM_BOT_TOKEN=your_token_here\n\n# Provider-specific\nKANEO_CLIENT_URL=https://kaneo.example.com\n```\n\nStart the bot:\n\n```bash\nbun start\n```\n\nThen configure runtime settings in chat:\n\n1. DM the bot and run `/setup`\n2. Complete the wizard for personal settings\n3. Use `/config` later to review or edit settings\n\nFor groups, run `/setup` or `/config` in DM and choose either personal settings or one of the groups you manage.\n\n---\n\n## Architecture\n\n```mermaid\nflowchart TD\n    Runtime[src/index.ts] --\u003e CP[ChatProvider]\n    Runtime --\u003e Debug[Optional Debug Server + Dashboard]\n    User[User\u003cbr\u003eTelegram / Mattermost / Discord] --\u003e|Message or interaction| CP\n    CP --\u003e|IncomingMessage / IncomingInteraction| Bot[bot.ts]\n    Bot --\u003e|intercepts setup/config/group-selector flows| Intercept[Wizard + Config Editor + Group Settings]\n    Bot --\u003e|queued prompt + reply context + attachment ids| Queue[Message Queue + Attachment Workspace]\n    Queue --\u003e LLM[LLM Orchestrator]\n    LLM --\u003e Tools[Capability-gated Tool Registry]\n    Tools --\u003e Providers[Task Providers]\n    Providers --\u003e APIs[Task Tracker APIs]\n    Tools --\u003e Web[Web Fetch / Extraction]\n    LLM --\u003e CP\n    CP --\u003e User\n```\n\n### Component Overview\n\n| Path                             | Responsibility                                                                             |\n| -------------------------------- | ------------------------------------------------------------------------------------------ |\n| `src/index.ts`                   | Entry point, env validation, startup, scheduler and optional debug server wiring           |\n| `src/bot.ts`                     | Platform-agnostic message handling, interception, queueing, and interaction routing        |\n| `src/chat/`                      | Telegram, Mattermost, and Discord adapters plus capability metadata                        |\n| `src/llm-orchestrator.ts`        | LLM tool-calling orchestration                                                             |\n| `src/tools/`                     | Context-aware, capability-gated tool assembly                                              |\n| `src/providers/`                 | Kaneo and YouTrack provider adapters                                                       |\n| `src/identity/`                  | Chat-to-provider identity mapping and “me” resolution                                      |\n| `src/attachments/`               | Durable attachment workspace: ingest, S3 blob store, metadata, manifest building, resolver |\n| `src/message-queue/`             | Message coalescing and orderly LLM dispatch                                                |\n| `src/group-settings/`            | DM-driven selection of personal vs group configuration targets                             |\n| `src/web/`                       | Safe fetch, extraction, distillation, caching, and rate limiting for `web_fetch`           |\n| `src/debug/` and `client/debug/` | Optional local debug server and dashboard UI                                               |\n\n---\n\n## Configuration\n\n### Environment Variables\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eRequired Variables\u003c/b\u003e (click to expand)\u003c/summary\u003e\n\n| Variable        | Description                       | Example                                            |\n| --------------- | --------------------------------- | -------------------------------------------------- |\n| `CHAT_PROVIDER` | Chat platform                     | `telegram`, `mattermost`, or `discord`             |\n| `ADMIN_USER_ID` | Initial authorized admin identity | Platform user ID string seen by the active adapter |\n| `TASK_PROVIDER` | Task tracker backend              | `kaneo` or `youtrack`                              |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eTelegram Configuration\u003c/b\u003e\u003c/summary\u003e\n\n| Variable             | Description                                         |\n| -------------------- | --------------------------------------------------- |\n| `TELEGRAM_BOT_TOKEN` | Bot token from [@BotFather](https://t.me/BotFather) |\n\nTo find your Telegram numeric user ID, message [@userinfobot](https://t.me/userinfobot) and copy the returned value into `ADMIN_USER_ID`.\n\nFor Mattermost and Discord, use the platform user ID string the bot receives, not a display name or `@username`.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eMattermost Configuration\u003c/b\u003e\u003c/summary\u003e\n\n| Variable               | Description         |\n| ---------------------- | ------------------- |\n| `MATTERMOST_URL`       | Mattermost base URL |\n| `MATTERMOST_BOT_TOKEN` | Bot account token   |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eDiscord Configuration\u003c/b\u003e\u003c/summary\u003e\n\n| Variable            | Description                                 |\n| ------------------- | ------------------------------------------- |\n| `DISCORD_BOT_TOKEN` | Bot token from the Discord developer portal |\n\nDiscord support uses gateway intents including `MessageContent`. Enable the **Message Content Intent** for the bot in the Discord developer portal if you expect the bot to read message content beyond explicit interaction payloads. Verified applications must also enable the privileged Message Content intent in the portal for non-empty content, attachments, embeds, and similar fields.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eKaneo Configuration\u003c/b\u003e\u003c/summary\u003e\n\n| Variable             | Description                                        |\n| -------------------- | -------------------------------------------------- |\n| `KANEO_CLIENT_URL`   | Public Kaneo client URL                            |\n| `KANEO_INTERNAL_URL` | Optional internal API URL for bot-to-Kaneo traffic |\n\nKaneo can auto-provision user accounts for the bot workflow. In self-hosted deployments, `docker-compose.yml` also expects Kaneo-specific database/auth variables such as `KANEO_POSTGRES_PASSWORD` and `KANEO_AUTH_SECRET`.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eYouTrack Configuration\u003c/b\u003e\u003c/summary\u003e\n\n| Variable       | Description           |\n| -------------- | --------------------- |\n| `YOUTRACK_URL` | YouTrack instance URL |\n\nRuntime setup still requires a per-user `youtrack_token`, configured through the bot.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eOptional Debug Server\u003c/b\u003e\u003c/summary\u003e\n\n| Variable         | Description                                        |\n| ---------------- | -------------------------------------------------- |\n| `DEBUG_SERVER`   | Set to `true` to start the local debug server      |\n| `DEBUG_HOSTNAME` | Debug server bind host (default `127.0.0.1`)       |\n| `DEBUG_PORT`     | Debug server bind port (default `9100`)            |\n| `DEBUG_TOKEN`    | Optional bearer token required for debug endpoints |\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eFile Attachments (S3-compatible Object Storage)\u003c/b\u003e\u003c/summary\u003e\n\nRequired when the bot needs to receive, persist, or attach files to tasks.\n\n| Variable               | Required | Description                                                           |\n| ---------------------- | -------- | --------------------------------------------------------------------- |\n| `S3_BUCKET`            | Yes      | S3 bucket name where attachment objects are stored                    |\n| `S3_ACCESS_KEY_ID`     | Yes      | Access key for the S3-compatible service                              |\n| `S3_SECRET_ACCESS_KEY` | Yes      | Secret key for the S3-compatible service                              |\n| `S3_ENDPOINT`          | No\\*     | Endpoint URL. Required for non-AWS providers such as MinIO, R2, or B2 |\n| `S3_REGION`            | No       | AWS region (e.g. `us-east-1`)                                         |\n| `S3_PREFIX`            | No       | Optional key prefix inside the bucket                                 |\n| `S3_FORCE_PATH_STYLE`  | No       | Set to `true` for MinIO                                               |\n\n\u003c/details\u003e\n\n### Runtime Configuration\n\nUse the bot’s DM-based configuration flow:\n\n| Command    | Description                                                            |\n| ---------- | ---------------------------------------------------------------------- |\n| `/setup`   | Run the guided configuration wizard                                    |\n| `/config`  | View current settings and edit fields interactively where supported    |\n| `/clear`   | Clear conversation history, summary, and facts for the current context |\n| `/context` | View the current LLM context window for this conversation              |\n\nRuntime keys shown by `/setup` and `/config` include:\n\n| Key               | Description                                                 |\n| ----------------- | ----------------------------------------------------------- |\n| `llm_apikey`      | LLM provider API key                                        |\n| `llm_baseurl`     | OpenAI-compatible base URL                                  |\n| `main_model`      | Main model used for task orchestration                      |\n| `small_model`     | Smaller model used by features such as group-history lookup |\n| `embedding_model` | Embedding model for semantic memo search                    |\n| `kaneo_apikey`    | Kaneo API key or session token                              |\n| `youtrack_token`  | YouTrack permanent token                                    |\n| `timezone`        | User timezone for local date/time interpretation            |\n\n---\n\n## Usage\n\nSend natural-language requests to the bot.\n\n**Task Management**\n\n- \"Create a high-priority bug: login crashes on Safari\"\n- \"Move task 42 to In Progress\"\n- \"Show me task PROJ-55\"\n- \"Delete task 42\"\n\n**Comments and Relations**\n\n- \"Add a comment to task 42: waiting for API changes\"\n- \"Show all comments on task 55\"\n- \"Create a blocks relation: task 42 blocks task 55\"\n\n**Identity and Assignment**\n\n- \"I'm jsmith\"\n- \"Assign this to me\"\n- \"Add me as a watcher\"\n\n**Attachments and Web Fetch**\n\n- Send a file with: \"Attach this screenshot to task 42\"\n- \"Fetch https://example.com/release-notes and summarize the breaking changes\"\n\n**Memos and History**\n\n- \"Save a memo: renew the SSL certificate before Friday\"\n- \"Search my memos for certificate\"\n- \"Look up what we decided about alert thresholds in the main chat\"\n\n### Group Chat\n\nAdd the bot to a Telegram group, Mattermost channel, or Discord server/channel.\n\nTypical flow:\n\n1. Add the bot to the group or channel\n2. A group admin authorizes members with `/group adduser \u003c@username\u003e` or an explicit user ID\n3. Group admins configure group settings from DM using `/setup` or `/config`\n4. Members interact in-group, usually by mention where the platform requires it\n\nImportant behavior:\n\n- Telegram and Mattermost can observe regular group messages; Discord group use is mention-driven.\n- Group configuration is DM-only. `/setup` and `/config` in groups redirect admins to DM.\n- Thread contexts are isolated. In Telegram forum topics and Mattermost threads, the bot stores thread-scoped history separately from the main group chat.\n- In thread-scoped group contexts, the bot can use `lookup_group_history` to search the main group discussion when needed.\n\n---\n\n## Development\n\nAll commands can be run as `bun \u003cscript\u003e` or `bun run \u003cscript\u003e`.\n\n```bash\n# App and debug UI\nbun start\nbun start:debug\nbun build:client\n\n# Code quality\nbun lint\nbun lint:fix\nbun lint:agent-strict -- src/file.ts tests/file.test.ts\nbun format\nbun format:check\nbun typecheck\nbun knip\nbun duplicates\n\n# Security\nbun security\nbun security:ci\n\n# Testing\nbun test\nbun test:client\nbun test:watch\nbun test:coverage\nbun test:e2e\nbun test:e2e:watch\nbun test:mutate\nbun test:mutate:changed\nbun test:mutate:full\n\n# Composite checks\nbun check\nbun check:full\nbun check:verbose\nbun fix\n\n# Release helpers\nbun changelog:preview\nbun changelog:generate\n```\n\nNotes:\n\n- `bun start` builds the dashboard client first, then starts the bot.\n- `bun start:debug` also enables the local debug server.\n- `bun test` excludes client and E2E suites; run `bun test:client` and `bun test:e2e` separately.\n- `bun check` runs staged-file checks, while `bun check:full` runs the wider repo checks.\n\n---\n\n## Testing\n\n### Unit and Integration Tests\n\n```bash\nbun test\n```\n\nRuns the curated main Bun test suites defined in `package.json` for the repo’s non-client, non-E2E areas.\n\n### Client Tests\n\n```bash\nbun test:client\n```\n\nRuns debug dashboard UI tests under `tests/client/` with happy-dom.\n\n### E2E Tests\n\n```bash\nbun test:e2e\n```\n\nRuns the Docker-backed Kaneo end-to-end suite.\n\n### Mutation Testing\n\n```bash\nbun test:mutate:changed\n```\n\nRuns incremental mutation testing with Stryker. Full mutation runs are also available via `bun test:mutate` and `bun test:mutate:full`.\n\n---\n\n## Deployment\n\n### Docker Compose (Recommended for self-hosted Kaneo deployments)\n\nThe repository includes a production-oriented `docker-compose.yml` that runs:\n\n- `papai`\n- Kaneo API and web\n- PostgreSQL\n- a one-shot Kaneo DB fix container\n- Caddy for TLS and reverse proxying\n\nMinimal example:\n\n```yaml\nservices:\n  papai:\n    image: ghcr.io/yourpapai/papai:latest\n    environment:\n      CHAT_PROVIDER: telegram\n      TASK_PROVIDER: kaneo\n      ADMIN_USER_ID: '123456789'\n      TELEGRAM_BOT_TOKEN: ${TELEGRAM_BOT_TOKEN}\n      KANEO_CLIENT_URL: https://kaneo.example.com\n```\n\nFor a real deployment, prefer the checked-in `docker-compose.yml` and `.env.example` together, because the full stack is Kaneo-specific and also needs Kaneo database/auth settings. For YouTrack deployments, you typically run `papai` against an external YouTrack instance instead of this full bundled stack.\n\n### GitHub Actions Deployment\n\nThe repo currently uses:\n\n- `release.yml` to bump version, update `package.json`, generate `CHANGELOG.md`, and create a GitHub release\n- `deploy.yml` to build/push the container and deploy over SSH on version tags or successful release workflow completion\n\nCurrent deployment automation is opinionated for the Telegram + Kaneo production path. If you deploy Mattermost, Discord, or YouTrack in production, adapt the workflow and `.env` generation accordingly.\n\n### Manual (Bare Metal)\n\n```bash\ngit clone https://github.com/yourpapai/papai.git\ncd papai\nbun install\ncp .env.example .env\n# Edit .env\nbun start\n```\n\nIf you want the local debug dashboard too:\n\n```bash\nbun start:debug\n```\n\n---\n\n## Tech Stack\n\n- **Runtime:** [Bun](https://bun.sh) 1.3+\n- **Language:** TypeScript (strict mode)\n- **Validation:** [Zod](https://zod.dev) v4\n- **LLM Integration:** [Vercel AI SDK](https://sdk.vercel.ai)\n- **Chat Platforms:** [Grammy](https://grammy.dev), Mattermost REST/WebSocket, [discord.js](https://discord.js.org)\n- **Task Trackers:** Kaneo REST API, YouTrack REST API\n- **Database:** SQLite with Drizzle ORM\n- **Web Extraction:** defuddle, linkedom, unpdf\n- **Linting / Formatting:** oxlint, oxfmt\n- **Security:** Semgrep\n- **Testing:** Bun Test, happy-dom, Stryker, Docker-backed E2E\n\n---\n\n## License\n\n[MIT](LICENSE) © 2026 Dmitriy Lazarev\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyourpapai%2Fpapai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyourpapai%2Fpapai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyourpapai%2Fpapai/lists"}