claude-code-tg 0.8.3

Lightweight self-hosted Telegram manager for Claude Code CLI

tgcc - 用 Telegram 控制 Claude Code

English | 中文

用手机给 Claude Code 发消息，让它在你的电脑上写代码。

在 Telegram 发送指令 → tgcc 在本地调用 Claude Code CLI → 结果发回 Telegram

---

⚡ 3 步开始

# 1. 安装（PyPI）
uv tool install claude-code-tg
# 或装最新开发版：uv tool install "git+https://github.com/Ike-li/claude-code-tg.git"

# 2. 配置（快速向导，只问 3 个必填项；用 tgcc init --full 可配置全部选项）
tgcc init

# 3. 启动
tgcc start

然后在 Telegram 给你的 Bot 发消息就行了！

📋 需要准备什么？

• Python 3.11+
• uv 包管理器
• Claude Code CLI（已认证登录）
• Telegram Bot Token（找 @BotFather 创建）
• 你的 Telegram User ID（找 @userinfobot 获取）

---

💡 为什么用 tgcc？

你的需求	tgcc 给你
🏠 完全本地运行	不需要云服务器，Bot token 和代码都在你的机器上
📱 手机控制编程	通勤路上也能让 Claude 写代码，到家直接看结果
🎯 多项目管理	一台机器跑多个 Bot，每个对应不同项目目录
🔒 安全可见	日志自动脱敏，权限模式清晰显示，文件访问可控
⚙️ 灵活配置	每个对话可以单独设置模型/思考强度/权限模式

---

🎮 常用操作

Telegram 里的基础命令

/new        - 开始新的 Claude 会话
/resume     - 恢复本地的 Claude 会话
/stop       - 停止当前执行
/status     - 查看运行状态
/model opus - 切换到 Opus 模型
/effort max - 最大思考强度

本地管理多个 Bot

# 启动前自检配置
tgcc doctor --env prod.env

# 查看所有实例状态
tgcc status --all

# 批量启动 / 停止 / 重启
tgcc start-all
tgcc stop-all
tgcc restart-all

# 查看某个实例的日志
tgcc logs --env prod.env -f

---

📸 功能预览

📤 发送文件和图片

支持三种模式：

• path - 传递本地文件路径给 Claude（推荐）
• copy-to-project - 复制附件到项目目录
• reject - 禁用文件上传

🎛️ 运行时控制

每个 Telegram 对话可以独立设置：

• 模型选择（Opus / Sonnet / Haiku）
• 思考强度（low → ultracode）
• 权限模式（bypassPermissions / default / plan）

所有设置在状态卡和日志中清晰可见。

📊 实时状态卡

运行中会显示可编辑的状态卡，包括：

• 当前执行的工具
• 已用时间
• 权限模式和思考强度
• Stop 按钮

完成后显示结果，带一键复制和重新执行按钮。

---

🔐 安全提醒

⚠️ 默认权限模式是 bypassPermissions，适合可信项目。如果项目目录不受你完全控制，启动前改成 default 或 plan。

✅ 推荐做法：

• 只把白名单用户加入 ALLOWED_USER_IDS
• .env 文件设置为 chmod 600（init 会自动做）
• 定期检查日志，确保脱敏正常工作
• 不要把真实 token 提交到 git

详细安全模型见 Security Policy 和 Security Model。

---

📚 完整文档

• 快速开始: 5 分钟上手指南 - 最短路径
• 日常使用: 用户指南 - 所有配置选项和 Telegram 命令
• 遇到问题: 故障排查 - 按症状查找解决方案
• 长期运行: 运维指南 - 日志管理、升级、事故响应
• 架构设计: Architecture - 模块结构和设计决策
• 开发贡献: Contributing - 本地验证和 PR 流程

完整文档索引：Documentation Index

---

🚧 当前状态

这是 0.8.3 Alpha 版本（已打 tag v0.8.3）：

✅ 已实现：文本对话、文件输入、多实例管理、会话恢复、权限模式、队列、日志脱敏、CI

✅ 已发布到 PyPI：uv tool install claude-code-tg

运行完整本地校验：

uv run python scripts/validate_local.py

---

🤝 贡献

欢迎贡献！提交 PR 前请：

uv sync --extra dev
uv run pytest --cov=claude_code_tg
uv run ruff check .
uv run --extra dev mypy
uv run ruff format --check .

详见 Contributing Guide。

---

📄 License

MIT License - 详见 LICENSE

---

🙋 获取帮助

• 问题和功能请求：GitHub Issues
• 安全漏洞：见 Security Policy
• 使用疑问：先查 Troubleshooting

---

_{⚡ Built with Claude Code | 🤖 Powered by Anthropic Claude | 💬 Delivered via Telegram}