一个强大的 Telegram 机器人，用于监控和控制 Claude Code 的完整生命周期。通过 Telegram 即时消息，您可以实时监控 AI Agent 状态、管理任务、控制工具调用，并接收任务完成报告。
- 实时监控：跟踪所有 Claude Code Agent 的运行状态
- 任务管理：通过 Telegram 创建、停止和管理任务
- 工具调用监控：查看和控制工具的调用情况
- 智能报告：任务完成时自动发送详细报告
- 异步架构：基于
asyncio的高性能异步处理 - Telegram Bot API：使用
python-telegram-bot框架 - 模块化设计：清晰的代码结构，易于扩展
- 数据持久化：SQLite 数据库存储配置和历史记录
- Python 3.12+
- Telegram Bot Token（从 @BotFather 获取）
- Anthropic API Key
# 1. 克隆仓库
git clone <repository-url>
cd notify-claude-code-bot
# 2. 创建虚拟环境
python -m venv venv
source venv/bin/activate # Linux/Mac
# 或 venv\Scripts\activate # Windows
# 3. 安装依赖
pip install -r requirements.txt
# 4. 配置环境变量
cp .env.example .env
nano .env # 编辑配置文件
# 5. 启动服务
python main.py# 构建镜像
docker build -t notify-claude-code-bot .
# 运行容器
docker run -d \
--name notify-claude-bot \
--env-file .env \
-v $(pwd)/storage:/app/storage \
-v $(pwd)/logs:/app/logs \
notify-claude-code-bot
# 或使用 docker-compose
docker-compose up -d编辑 .env 文件：
# Telegram 配置
TELEGRAM_BOT_TOKEN=your_bot_token_here
TELEGRAM_ADMIN_USER_ID=your_telegram_user_id
# Anthropic API
ANTHROPIC_API_KEY=your_api_key_here
# Claude Code 路径
CLAUDE_CODE_BASE_PATH=/path/to/claude/code
# 其他配置
LOG_LEVEL=INFO获取 Telegram User ID：发送消息给 @userinfobot
| 命令 | 说明 |
|---|---|
/start |
初始化机器人并验证权限 |
/status |
查看 Claude Code 当前状态 |
/agents |
列出所有运行的 Agent |
/tasks |
显示当前活跃任务列表 |
/create |
创建新的 Claude Code 任务 |
/stop |
停止指定的运行中任务 |
/logs |
查看最近的系统日志 |
/report |
获取任务完成报告 |
/help |
显示帮助信息 |
场景 1：监控 Agent
用户: /agents
Bot: 📊 当前运行的 Agents:
• Agent-1: 状态=运行中, 任务=代码审查
• Agent-2: 状态=等待中, 任务=文档生成
场景 2：创建任务
用户: /create
Bot: 🔧 请输入任务描述...
用户: 帮我重构 user_service.py
Bot: ✅ 任务已创建！ID: task-123
场景 3：接收报告
Bot: 🎉 任务完成报告
━━━━━━━━━━━━━━━━
任务: task-123
状态: ✅ 成功
耗时: 3分20秒
输出: 已完成 user_service.py 重构
修改文件: 1个
新增测试: 5个
notify-claude-code-bot/
├── claude/ # Claude Code 控制器
│ ├── controller.py # 核心控制器
│ ├── controller_enhanced.py # 增强版控制器
│ ├── agent_monitor.py # Agent 监控
│ ├── tool_manager.py # 工具管理
│ └── hooks_integration.py # Hooks 集成
├── config/ # 配置管理
│ └── settings.py # 配置加载
├── models/ # 数据模型
│ ├── agent.py # Agent 模型
│ ├── task.py # 任务模型
│ └── tool.py # 工具模型
├── services/ # 业务逻辑
│ ├── task_service.py # 任务服务
│ └── report_service.py # 报告服务
├── tg_bot/ # Telegram Bot
│ ├── bot.py # Bot 初始化
│ ├── handlers.py # 消息处理
│ └── keyboards.py # 键盘布局
├── utils/ # 工具函数
│ └── logger.py # 日志配置
├── storage/ # 数据存储
│ └── *.db # SQLite 数据库
├── logs/ # 日志文件
├── tests/ # 测试文件
├── main.py # 程序入口
├── requirements.txt # 依赖列表
├── Dockerfile # Docker 配置
├── docker-compose.yml # Docker Compose 配置
└── README.md # 项目文档
┌─────────────┐ ┌──────────────┐
│ Telegram │◄────────┤ Bot Core │
│ User │ │ (handlers) │
└─────────────┘ └──────┬───────┘
│
┌──────────┼──────────┐
│ │ │
┌───────▼───┐ ┌───▼────┐ ┌──▼────────┐
│ Task │ │ Agent │ │ Report │
│ Service │ │ Monitor│ │ Service │
└───────┬───┘ └───┬────┘ └──┬────────┘
│ │ │
└──────────┼──────────┘
│
┌──────────▼──────────┐
│ Claude Controller │
│ (controller.py) │
└──────────┬──────────┘
│
┌──────────▼──────────┐
│ Claude Code CLI │
└─────────────────────┘
# 运行所有测试
pytest tests/
# 运行特定测试
pytest tests/test_hooks_integration.py
# 查看覆盖率
pytest --cov=. tests/- 在
tg_bot/handlers.py中添加新的命令处理器 - 在
services/中实现业务逻辑 - 更新 README.md 文档
项目遵循 PEP 8 规范：
# 格式化代码
black .
# 检查代码质量
flake8 .- ✨ 初始版本发布
- 🎯 基础 Agent 监控功能
- 🔧 任务管理功能
- 📊 报告生成功能
- 🐳 Docker 支持
欢迎提交 Issue 和 Pull Request！
- Fork 本仓库
- 创建特性分支 (
git checkout -b feature/AmazingFeature) - 提交更改 (
git commit -m 'Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 开启 Pull Request
本项目采用 MIT 许可证。详见 LICENSE 文件。
- 提交 Issue：GitHub Issues
- 文档：完整文档
- 邮箱：support@example.com
- Claude Code - 强大的 AI 编程助手
- python-telegram-bot - Telegram Bot 框架
- 所有贡献者
Made with ❤️ by Claude Code