yee88 0.1.0__tar.gz

yee88-0.1.0/.codex/AGENTS.md

@@ -0,0 +1,5 @@
+after you finish work, commit with a conventional message. only commit the files you edited.
+always run `just check` before code commits.
+if you fix anything from `just check`, rerun it and confirm it passes before committing.
+when using gh to edit or create PR descriptions, prefer `--body-file` to preserve newlines.
+always include a "Manual testing" checklist section in PRs.

yee88-0.1.0/.codex/skills/takopi-release/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: takopi-release
+description: Prepare and ship a Takopi release. Use when asked to cut a release, bump release versions, update changelog/spec/readme, tag v<major.minor.patch>, or trigger the GitHub release workflow.
+---
+
+# Takopi Release
+
+## Overview
+
+Prepare a tagged release that matches the GitHub Actions release workflow. The workflow requires the tag version to match both `pyproject.toml` and `src/takopi/__init__.py`.
+
+## Workflow
+
+### 1) Choose version + date
+
+Pick the release version (major.minor.patch) and the release date (YYYY-MM-DD) for changelog/spec headers.
+If the current version has a `.dev` suffix, assume the target release version is the same version without the suffix, as long as that tag does not already exist.
+
+### 2) Update changelog
+
+Update `changelog.md` by adding a new top section. Before writing it, study the diff between the previous tag and the new release to rank changes; put user-facing changes first.
+
+- `## v<major.minor.patch> (YYYY-MM-DD)`
+- Include subsections like `changes`, `fixes`, `breaking`, `docs` as needed.
+- Keep entries short and include PR links when available (match existing style).
+
+### 3) Bump versions
+
+Update version strings to match the release tag:
+
+- `pyproject.toml`: `project.version = "<major.minor.patch>"`
+- `src/takopi/__init__.py`: `__version__ = "<major.minor.patch>"`
+- `uv.lock`: refresh so the root package version matches (run `uv lock` or `uv sync`).
+
+### 4) Update spec + docs
+
+Update `docs/specification.md` to match the release:
+
+- Header: `# Takopi Specification v<major.minor.patch> [YYYY-MM-DD]`
+- Replace `Takopi v<old>` and `Out of scope for v<old>` lines with the new version.
+- Add a changelog entry like `- No normative changes; align spec version with the v<major.minor.patch> release.` unless the spec itself changed.
+
+If the release highlights new features, update `readme.md` accordingly (see v0.9.0 release).
+
+### 5) Run checks
+
+Run the standard checks before committing:
+
+- `just check` (ruff/ty/pytest)
+
+### 6) Commit + tag
+
+Commit the release using conventional commits:
+
+- Commit message: `chore(release): v<major.minor.patch>`
+- Tag: `git tag v<major.minor.patch>`
+
+Push the tag to trigger `.github/workflows/release.yml` (build, PyPI publish, GitHub release).
+
+### 7) Optional post-release bump
+
+If you keep a dev version between releases, bump the minor version (reset patch to 0) and commit (`chore: bump version to ...`).
+
+## Notes
+
+- The release workflow checks that the tag matches `pyproject.toml` and `src/takopi/__init__.py`.
+- Keep dates consistent across `changelog.md` and `docs/specification.md`.

yee88-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,92 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - "master"
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  checks:
+    name: ${{ matrix.task }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - task: format
+            do_sync: true
+            command: uv run --no-sync ruff format --check --diff src tests
+            sync_args: --no-install-project
+          - task: ruff
+            do_sync: true
+            command: uv run --no-sync ruff check src tests --output-format=github
+            sync_args: --no-install-project
+          - task: ty
+            do_sync: true
+            command: uv run --no-sync ty check src tests
+            sync_args: --no-install-project
+          - task: pytest
+            do_sync: true
+            command: uv run --no-sync pytest
+            sync_args: ""
+          - task: build
+            do_sync: false
+            command: uv build
+            sync_args: ""
+          - task: docs
+            do_sync: true
+            command: uv run --no-sync python scripts/docs_prebuild.py && uv run --no-sync zensical build --clean
+            sync_args: --no-install-project --group docs
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.14"
+          enable-cache: true
+
+      - name: Install dependencies
+        if: matrix.do_sync
+        run: uv sync --frozen ${{ matrix.sync_args }}
+
+      - name: Run check
+        run: ${{ matrix.command }}
+
+      - name: Add coverage to summary
+        if: ${{ always() && matrix.task == 'pytest' }}
+        run: |
+          {
+            echo "## Coverage"
+            echo ""
+            uv run --no-sync python -m coverage report || true
+          } >> "$GITHUB_STEP_SUMMARY"
+
+  notify-commit:
+    name: notify-commit
+    runs-on: ubuntu-latest
+    needs: checks
+    if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/master' && needs.checks.result == 'success' }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.14"
+          enable-cache: true
+
+      - name: Send Telegram notification
+        run: uv run scripts/commit_notify.py
+        env:
+          REPO: ${{ github.repository }}
+          TELEGRAM_BOT_TOKEN: ${{ secrets.TELEGRAM_BOT_TOKEN }}
+          TELEGRAM_CHAT_ID: ${{ secrets.TELEGRAM_CHAT_ID }}

yee88-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,126 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.14"
+          enable-cache: true
+
+      - name: Check tag matches project version
+        run: |
+          uv run --no-project python - <<'PY'
+          import os
+          import re
+          import tomllib
+          from pathlib import Path
+
+          tag = os.environ.get('GITHUB_REF_NAME', '')
+          tag_version = tag[1:] if tag.startswith('v') else tag
+
+          pyproject = tomllib.loads(Path('pyproject.toml').read_text(encoding='utf-8'))
+          project_version = pyproject['project']['version']
+
+          init_version = None
+          init_path = Path('src') / 'takopi' / '__init__.py'
+          if init_path.is_file():
+            m = re.search(r'__version__\s*=\s*"([^"]+)"', init_path.read_text(encoding='utf-8'))
+            if m:
+              init_version = m.group(1)
+
+          if project_version != tag_version:
+            raise SystemExit(f"Tag {tag!r} does not match pyproject version {project_version!r}")
+          if init_version and init_version != project_version:
+            raise SystemExit(
+              f"src/takopi/__init__.py __version__ {init_version!r} does not match pyproject version {project_version!r}"
+            )
+
+          print(f"OK: tag {tag!r} matches version {project_version!r}")
+          PY
+
+      - name: Run tests
+        run: uv run pytest
+
+      - name: Build (wheel + sdist)
+        run: uv build
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    name: Publish to PyPI (trusted publishing)
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/takopi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+          skip-existing: true
+
+  github-release:
+    name: Create GitHub Release
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.14"
+          enable-cache: true
+
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create GitHub release and upload artifacts
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: |
+            dist/*
+
+      - name: Notify release
+        run: uv run scripts/release_notify.py
+        env:
+          REPO: ${{ github.repository }}
+          TAG_NAME: ${{ github.ref_name }}
+          TELEGRAM_BOT_TOKEN: ${{ secrets.TELEGRAM_BOT_TOKEN }}
+          TELEGRAM_CHAT_ID: ${{ secrets.TELEGRAM_CHAT_ID }}

yee88-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+dist/
+.venv/
+*.egg-info/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+.coverage
+.mutmut-cache/
+mutants/
+.worktrees/
+research/
+_site/
+docs/reference/changelog.md

yee88-0.1.0/Justfile

@@ -0,0 +1,23 @@
+check:
+    uv run ruff format --check src tests
+    uv run ruff check src tests
+    uv run ty check src tests
+    uv run pytest
+
+mutate:
+    uv run mutmut run
+
+docs-serve:
+    uv run --no-sync python scripts/docs_prebuild.py
+    uv run --group docs zensical serve
+
+docs-build:
+    uv run --no-sync python scripts/docs_prebuild.py
+    uv run --group docs zensical build
+
+bundle:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    bundle="takopi.git.bundle"
+    git bundle create "$bundle" --all
+    open -R "$bundle"

yee88-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 banteg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

yee88-0.1.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: yee88
+Version: 0.1.0
+Summary: Telegram bridge for Codex, Claude Code, and other agent CLIs.
+Project-URL: Homepage, https://github.com/banteg/takopi
+Project-URL: Documentation, https://takopi.dev/
+Project-URL: Repository, https://github.com/banteg/takopi
+Project-URL: Issues, https://github.com/banteg/takopi/issues
+Author: yee.wang
+License: MIT License
+        
+        Copyright (c) 2025 banteg
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.14
+Requires-Dist: anyio>=4.12.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: markdown-it-py
+Requires-Dist: msgspec>=0.20.0
+Requires-Dist: openai>=2.15.0
+Requires-Dist: pydantic-settings>=2.12.0
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: questionary>=2.1.1
+Requires-Dist: rich>=14.2.0
+Requires-Dist: structlog>=25.5.0
+Requires-Dist: sulguk>=0.11.1
+Requires-Dist: tomli-w>=1.2.0
+Requires-Dist: typer>=0.21.0
+Requires-Dist: watchfiles>=0.21.0
+Description-Content-Type: text/markdown
+
+# yee88
+
+telegram bridge for codex, claude code, opencode, pi.
+
+## quickstart
+
+```sh
+# install
+uv tool install -U yee88
+
+# first run - follow the setup wizard
+yee88
+
+# in any git repo - create a topic and start
+cd ~/your-project
+yee88 topic init
+yee88
+```
+
+## features
+
+- projects and worktrees: work on multiple repos/branches simultaneously, branches are git worktrees
+- stateless resume: continue in chat or copy the resume line to pick up in terminal
+- progress streaming: commands, tools, file changes, elapsed time
+- parallel runs across agent sessions, per-agent-session queue
+- works with telegram features like voice notes and scheduled messages
+- file transfer: send files to the repo or fetch files/dirs back
+- group chats and topics: map group topics to repo/branch contexts
+- works with existing anthropic and openai subscriptions
+
+## requirements
+
+`uv` for installation (`curl -LsSf https://astral.sh/uv/install.sh | sh`)
+
+python 3.14+ (`uv python install 3.14`)
+
+at least one engine on PATH: `codex`, `claude`, `opencode`, or `pi`
+
+## usage
+
+```sh
+cd ~/dev/happy-gadgets
+yee88
+```
+
+send a message to your bot. prefix with `/codex`, `/claude`, `/opencode`, or `/pi` to pick an engine. reply to continue a thread.
+
+register a project with `yee88 init happy-gadgets`, then target it from anywhere with `/happy-gadgets hard reset the timeline`.
+
+mention a branch to run an agent in a dedicated worktree `/happy-gadgets @feat/memory-box freeze artifacts forever`.
+
+inspect or update settings with `yee88 config list`, `yee88 config get`, and `yee88 config set`.
+
+## plugins
+
+takopi supports entrypoint-based plugins for engines, transports, and commands.
+
+see [`docs/how-to/write-a-plugin.md`](docs/how-to/write-a-plugin.md) and [`docs/reference/plugin-api.md`](docs/reference/plugin-api.md).
+
+## development
+
+see [`docs/reference/specification.md`](docs/reference/specification.md) and [`docs/developing.md`](docs/developing.md).
+

yee88-0.1.0/README.md

@@ -0,0 +1,63 @@
+# yee88
+
+telegram bridge for codex, claude code, opencode, pi.
+
+## quickstart
+
+```sh
+# install
+uv tool install -U yee88
+
+# first run - follow the setup wizard
+yee88
+
+# in any git repo - create a topic and start
+cd ~/your-project
+yee88 topic init
+yee88
+```
+
+## features
+
+- projects and worktrees: work on multiple repos/branches simultaneously, branches are git worktrees
+- stateless resume: continue in chat or copy the resume line to pick up in terminal
+- progress streaming: commands, tools, file changes, elapsed time
+- parallel runs across agent sessions, per-agent-session queue
+- works with telegram features like voice notes and scheduled messages
+- file transfer: send files to the repo or fetch files/dirs back
+- group chats and topics: map group topics to repo/branch contexts
+- works with existing anthropic and openai subscriptions
+
+## requirements
+
+`uv` for installation (`curl -LsSf https://astral.sh/uv/install.sh | sh`)
+
+python 3.14+ (`uv python install 3.14`)
+
+at least one engine on PATH: `codex`, `claude`, `opencode`, or `pi`
+
+## usage
+
+```sh
+cd ~/dev/happy-gadgets
+yee88
+```
+
+send a message to your bot. prefix with `/codex`, `/claude`, `/opencode`, or `/pi` to pick an engine. reply to continue a thread.
+
+register a project with `yee88 init happy-gadgets`, then target it from anywhere with `/happy-gadgets hard reset the timeline`.
+
+mention a branch to run an agent in a dedicated worktree `/happy-gadgets @feat/memory-box freeze artifacts forever`.
+
+inspect or update settings with `yee88 config list`, `yee88 config get`, and `yee88 config set`.
+
+## plugins
+
+takopi supports entrypoint-based plugins for engines, transports, and commands.
+
+see [`docs/how-to/write-a-plugin.md`](docs/how-to/write-a-plugin.md) and [`docs/reference/plugin-api.md`](docs/reference/plugin-api.md).
+
+## development
+
+see [`docs/reference/specification.md`](docs/reference/specification.md) and [`docs/developing.md`](docs/developing.md).
+