🤖 Agentic Project Manager on Telegram

An autonomous AI-powered project management bot that lives inside your Telegram group, manages tasks via natural language, chases teammates for updates, and posts daily standups without being asked.

---

What Is The Actual Problem?

Most teams use Telegram to communicate but switch to Jira/Notion/Trello for task tracking, creating a painful context switch. Updates get lost in chat, tasks go stale, no one follows up.

Agentic PM solves this by bringing the project manager INTO Telegram:

1. Lives in the group: reads messages, replies, and posts updates directly in Telegram
2. Manages tasks: create, assign, update, and close tasks via plain English
3. Actively chases people: DMs: "Hey @john, task X hasn't been updated in 2 days. What's the status?"
4. Posts daily standups: "3 done ✅, 2 in progress 🔄, 1 blocked 🚫"

⚡ "AGENTIC" = the bot thinks and acts on its own. It decides WHEN to ask, WHO to ask, WHAT to say. That's what separates an AI agent from a simple command bot.

---

🎬 Try It Yourself

---

How It Works (HIGH LEVEL)

---

🏗️ System Design

Architecture

Request Flow (How One Message Works)

Proactive Behavior (The Agentic Part)

Stale Task Detection & Follow-Up Logic

Every 4 hours, the scheduler scans for stale tasks and proactively contacts assignees via DM, no manual trigger needed.

A task is considered stale when:

• Status is IN_PROGRESS or BLOCKED
• Has an assignee
• lastCheckedAt is null OR older than 4 hours

Two-tier response based on how long the task has been silent:

Silence Duration	Bot Action
> 4 hours	Private DM to assignee, friendly check-in, nothing posted to group
> 24 hours	Private DM to assignee (firm) + non-blaming group escalation message

Flow inside the scheduler:

DM blocked by Telegram (403 error)? The bot can only initiate a DM if the user has previously opened a private chat. Fix: open @AgenticPM_bot in private and send /start once (group /start does not count).

---

🗄️ Database Schema

---

📁 Folder Structure

---

🛠️ Agent Tools List

---

🧠 Complete System Prompt (Brain of the Agent)

---

🧰 Our Final Stack

---

⚙️ Setup & Run

Prerequisites

• Bun >= 1.0
• Docker (for PostgreSQL)
• A Telegram Bot Token from @BotFather
• An OpenAI API Key

1. Clone & Install

git clone https://github.com/BCAPATHSHALA/agentic-project-manager-on-telegram.git
cd agentic-project-manager-on-telegram
bun install

2. Configure Environment

cp .env.example .env

Fill in your .env:

# ── Telegram ──
# Get this from @BotFather on Telegram
BOT_TOKEN="7123456789:AAHxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# ── OpenAI ──
# Get from platform.openai.com
OPENAI_API_KEY="sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# ── Database ──
# Local:      postgresql://postgres:password@localhost:5432/agenticpm
# Railway/Neon:    paste the DATABASE_URL from your Railway/Neon PostgreSQL service
DATABASE_URL="postgresql://postgres:password@localhost:5432/agenticpm"

# ── App ──
NODE_ENV="development"
LOG_LEVEL="info"

3. Start the Database

bun run db:up

4. Run Migrations

bun run db:migrate
bun run db:generate

5. Start the Bot

# Development (auto-reload)
bun run dev

# Production
bun run start

---

💬 Bot Commands

Command	Description	Where
/setup	Initialize project for this group	Group only
/join	Register yourself as a team member	Group only
/status	Get project status overview	Group + DM
/tasks	List all tasks	Group + DM
/mytasks	Show your assigned tasks	Group + DM
/help	Show all available commands	Anywhere

Natural Language Examples

@AgenticPM_bot add a task: build login page, assign to @john, high priority, due May 1
@AgenticPM_bot the auth task is now in progress
@AgenticPM_bot mark the login page as done
@AgenticPM_bot what's blocked right now?
@AgenticPM_bot who is working on the database?

---

🤖 Proactive Behavior

Trigger	Action
Task idle for 4h	Sends a friendly DM to the assignee
Task idle for 24h	DM + gentle group escalation
Every day at 9:00 AM	Posts daily standup summary
Every day at 10:00 AM	Flags overdue tasks in the group

---

🧪 How the Agentic Loop Works

---

📜 Scripts

bun run dev           # Start with auto-reload
bun run start         # Start production
bun run build         # Bundle to dist/
bun run typecheck     # Type check only
bun run db:up         # Start PostgreSQL via Docker
bun run db:down       # Stop PostgreSQL
bun run db:migrate    # Run DB migrations
bun run db:generate   # Regenerate Prisma client
bun run db:studio     # Open Prisma Studio

---

🏛️ Tech Stack

Layer	Technology
Runtime	Bun
Language	TypeScript
Telegram	Grammy
AI Agent	OpenAI Agents SDK (@openai/agents)
LLM	gpt-4o-mini
Database	PostgreSQL (via Docker)
ORM	Prisma
Scheduler	node-cron
Logging	pino + pino-pretty
Validation	Zod

---

Follow-Up Testing (Manual)

Use this to test follow-up scheduler behavior immediately without waiting 4 hours.

Run DM follow-up test now

Linux/macOS:

FOLLOWUP_TEST_STALE_HOURS=0 FOLLOWUP_TEST_ESCALATE_HOURS=24 bun run test:followup

Windows PowerShell:

$env:FOLLOWUP_TEST_STALE_HOURS="0"
$env:FOLLOWUP_TEST_ESCALATE_HOURS="24"
bun run test:followup

Run escalation test now (DM + group escalation)

Linux/macOS:

FOLLOWUP_TEST_STALE_HOURS=0 FOLLOWUP_TEST_ESCALATE_HOURS=0 bun run test:followup

Windows PowerShell:

$env:FOLLOWUP_TEST_STALE_HOURS="0"
$env:FOLLOWUP_TEST_ESCALATE_HOURS="0"
bun run test:followup

Telegram DM requirement

If you see this error:

403 Forbidden: bot can't initiate conversation with a user

Do this once:

1. Open a private chat with @AgenticPM_bot.
2. Send /start there (group /start does not count).
3. Re-run bun run test:followup.

---

Built with ❤️ by Manoj Kumar

"The best project manager is one that never sleeps, never forgets, and always follows up."

If this project helped you, give it a ⭐ on GitHub!