{"id":47000016,"url":"https://github.com/wkich/papai","last_synced_at":"2026-04-18T13:04:58.271Z","repository":{"id":341746964,"uuid":"1171287587","full_name":"wKich/papai","owner":"wKich","description":"Proactive personal AI agent with scheduled nudges, smart suggestions, and context-aware assistance","archived":false,"fork":false,"pushed_at":"2026-04-14T19:00:04.000Z","size":7231,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-14T21:04:01.655Z","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/wKich.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-04-14T19:00:16.000Z","dependencies_parsed_at":"2026-04-01T21:01:57.050Z","dependency_job_id":"cf3dc591-0723-4b81-88f7-3779fb9edb82","html_url":"https://github.com/wKich/papai","commit_stats":null,"previous_names":["wkich/papai"],"tags_count":75,"template":false,"template_full_name":null,"purl":"pkg:github/wKich/papai","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wKich%2Fpapai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wKich%2Fpapai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wKich%2Fpapai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wKich%2Fpapai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wKich","download_url":"https://codeload.github.com/wKich/papai/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wKich%2Fpapai/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31969779,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T00:39:45.007Z","status":"online","status_checked_at":"2026-04-18T02:00:07.018Z","response_time":103,"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-03-11T17:03:31.929Z","updated_at":"2026-04-18T13:04:58.258Z","avatar_url":"https://github.com/wKich.png","language":"TypeScript","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 and Mattermost\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/wKich/papai/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/wKich/papai/ci.yml?branch=master\u0026label=CI\u0026style=flat-square\" alt=\"CI Status\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/wKich/papai/security\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/wKich/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/wKich/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.11-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 or Mattermost, connect to Kaneo or YouTrack task trackers, and manage your team's work through conversational interfaces.\n\nThe bot interprets natural language requests, invokes appropriate operations through LLM tool-calling, and responds with task status, updates, and search results. Each user maintains isolated credentials, conversation history, and long-term memory for context-aware interactions.\n\n---\n\n## Features\n\n| Category      | Capability                  | Description                                |\n| ------------- | --------------------------- | ------------------------------------------ |\n| **Tasks**     | Create, Update, Search      | Full task lifecycle with natural language  |\n| **Comments**  | Add, Read, Update, Delete   | Threaded discussions on tasks              |\n| **Relations** | Blocks, Duplicates, Related | Task dependencies and associations         |\n| **Labels**    | Create, Apply, Remove       | Categorization and filtering               |\n| **Projects**  | List, Create, Update        | Workspace organization                     |\n| **Statuses**  | CRUD, Reorder               | Kanban board column management             |\n| **Memory**    | Conversation, Facts         | Per-user history and knowledge persistence |\n\n### Platform Support\n\n| Platform       | Authentication      | Group Support             | WebSocket |\n| -------------- | ------------------- | ------------------------- | --------- |\n| **Telegram**   | Bot token + User ID | Full (admin/member roles) | Real-time |\n| **Mattermost** | Bot account + Token | Full (admin/member roles) | Real-time |\n\n### Task Provider Support\n\n| Provider     | Auto-Provisioning | Relations | Labels  | Comments |\n| ------------ | ----------------- | --------- | ------- | -------- |\n| **Kaneo**    | Yes               | Yes       | Yes     | Yes      |\n| **YouTrack** | No                | Yes       | Limited | Yes      |\n\n---\n\n## Quick Start\n\n### Prerequisites\n\n- [Bun](https://bun.sh) 1.3.11+\n- Telegram bot token or Mattermost instance\n- Kaneo or YouTrack instance\n- OpenAI-compatible API key\n\n### 30-Second Setup\n\n```bash\ngit clone https://github.com/wKich/papai.git\ncd papai\nbun install\ncp .env.example .env\n```\n\nEdit `.env` with your configuration:\n\n```bash\n# Required for all setups\nCHAT_PROVIDER=telegram          # or: mattermost\nTASK_PROVIDER=kaneo             # or: youtrack\nADMIN_USER_ID=123456789         # Your Telegram user ID\n\n# Platform-specific\nTELEGRAM_BOT_TOKEN=your_token_here\nKANEO_CLIENT_URL=https://kaneo.example.com\n```\n\nStart the bot:\n\n```bash\nbun start\n```\n\nConfigure credentials via chat:\n\n```\n/set llm_apikey sk-your-openai-key\n/set llm_baseurl https://api.openai.com/v1\n/set main_model gpt-4o\n/set kaneo_apikey your-kaneo-key    # When TASK_PROVIDER=kaneo\n```\n\n---\n\n## Architecture\n\n```mermaid\nflowchart TD\n    User[User\u003cbr\u003eTelegram/Mattermost] --\u003e|Message| CP[ChatProvider]\n    CP --\u003e|IncomingMessage| Bot[Bot Orchestrator]\n    Bot --\u003e|History + Tools| LLM[LLM Provider\u003cbr/\u003eVercel AI SDK]\n    LLM --\u003e|Tool Calls| Tools[Tool Registry]\n    Tools --\u003e|Provider-specific| KP[Kaneo Provider]\n    Tools --\u003e|Provider-specific| YP[YouTrack Provider]\n    KP --\u003e|REST API| KAPI[Kaneo API]\n    YP --\u003e|REST API| YAPI[YouTrack API]\n    LLM --\u003e|Response| Bot\n    Bot --\u003e|Reply| CP\n    CP --\u003e|Message| User\n```\n\n### Component Overview\n\n| Path                      | Responsibility                                  |\n| ------------------------- | ----------------------------------------------- |\n| `src/index.ts`            | Entry point, environment validation, migrations |\n| `src/bot.ts`              | Platform-agnostic message routing               |\n| `src/chat/`               | Telegram and Mattermost adapters                |\n| `src/llm-orchestrator.ts` | LLM integration with tool-calling               |\n| `src/tools/`              | Capability-gated tool definitions               |\n| `src/providers/`          | Kaneo and YouTrack API adapters                 |\n| `src/config.ts`           | Per-user runtime configuration                  |\n| `src/memory.ts`           | Fact extraction and long-term storage           |\n| `src/conversation.ts`     | History management with summarization           |\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` or `mattermost`                        |\n| `ADMIN_USER_ID` | Admin user identifier | `123456789` (Telegram) or `username` (Mattermost) |\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` | From [@BotFather](https://t.me/BotFather) |\n\n**Getting your Telegram user ID:**\n\n1. Message [@userinfobot](https://t.me/userinfobot)\n2. Copy the numeric ID to `ADMIN_USER_ID`\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`       | Instance URL      |\n| `MATTERMOST_BOT_TOKEN` | Bot account token |\n\n**Creating a bot:**\n\n1. Go to **Main Menu → Integrations → Bot Accounts**\n2. Add bot with `System Admin` role\n3. Copy token to `MATTERMOST_BOT_TOKEN`\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` | Kaneo instance URL |\n\n**Getting API key:**\n\n1. Log into Kaneo web UI\n2. Go to **Settings → API Keys**\n3. Create and copy key\n4. Alternatively: Auto-provision via `/set kaneo_apikey`\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\n**Creating a token:**\n\n1. Go to **Profile → Account Settings → Authentication → Hub Tokens**\n2. Create token with permissions:\n   - Read/Create/Update issues\n   - Read projects\n   - Read user profile\n\n\u003c/details\u003e\n\n### Runtime Configuration\n\nUse chat commands to configure per-user settings:\n\n| Command              | Description                |\n| -------------------- | -------------------------- |\n| `/config`            | View current configuration |\n| `/set \u003ckey\u003e \u003cvalue\u003e` | Set configuration value    |\n| `/clear`             | Clear conversation history |\n\n**Common Settings:**\n\n| Key              | Description                | Example                            |\n| ---------------- | -------------------------- | ---------------------------------- |\n| `llm_apikey`     | LLM provider API key       | `sk-...`                           |\n| `llm_baseurl`    | OpenAI-compatible endpoint | `https://api.openai.com/v1`        |\n| `main_model`     | Primary model              | `gpt-4o`, `claude-3-opus-20240229` |\n| `small_model`    | Memory extraction model    | `gpt-4o-mini`                      |\n| `kaneo_apikey`   | Kaneo API key              | From Kaneo settings                |\n| `youtrack_token` | YouTrack permanent token   | `perm:XXX...`                      |\n\n---\n\n## Usage\n\nSend natural language messages 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 the details of task 55\"\n- \"Archive task 42\"\n\n**Search and Discovery**\n\n- \"What tasks are in the Backend project?\"\n- \"Search for timeout issues\"\n- \"List all projects\"\n\n**Organization**\n\n- \"Add label 'urgent' to task 42\"\n- \"Create a blocks relation: task 42 blocks task 55\"\n- \"Create a new status called Review in Frontend\"\n\n**Comments**\n\n- \"Add a comment to task 42: Waiting for API changes\"\n- \"Show all comments on task 55\"\n\n### Group Chat\n\nAdd the bot to Telegram groups or Mattermost channels:\n\n1. Add bot to group/channel\n2. Admin runs: `/group adduser @username`\n3. Admin configures credentials via `/set`\n4. Members mention: `@bot create task: fix the bug`\n\n| Capability               | Admin | Member                 |\n| ------------------------ | ----- | ---------------------- |\n| User management          | Yes   | No                     |\n| Configuration            | Yes   | No                     |\n| Natural language queries | Yes   | Yes (mention required) |\n\n---\n\n## Development\n\nAll commands use `bun` directly (no `run` keyword):\n\n```bash\n# Code quality\nbun lint          # Lint with oxlint\nbun lint:fix      # Auto-fix lint issues\nbun format        # Format with oxfmt\nbun format:check  # Check formatting\n\n# Type checking\nbun typecheck     # TypeScript validation\n\n# Security\nbun security      # Run Semgrep security scan\nbun security:ci   # CI scan with SARIF output\n\n# Analysis\nbun knip          # Check for unused dependencies/exports\n\n# Testing\nbun test          # Run unit tests\nbun test:watch    # Watch mode\nbun test:coverage # Coverage report\nbun test:e2e      # E2E tests (requires Docker)\n\n# All checks\nbun check           # Run staged-only checks (used by pre-commit hook)\nbun check:full      # Run full suite: lint, typecheck, format:check, knip, test, duplicates, mock-pollution\nbun check:verbose   # Run full suite with verbose output\nbun fix             # Auto-fix lint and format\n```\n\nNo build step required. Bun runs TypeScript directly.\n\n---\n\n## Testing\n\n### Unit Tests\n\n```bash\nbun test\n```\n\nLocated in `tests/` mirroring `src/` structure. Excludes E2E tests by default.\n\n### E2E Tests\n\n```bash\nbun test:e2e\n```\n\nRequires Docker. Spins up a Kaneo instance, runs full integration tests, and tears down automatically.\n\n---\n\n## Deployment\n\n### Docker Compose (Recommended)\n\n```yaml\nservices:\n  papai:\n    image: ghcr.io/wkich/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    volumes:\n      - papai-data:/data\n\nvolumes:\n  papai-data:\n```\n\n### GitHub Actions\n\nPublishing a release triggers automatic deployment:\n\n1. Create GitHub release (e.g., `v4.2.0`)\n2. Workflow builds and pushes to GHCR\n3. SSH deployment to configured server\n\n**Required Secrets:**\n\n- `SSH_KEY` - Private SSH key\n- `SSH_HOST_KEY` - Server host key\n- `TELEGRAM_BOT_TOKEN`\n- `ADMIN_USER_ID`\n\n**Required Variables:**\n\n- `SSH_HOST` - Deployment target\n- `SSH_USER` - SSH username\n- `SSH_PORT` - SSH port (default: 22)\n\n### Manual (Bare Metal)\n\n```bash\ngit clone https://github.com/wKich/papai.git\ncd papai\nbun install\ncp .env.example .env\n# Edit .env with your settings\nbun start\n```\n\n---\n\n## Tech Stack\n\n- **Runtime:** [Bun](https://bun.sh) 1.3.11\n- **Language:** TypeScript 5.x (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) (Telegram), Mattermost REST API\n- **Task Trackers:** Kaneo REST API, YouTrack REST API\n- **Database:** SQLite (Drizzle ORM)\n- **Linting:** oxlint, oxfmt\n- **Security:** Semgrep (OWASP Top 10, AI/LLM-specific rules)\n- **Testing:** Bun Test\n\n---\n\n## License\n\n[MIT](LICENSE) © 2026 Dmitriy Lazarev\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwkich%2Fpapai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwkich%2Fpapai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwkich%2Fpapai/lists"}