claude-code-tg 0.8.3__tar.gz

claude_code_tg-0.8.3/.editorconfig

@@ -0,0 +1,18 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 4
+trim_trailing_whitespace = true
+
+[*.{yml,yaml}]
+indent_size = 2
+
+[*.toml]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false

claude_code_tg-0.8.3/.env.example

@@ -0,0 +1,62 @@
+# tgcc 配置模板
+# 复制为 .env 后填写，并执行 chmod 600 .env（tgcc init 会自动设好权限）。
+# 不要把真实 token 提交到 git。每个实例用一个独立的 BotFather token。
+# 也可以直接运行 `tgcc init` 交互式生成本文件。
+
+# ── 必填 ──────────────────────────────────────────────
+# Bot Token：在 Telegram 找 @BotFather 创建 bot 获取
+TELEGRAM_BOT_TOKEN=
+# 你的 Telegram 数字 User ID（不是 @用户名）：找 @userinfobot 获取
+# 多个用逗号分隔；admin 拥有最高权限，请保持范围最小
+ADMIN_USER_IDS=
+
+# ── 常用（已有默认值，可不改）─────────────────────────
+# 其他允许使用本 bot 的用户 ID，逗号分隔；留空则仅 admin 可用
+ALLOWED_USER_IDS=
+# Claude 可读写的项目目录（默认当前目录）；改动后建议跑 tgcc doctor
+CLAUDE_PROJECT_DIR=.
+# 权限模式：bypassPermissions（信任本地项目）| default | plan（更严格）
+# 项目目录不完全可信时，改成 default 或 plan
+CLAUDE_PERMISSION_MODE=bypassPermissions
+# 模型别名或完整名（如 opus / sonnet / haiku）；留空用 Claude Code 默认
+CLAUDE_MODEL=
+# 思考强度：low / medium / high / xhigh / max / ultracode；留空用 Claude Code 默认
+CLAUDE_EFFORT=
+# 单次执行超时（秒）
+CLAUDE_TIMEOUT=300
+# 排队等待的最大消息数
+QUEUE_MAX_SIZE=3
+
+# ── 附件 ──────────────────────────────────────────────
+# 附件处理方式：path（传本地路径给 Claude，推荐）
+#   | copy-to-project（复制进项目目录）| reject（禁用文件上传）
+ATTACHMENT_MODE=path
+# 单个附件大小上限（MB）
+ATTACHMENT_MAX_MB=20
+# 附件缓存保留天数；留空或 0 表示不自动清理
+ATTACHMENT_RETENTION_DAYS=
+
+# ── 高级 ──────────────────────────────────────────────
+# 危险：旧式的全量权限绕过；true 仅用于完全可信的项目目录
+CLAUDE_SKIP_PERMISSIONS=false
+# 改写 tgcc 的 transcript 入口，使本地 Claude Code /resume 能看到
+# 由 Telegram 发起的会话；默认关闭
+CLAUDE_CLI_RESUME_COMPAT=false
+# 记录交互日志（已脱敏）
+LOG_INTERACTIONS=false
+# 在 Telegram 命令菜单中透传 Claude 的 slash 命令
+CLAUDE_COMMAND_MENU=false
+# 在私聊中流式显示临时草稿预览；默认关闭
+TELEGRAM_DRAFT_PREVIEW=false
+
+# ── Mini App（可选的 HTTPS 控制台）────────────────────
+# 启用 Telegram Mini App 控制台
+TELEGRAM_MINI_APP_ENABLED=false
+# Mini App 对外可访问的 HTTPS 地址（启用时必填）
+TELEGRAM_MINI_APP_PUBLIC_URL=
+# 本地监听地址
+TELEGRAM_MINI_APP_HOST=127.0.0.1
+# 本地监听端口
+TELEGRAM_MINI_APP_PORT=8787
+# Mini App 在 Telegram 菜单中显示的文字
+TELEGRAM_MINI_APP_MENU_TEXT=tgcc

claude_code_tg-0.8.3/.gitattributes

@@ -0,0 +1,22 @@
+# Normalize text files across platforms.
+* text=auto eol=lf
+
+# Source, docs, and config files are reviewed as text.
+*.py text eol=lf
+*.md text eol=lf
+*.toml text eol=lf
+*.yml text eol=lf
+*.yaml text eol=lf
+*.json text eol=lf
+*.txt text eol=lf
+*.svg text eol=lf
+
+# Binary assets should not be line-ending normalized.
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.pdf binary
+*.zip binary
+*.tar.gz binary

claude_code_tg-0.8.3/.github/CODEOWNERS

@@ -0,0 +1,24 @@
+# Maintainer ownership for security and runtime boundaries.
+* @Ike-li
+
+/.github/ @Ike-li
+/SECURITY.md @Ike-li
+/SUPPORT.md @Ike-li
+/CONTRIBUTING.md @Ike-li
+/CODE_OF_CONDUCT.md @Ike-li
+/MAINTAINERS.md @Ike-li
+/README.en.md @Ike-li
+/pyproject.toml @Ike-li
+/CHANGELOG.md @Ike-li
+/scripts/validate_local.py @Ike-li
+/src/claude_code_tg/ @Ike-li
+/tests/ @Ike-li
+/docs/index.md @Ike-li
+/docs/quickstart.md @Ike-li
+/docs/troubleshooting.md @Ike-li
+/docs/architecture.md @Ike-li
+/docs/user-guide.md @Ike-li
+/docs/operator-guide.md @Ike-li
+/docs/compatibility.md @Ike-li
+/docs/roadmap.md @Ike-li
+/docs/security-model.md @Ike-li

claude_code_tg-0.8.3/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,62 @@
+---
+name: Bug report
+about: Report a reproducible tgcc problem
+title: "[Bug]: "
+labels: bug, needs triage
+assignees: ""
+---
+
+## What happened?
+
+Describe the problem and the expected behavior.
+
+## Steps to reproduce
+
+1.
+2.
+3.
+
+## Environment
+
+- tgcc version or commit: run `tgcc --version`, or include the exact commit
+- Python version:
+- OS:
+- Claude Code CLI version:
+- Install method: `uv tool install "git+https://github.com/Ike-li/claude-code-tg.git"` / `uv tool install -e .` / `uv sync` / other
+
+## Configuration shape
+
+Do not paste secrets, tokens, chat transcripts, unsanitized logs, or local
+filesystem paths. Include only safe values such as:
+
+```env
+CLAUDE_PROJECT_DIR=
+CLAUDE_TIMEOUT=
+QUEUE_MAX_SIZE=
+CLAUDE_PERMISSION_MODE=
+CLAUDE_MODEL=
+ATTACHMENT_MAX_MB=
+ATTACHMENT_MODE=
+ATTACHMENT_RETENTION_DAYS=
+CLAUDE_SKIP_PERMISSIONS=
+```
+
+## Logs
+
+Paste relevant sanitized output from:
+
+```bash
+tgcc doctor --env <file>
+tgcc status --env <file>
+tgcc logs --env <file> -n 100
+```
+
+## Additional context
+
+Screenshots, Telegram message examples, or suspected related changes. Redact
+personal data before sharing anything publicly.
+
+## Privacy checklist
+
+- [ ] I did not include Telegram bot tokens, `.env` files, Claude credentials, API keys, private chat transcripts, unsanitized logs, local filesystem paths, screenshots with personal data, or exploit details.
+- [ ] This is not a security vulnerability report. Security-sensitive reports should follow SECURITY.md instead of public issues.

claude_code_tg-0.8.3/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability report
+    url: https://github.com/Ike-li/claude-code-tg/security/advisories/new
+    about: Report vulnerabilities privately instead of posting tokens, logs, chat transcripts, or exploit details in public issues.
+  - name: Support policy
+    url: https://github.com/Ike-li/claude-code-tg/blob/main/SUPPORT.md
+    about: Check support scope, reporting paths, and what not to share publicly.

claude_code_tg-0.8.3/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,39 @@
+---
+name: Feature request
+about: Suggest a focused improvement for tgcc
+title: "[Feature]: "
+labels: enhancement, needs triage
+assignees: ""
+---
+
+## Problem
+
+What user problem should this solve?
+
+## Proposed behavior
+
+Describe the smallest useful behavior that would solve it.
+
+## Why this fits tgcc
+
+tgcc is intentionally a lightweight, self-hosted Claude Code Telegram manager.
+Explain how the feature supports that positioning.
+
+## Environment / scope
+
+If this depends on setup, include safe non-secret context.
+
+- tgcc version or commit (if known): run `tgcc --version`, or include the exact commit
+- Install method: `uv tool install "git+https://github.com/Ike-li/claude-code-tg.git"` / `uv tool install -e .` / `uv sync` / not applicable
+- Runtime area: Telegram bot / CLI / docs / release process / other
+
+## Alternatives considered
+
+What workaround or different approach did you consider?
+
+## Acceptance checks
+
+- [ ] Documentation updated
+- [ ] Tests or smoke steps included
+- [ ] Security/privacy impact considered
+- [ ] No tokens, chat transcripts, unsanitized logs, local filesystem paths, or private chat content included

claude_code_tg-0.8.3/.github/ISSUE_TEMPLATE/question.md

@@ -0,0 +1,56 @@
+---
+name: Question / help
+about: Ask for setup or usage help within tgcc support scope
+title: "[Question]: "
+labels: question, needs triage
+assignees: ""
+---
+
+## What are you trying to do?
+
+Describe the setup, command, or Telegram workflow you are trying to complete.
+
+## Where are you stuck?
+
+Describe what happened, what you expected, and which README or troubleshooting
+step you already tried.
+
+## Environment
+
+- tgcc version or commit: run `tgcc --version`, or include the exact commit
+- Python version:
+- OS:
+- Claude Code CLI version:
+- Install method: `uv tool install "git+https://github.com/Ike-li/claude-code-tg.git"` / `uv tool install -e .` / `uv sync` / other
+
+## Configuration shape
+
+Do not paste secrets, tokens, chat transcripts, unsanitized logs, or local
+filesystem paths. Include only safe values such as:
+
+```env
+CLAUDE_PROJECT_DIR=
+CLAUDE_TIMEOUT=
+QUEUE_MAX_SIZE=
+CLAUDE_PERMISSION_MODE=
+CLAUDE_MODEL=
+ATTACHMENT_MAX_MB=
+ATTACHMENT_MODE=
+ATTACHMENT_RETENTION_DAYS=
+CLAUDE_SKIP_PERMISSIONS=
+```
+
+## Diagnostics
+
+Paste relevant sanitized output from:
+
+```bash
+tgcc doctor --env <file>
+tgcc status --env <file>
+tgcc logs --env <file> -n 100
+```
+
+## Privacy checklist
+
+- [ ] I did not include Telegram bot tokens, `.env` files, Claude credentials, API keys, private chat transcripts, unsanitized logs, local filesystem paths, screenshots with personal data, or exploit details.
+- [ ] This is not a security vulnerability report. Security-sensitive reports should follow SECURITY.md instead of public issues.

claude_code_tg-0.8.3/.github/pull_request_template.md

@@ -0,0 +1,21 @@
+## Summary
+
+Describe the user-facing change and why it belongs in tgcc.
+
+## Checks
+
+- [ ] I kept the change focused and consistent with the lightweight self-hosted scope.
+- [ ] I updated README/docs when behavior, setup, or security expectations changed.
+- [ ] I added or updated tests for user-visible behavior.
+- [ ] I ran `uv run python scripts/validate_local.py` or documented the skipped check below.
+- [ ] I ran tests, `uv run ruff check .`, `uv run --extra dev mypy`, `uv run ruff format --check .`, and `uv build`.
+- [ ] I did not include `.env` files, tokens, unsanitized logs, local filesystem paths, chat transcripts, or private chat content.
+
+## Security And Privacy Impact
+
+- [ ] I considered whether this changes token handling, `.env` files, logs, local paths, chat transcripts, attachments, Claude permission modes, GitHub Actions, or release artifacts.
+- [ ] Security-sensitive changes update `SECURITY.md` or `docs/security-model.md` as needed.
+
+## Notes
+
+Mention any known gaps, skipped checks, or follow-up work.

claude_code_tg-0.8.3/.github/workflows/ci.yml

@@ -0,0 +1,64 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  UV_VERSION: "0.11.17"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # actions/checkout@v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # actions/setup-python@v6.2.0
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        run: python -m pip install --upgrade pip "uv==${UV_VERSION}"
+
+      - name: Install dependencies
+        run: uv sync --extra dev --frozen
+
+      - name: Run tests
+        run: uv run pytest --cov=claude_code_tg --cov-report=term-missing --cov-report=xml
+
+      - name: Upload coverage XML
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # actions/upload-artifact@v7.0.1
+        with:
+          name: coverage-${{ matrix.python-version }}
+          path: coverage.xml
+          if-no-files-found: error
+          retention-days: 14
+
+      - name: Run ruff
+        run: uv run ruff check .
+
+      - name: Run mypy
+        run: uv run --extra dev mypy
+
+      - name: Check formatting
+        run: uv run ruff format --check .
+
+      - name: Build distributions
+        run: uv build

claude_code_tg-0.8.3/.github/workflows/release.yml

@@ -0,0 +1,52 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+env:
+  UV_VERSION: "0.11.17"
+
+jobs:
+  publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    environment:
+      name: pypi
+      url: https://pypi.org/p/claude-code-tg
+    permissions:
+      id-token: write # required for PyPI Trusted Publishing (OIDC)
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # actions/checkout@v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # actions/setup-python@v6.2.0
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        run: python -m pip install --upgrade pip "uv==${UV_VERSION}"
+
+      - name: Verify tag matches package version
+        run: |
+          pkg_version="$(grep -m1 '^version = ' pyproject.toml | sed -E 's/version = "(.*)"/\1/')"
+          tag_version="${GITHUB_REF_NAME#v}"
+          echo "pyproject version: ${pkg_version}; tag: ${tag_version}"
+          if [ "${pkg_version}" != "${tag_version}" ]; then
+            echo "::error::Tag ${tag_version} does not match pyproject version ${pkg_version}"
+            exit 1
+          fi
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # pypa/gh-action-pypi-publish@v1.14.0

claude_code_tg-0.8.3/.gitignore

@@ -0,0 +1,30 @@
+# Environment and secrets
+.env
+*.env
+
+# Python
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+dist/
+build/
+*.egg-info/
+.venv/
+.hypothesis/
+
+# IDE and local orchestration
+.idea/
+.vscode/
+.omc/
+.omx/
+.antigravitycli
+.tgcc-attachments/
+
+# OS noise
+.DS_Store

claude_code_tg-0.8.3/AGENTS.md

@@ -0,0 +1,117 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+This is a Python 3.11+ package for bridging Telegram chats to the Claude Code CLI.
+Source lives in `src/claude_code_tg/`; the main areas are bot wiring
+(`bot.py`, `bot_app.py`, `bot_commands.py`), the CLI (`cli.py`, `cli_parser.py`,
+`cli_init.py`, `cli_instances.py`) and config (`config.py`), Claude execution
+(`executor.py`), sessions (`sessions.py`, `claude_sessions.py`), command menu
+(`command_menu.py`), attachments, diagnostics, interaction logging, and
+file-security helpers. See `docs/architecture.md` for the full module map. Tests
+live in `tests/` and mirror source modules with `test_*.py` files. User docs
+live in `docs/`; contributor/maintainer notes live in `docs/dev/`; assets are
+under `docs/assets/`. Local helper scripts live in `scripts/`.
+
+## Build, Test, and Development Commands
+
+- `uv run python scripts/validate_local.py` runs the full local gate: pytest with
+  coverage, Ruff lint, mypy, Ruff format check, and package build.
+- `uv run pytest` runs the test suite. Use paths for focused runs, for example
+  `uv run pytest tests/test_bot.py`.
+- `uv run ruff check .` checks linting and import ordering.
+- `uv run --extra dev mypy` type-checks `src/claude_code_tg`.
+- `uv build` builds the sdist and wheel.
+- `uv run tgcc --help` inspects the installed CLI entry point locally.
+
+## Session Handoff
+
+When opening a fresh maintainer or agent session, read
+`docs/dev/project-memory.md` first, then run `git log -2 --oneline` before
+making assumptions about current state. For Telegram E2E work, also read
+`docs/dev/e2e/telegram-e2e.md` and `docs/dev/e2e/telegram-e2e-findings.md`
+before starting a real-client run.
+
+## Documentation Maintenance
+
+Use `docs/index.md` as the document map before adding or moving docs. Keep
+`README.md` as the Chinese landing page, `README.en.md` as the English landing
+page (kept in parity with the Chinese one), `docs/quickstart.md` as the shortest
+first-run path, and `docs/user-guide.md` as the source of truth for day-to-day
+Telegram behavior. Prefer linking to the specific owner document over repeating
+setup, security, or E2E details in multiple files.
+
+Do not add new run-specific Telegram E2E docs for ordinary test passes; update
+`docs/dev/e2e/telegram-e2e.md` for procedure changes and
+`docs/dev/e2e/telegram-e2e-findings.md` for compact closure notes. Use
+`docs/dev/project-memory.md` only for current handoff state, not long-lived user
+documentation.
+
+## Coding Style & Naming Conventions
+
+Use 4-space indentation, type annotations for public/internal boundaries, and
+clear `snake_case` names for modules, functions, variables, and tests. Keep code
+small and explicit; prefer existing helpers for sessions, file safety, output
+pagination, and command parsing. Ruff controls formatting-adjacent lint rules
+and import ordering; do not hand-format around it.
+
+## Testing Guidelines
+
+Tests use `pytest`, `pytest-asyncio`, and `pytest-cov`; coverage must stay at or
+above 85%. Name tests `test_<behavior>` and group related cases in `Test...`
+classes. Use `AsyncMock`/fixtures instead of real Telegram network calls. Mark
+real subprocess integration tests with `@pytest.mark.slow` when needed.
+
+## Telegram E2E Notes
+
+Use a dedicated test bot, ignored env file, throwaway project directory, and
+real Telegram client for end-to-end Telegram validation. Do not write tokens,
+numeric Telegram IDs, full session IDs, tunnel URLs, private logs, or attachment
+caches into docs or commits. Avoid direct `getUpdates` while polling is active;
+it conflicts with the running bot and pollutes logs.
+
+E2E local artifacts have fixed homes: keep test env files such as
+`cctg_test.env` at the repository root where `*.env` ignores them, keep
+temporary Mini App HTTPS tunnel URLs only in that ignored env file while active,
+keep the throwaway Claude project outside this repository via
+`CLAUDE_PROJECT_DIR`, and rely on `$HOME/.tgcc/` for runtime state/logs. Telegram
+test groups and BotFather settings live in Telegram itself, not in git.
+
+Telegram E2E procedure and historical closure status are captured under
+`docs/dev/e2e/`. Notable lessons:
+Computer Use is useful for Telegram buttons, ForceReply, and Mini App menu
+checks, but it uses the user's active Mac pointer, keyboard, and focused
+window; it is not an isolated second keyboard/mouse. Telegram Desktop attachment
+preview and replying to an older bot message are fragile to automate. Natural
+non-command group `@bot` mentions require BotFather privacy to be disabled;
+slash commands addressed to the bot work with privacy enabled. Real Mini App
+menu testing needs a temporary HTTPS tunnel and cleanup of both default and
+chat-specific menu buttons; use
+`uv run python scripts/e2e_reset_telegram_menu.py --env cctg_test.env` for the
+cleanup step. Use `uv run python scripts/e2e_log_scan.py --env cctg_test.env`
+for sanitized final log scans instead of pasting raw logs.
+Start E2E runs with `uv run python scripts/e2e_preflight.py --env cctg_test.env`
+to verify the ignored env file, owner-only permissions, outside-repo project,
+and cleanup defaults without printing secrets. Then run
+`uv run python scripts/e2e_prepare_assets.py --env cctg_test.env` to create
+synthetic upload files and copyable prompts under the throwaway project instead
+of using private local files. For macOS Telegram Desktop button-heavy batches,
+run `uv run python scripts/e2e_macos_click.py --preflight`; if it passes, use
+that helper with `--dry-run` first to click Telegram window-relative coordinates
+when Computer Use coordinate clicks are unreliable.
+
+## Commit & Pull Request Guidelines
+
+Recent history uses short imperative subjects, sometimes with conventional
+prefixes such as `feat:`. Keep commits focused, for example `feat: add command
+cache` or `Fix session restore edge case`. PRs should include a concise summary,
+validation commands run, linked issues when relevant, and any security/config
+impact. Include screenshots only for Telegram UX changes where visual behavior
+matters.
+
+## Security & Configuration Tips
+
+Never commit real bot tokens, chat IDs, `.env` files, runtime logs, or attachment
+caches. Prefer `.env.example` for defaults and `tgcc doctor --env <file>` for
+operator checks. Be conservative with `CLAUDE_PERMISSION_MODE`,
+`CLAUDE_SKIP_PERMISSIONS`, and attachment modes; document risk changes clearly.