klir-bot 0.1.0__tar.gz

klir_bot-0.1.0/.gitignore

@@ -0,0 +1,59 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+.eggs/
+dist/
+build/
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Type checking & linting
+.mypy_cache/
+.ruff_cache/
+.dmypy.json
+dmypy.json
+
+# Testing
+.pytest_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+.hypothesis/
+
+# IDE & editors
+.idea/
+.vscode/
+.claude/
+*.swp
+*.swo
+*.swn
+*~
+.project
+.settings/
+
+# OS
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# Environment & secrets
+.env
+.env.*
+
+# Runtime
+*.pid
+*.log
+*.sock
+
+# Personal / dev-only (not part of the project)
+start_bot.sh
+python_best_practice.md
+run.py

klir_bot-0.1.0/Dockerfile.sandbox

@@ -0,0 +1,48 @@
+# Dockerfile.sandbox -- lightweight sandbox for klir CLI execution.
+# Based on Node 22 (Debian bookworm) with Python 3, Claude Code CLI,
+# and Codex CLI pre-installed.  The container runs "sleep infinity" so
+# klir can `docker exec` into it on demand.
+
+FROM node:22-bookworm-slim
+
+ENV DEBIAN_FRONTEND=noninteractive \
+    LANG=en_US.UTF-8 \
+    LC_ALL=en_US.UTF-8 \
+    PIP_BREAK_SYSTEM_PACKAGES=1
+
+# System packages: Python, build tools, Git, locale support
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+       python3 python3-pip python3-venv python3-dev \
+       build-essential git curl ca-certificates sudo locales \
+    && sed -i '/en_US.UTF-8/s/^# //' /etc/locale.gen && locale-gen \
+    && rm -rf /var/lib/apt/lists/*
+
+# Chrome/Chromium runtime dependencies for browser-based skills
+# (e.g. patchright, playwright). Only shared libraries -- no browser binary.
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+       libasound2 libatk-bridge2.0-0 libatk1.0-0 libcairo2 libcups2 \
+       libdbus-1-3 libdrm2 libexpat1 libgbm1 libglib2.0-0 libnspr4 \
+       libnss3 libpango-1.0-0 libx11-6 libx11-xcb1 libxcb1 \
+       libxcomposite1 libxdamage1 libxext6 libxfixes3 libxkbcommon0 \
+       libxrandr2 libxshmfence1 \
+       fonts-liberation fonts-noto-color-emoji \
+    && rm -rf /var/lib/apt/lists/*
+
+# Allow pip installs without the "externally managed" guard
+RUN rm -f /usr/lib/python*/EXTERNALLY-MANAGED
+
+# Install Claude Code CLI and Codex CLI
+RUN npm install -g @anthropic-ai/claude-code @openai/codex @google/gemini-cli
+
+# Prepare a writable data directory
+RUN mkdir -p /data && chown node:node /data
+
+# Let the `node` user run sudo without a password (useful for apt inside sandbox)
+RUN echo "node ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers.d/node
+
+USER node
+WORKDIR /workspace
+
+CMD ["sleep", "infinity"]

klir_bot-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 PleasePrompto
+
+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.

klir_bot-0.1.0/PKG-INFO

@@ -0,0 +1,364 @@
+Metadata-Version: 2.4
+Name: klir-bot
+Version: 0.1.0
+Summary: Control AI coding CLIs from Telegram. Live streaming, sessions, cron jobs, webhooks, Docker sandboxing. Originally forked from ductor by PleasePrompto.
+Project-URL: Repository, https://github.com/js-krinay/klir
+Project-URL: Issues, https://github.com/js-krinay/klir/issues
+Project-URL: Changelog, https://github.com/js-krinay/klir/releases
+Author: Jinay Shah
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai,automation,bot,claude,cli,codex,klir,streaming,telegram
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: aiogram<4.0.0,>=3.24.0
+Requires-Dist: aiohttp<4.0.0,>=3.9.0
+Requires-Dist: cronsim>=2.7
+Requires-Dist: filetype>=1.2.0
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: questionary>=2.1.1
+Requires-Dist: rich>=14.3.2
+Requires-Dist: tzdata>=2024.1
+Provides-Extra: api
+Requires-Dist: pynacl>=1.6.2; extra == 'api'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/js-krinay/klir/main/klir/bot/klir_images/logo_text.png" alt="klir" width="100%" />
+</p>
+
+<p align="center">
+  <strong>Claude Code, Codex CLI, and Gemini CLI as your Telegram assistant.</strong><br>
+  Uses only official CLIs. Nothing spoofed, nothing proxied.
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/klir/"><img src="https://img.shields.io/pypi/v/klir?color=blue" alt="PyPI" /></a>
+  <a href="https://pypi.org/project/klir/"><img src="https://img.shields.io/pypi/pyversions/klir?v=1" alt="Python" /></a>
+  <a href="https://github.com/js-krinay/klir/blob/main/LICENSE"><img src="https://img.shields.io/github/license/js-krinay/klir" alt="License" /></a>
+</p>
+
+<p align="center">
+  <a href="#quick-start">Quick start</a> &middot;
+  <a href="#how-chats-work">How chats work</a> &middot;
+  <a href="#telegram-commands">Commands</a> &middot;
+  <a href="docs/README.md">Docs</a> &middot;
+  <a href="#contributing">Contributing</a>
+</p>
+
+---
+
+If you want to control Claude Code, Google's Gemini CLI, or OpenAI's Codex CLI via Telegram, build automations, or manage multiple agents easily — klir is the right tool for you.
+
+klir runs on your machine and sends simple console commands as if you were typing them yourself, so you can use your active subscriptions (Claude Max, etc.) directly. No API proxying, no SDK patching, no spoofed headers. Just the official CLIs, executed as subprocesses, with all state kept in plain JSON and Markdown under `~/.klir/`.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/js-krinay/klir/main/docs/images/klir-start.jpeg" alt="klir /start screen" width="49%" />
+  <img src="https://raw.githubusercontent.com/js-krinay/klir/main/docs/images/klir-quick-actions.jpeg" alt="klir quick action buttons" width="49%" />
+</p>
+
+## Quick start
+
+```bash
+pipx install klir
+klir
+```
+
+The onboarding wizard handles CLI checks, Telegram setup, timezone, optional Docker, and optional background service install.
+
+**Requirements:** Python 3.11+, at least one CLI installed (`claude`, `codex`, or `gemini`), a Telegram Bot Token from [@BotFather](https://t.me/BotFather).
+
+Detailed setup: [`docs/installation.md`](docs/installation.md)
+
+## How chats work
+
+klir gives you multiple ways to interact with your coding agents. Each level builds on the previous one.
+
+### 1. Single chat (your main agent)
+
+This is where everyone starts. You get a private 1:1 Telegram chat with your bot. Every message goes to the CLI you have active (`claude`, `codex`, or `gemini`), responses stream back in real time.
+
+```text
+You:   "Explain the auth flow in this codebase"
+Bot:   [streams response from Claude Code]
+
+You:   /model
+Bot:   [interactive model/provider picker]
+
+You:   "Now refactor the parser"
+Bot:   [streams response, same session context]
+```
+
+This single chat is all you need. Everything else below is optional.
+
+### 2. Groups with topics (multiple isolated chats)
+
+Create a Telegram group, enable topics (forum mode), and add your bot. Now every topic becomes its own isolated chat with its own CLI context.
+
+```text
+Group: "My Projects"
+  ├── General           ← own context (isolated from your single chat)
+  ├── Topic: Auth       ← own context
+  ├── Topic: Frontend   ← own context
+  ├── Topic: Database   ← own context
+  └── Topic: Refactor   ← own context
+```
+
+That's 5 independent conversations from a single group. Your private single chat stays separate too — 6 total contexts, all running in parallel.
+
+Each topic can use a different model. Run `/model` inside a topic to change just that topic's provider.
+
+All chats share the same `~/.klir/` workspace — same tools, same memory, same files. The only thing isolated is the conversation context.
+
+> **Note:** The Telegram Bot API has no method to list existing forum topics. klir learns topic names from `forum_topic_created` and `forum_topic_edited` events — so only topics created or renamed while the bot is in the group are known by name. Pre-existing topics show as "Topic #N" until they are edited. This is a Telegram limitation, not a klir limitation.
+
+### 3. Named sessions (extra contexts within any chat)
+
+Need to work on something unrelated without losing your current context? Start a named session. It runs inside the same chat but has its own CLI conversation.
+
+```text
+You:   "Let's work on authentication"        ← main context builds up
+Bot:   [responds about auth]
+
+/session Fix the broken CSV export            ← starts session "firmowl"
+Bot:   [works on CSV in separate context]
+
+You:   "Back to auth — add rate limiting"     ← main context is still clean
+Bot:   [remembers exactly where you left off]
+
+@firmowl Also add error handling              ← follow-up to the session
+```
+
+Sessions work everywhere — in your single chat, in group topics, in sub-agent chats. Think of them as opening a second terminal window next to your current one.
+
+### 4. Background tasks (async delegation)
+
+Any chat can delegate long-running work to a background task. You keep chatting while the task runs autonomously. When it finishes, the result flows back into your conversation.
+
+```text
+You:   "Research the top 5 competitors and write a summary"
+Bot:   → delegates to background task, you keep chatting
+Bot:   → task finishes, result appears in your chat
+
+You:   "Delegate this: generate reports for all Q4 metrics"
+Bot:   → explicitly delegated, runs in background
+Bot:   → task has a question? It asks the agent → agent asks you → you answer → task continues
+```
+
+Each task gets its own memory file (`TASKMEMORY.md`) and can be resumed with follow-ups.
+
+### 5. Sub-agents (fully isolated second agent)
+
+Sub-agents are completely separate bots — own Telegram chat, own workspace, own memory, own CLI auth, own config settings (heartbeat, timeouts, model defaults, etc.). Like having klir installed twice on different machines.
+
+```bash
+klir agents add codex-agent    # creates a new bot (needs its own BotFather token)
+```
+
+```text
+Your main chat (Claude):        "Explain the auth flow"
+codex-agent chat (Codex):       "Refactor the parser module"
+```
+
+Sub-agents live under `~/.klir/agents/<name>/` with their own workspace, tools, and memory — fully isolated from the main agent.
+
+You can delegate tasks between agents:
+
+```text
+Main chat:  "Ask codex-agent to write tests for the API"
+  → Claude sends the task to Codex
+  → Codex works in its own workspace
+  → Result flows back to your main chat
+```
+
+### Comparison
+
+| | Single chat | Group topics | Named sessions | Background tasks | Sub-agents |
+|---|---|---|---|---|---|
+| **What it is** | Your main 1:1 chat | One topic = one chat | Extra context in any chat | "Do this while I keep working" | Separate bot, own everything |
+| **Context** | One per provider | One per topic per provider | Own context per session | Own context, result flows back | Fully isolated |
+| **Workspace** | `~/.klir/` | Shared with main | Shared with parent chat | Shared with parent agent | Own under `~/.klir/agents/` |
+| **Config** | Main config | Shared with main | Shared with parent chat | Shared with parent agent | Own config (heartbeat, timeouts, model, ...) |
+| **Setup** | Automatic | Create group + enable topics | `/session <prompt>` | Automatic or "delegate this" | `klir agents add` + BotFather |
+
+### How it all fits together
+
+```text
+~/.klir/                          ← shared workspace (tools, memory, files)
+  │
+  ├── Single chat                   ← main agent, private 1:1
+  │     ├── main context
+  │     └── named sessions
+  │
+  ├── Group: "My Projects"          ← same agent, same workspace
+  │     ├── General (own context)
+  │     ├── Topic: Auth (own context, own model)
+  │     ├── Topic: Frontend (own context)
+  │     └── each topic can have named sessions too
+  │
+  └── agents/codex-agent/           ← sub-agent, fully isolated workspace
+        ├── own single chat
+        ├── own group support
+        ├── own named sessions
+        └── own background tasks
+```
+
+## Features
+
+- **Real-time streaming** — live Telegram message edits as the CLI produces output
+- **Provider switching** — `/model` to change provider/model, `@model` directives for inline targeting
+- **Persistent memory** — plain Markdown files that survive across sessions
+- **Cron jobs** — in-process scheduler with timezone support, per-job overrides, quiet hours
+- **Webhooks** — `wake` (inject into active chat) and `cron_task` (isolated task run) modes
+- **Heartbeat** — proactive checks in active sessions with cooldown
+- **Config hot-reload** — most settings update without restart
+- **Docker sandbox** — optional sidecar container with configurable host mounts
+- **Service manager** — Linux (systemd), macOS (launchd), Windows (Task Scheduler)
+- **Cross-tool skill sync** — shared skills across `~/.claude/`, `~/.codex/`, `~/.gemini/`
+
+## Auth
+
+klir uses a dual-allowlist model. Every message must pass both checks.
+
+| Chat type | Check |
+|---|---|
+| **Private** | `user_id ∈ allowed_user_ids` |
+| **Group** | `group_id ∈ allowed_group_ids` AND `user_id ∈ allowed_user_ids` |
+
+- **`allowed_user_ids`** — Telegram user IDs that may talk to the bot. At least one required.
+- **`allowed_group_ids`** — Telegram group IDs where the bot may operate. Default `[]` = no groups.
+- **`group_mention_only`** — When `true`, the bot only responds in groups when @mentioned or replied to.
+
+All three are **hot-reloadable** — edit `config.json` and changes take effect within seconds.
+
+> **Privacy Mode:** Telegram bots have Privacy Mode enabled by default and only see `/commands` in groups. To let the bot see all messages, make it a **group admin** or disable Privacy Mode via BotFather (`/setprivacy` → Disable). If changed after joining, remove and re-add the bot.
+
+**Group management:** When the bot is added to a group not in `allowed_group_ids`, it warns and auto-leaves. Use `/where` to see tracked groups and their IDs.
+
+## Telegram commands
+
+| Command | Description |
+|---|---|
+| `/model` | Interactive model/provider selector |
+| `/new` | Reset active provider session |
+| `/stop` | Abort active run |
+| `/stop_all` | Abort runs across all agents |
+| `/status` | Session/provider/auth status |
+| `/memory` | Show persistent memory |
+| `/session <prompt>` | Start a named background session |
+| `/sessions` | View/manage active sessions |
+| `/tasks` | View/manage background tasks |
+| `/cron` | Interactive cron management |
+| `/showfiles` | Browse `~/.klir/` |
+| `/diagnose` | Runtime diagnostics |
+| `/upgrade` | Check/apply updates |
+| `/agents` | Multi-agent status |
+| `/agent_commands` | Multi-agent command reference |
+| `/where` | Show tracked chats/groups |
+| `/leave <id>` | Manually leave a group |
+| `/info` | Version + links |
+
+## CLI commands
+
+```bash
+klir                  # Start bot (auto-onboarding if needed)
+klir stop             # Stop bot
+klir restart          # Restart bot
+klir upgrade          # Upgrade and restart
+klir status           # Runtime status
+
+klir service install  # Install as background service
+klir service logs     # View service logs
+
+klir docker enable    # Enable Docker sandbox
+klir docker rebuild   # Rebuild sandbox container
+klir docker mount /p  # Add host mount
+
+klir agents list      # List configured sub-agents
+klir agents add NAME  # Add a sub-agent
+klir agents remove NAME
+
+klir api enable       # Enable WebSocket API (beta)
+```
+
+## Workspace layout
+
+```text
+~/.klir/
+  config/config.json                 # Bot configuration
+  sessions.json                      # Chat session state
+  named_sessions.json                # Named background sessions
+  tasks.json                         # Background task registry
+  cron_jobs.json                     # Scheduled tasks
+  webhooks.json                      # Webhook definitions
+  agents.json                        # Sub-agent registry (optional)
+  SHAREDMEMORY.md                    # Shared knowledge across all agents
+  CLAUDE.md / AGENTS.md / GEMINI.md  # Rule files
+  logs/agent.log
+  workspace/
+    memory_system/MAINMEMORY.md      # Persistent memory
+    cron_tasks/ skills/ tools/       # Scripts and tools
+    tasks/                           # Per-task folders
+    telegram_files/ output_to_user/  # File I/O
+  agents/<name>/                     # Sub-agent workspaces (isolated)
+```
+
+Full config reference: [`docs/config.md`](docs/config.md)
+
+## Documentation
+
+| Doc | Content |
+|---|---|
+| [System Overview](docs/system_overview.md) | End-to-end runtime overview |
+| [Developer Quickstart](docs/developer_quickstart.md) | Quickest path for contributors |
+| [Architecture](docs/architecture.md) | Startup, routing, streaming, callbacks |
+| [Configuration](docs/config.md) | Config schema and merge behavior |
+| [Automation](docs/automation.md) | Cron, webhooks, heartbeat setup |
+| [Module docs](docs/modules/) | Per-module deep dives |
+
+## Why klir?
+
+Other projects manipulate SDKs or patch CLIs and risk violating provider terms of service. klir simply runs the official CLI binaries as subprocesses — nothing more.
+
+- Official CLIs only (`claude`, `codex`, `gemini`)
+- Rule files are plain Markdown (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`)
+- Memory is one Markdown file per agent
+- All state is JSON — no database, no external services
+
+## Disclaimer
+
+klir runs official provider CLIs and does not impersonate provider clients. Validate your own compliance requirements before unattended automation.
+
+- [Anthropic Terms](https://www.anthropic.com/policies/terms)
+- [OpenAI Terms](https://openai.com/policies/terms-of-use)
+- [Google Terms](https://policies.google.com/terms)
+
+## Contributing
+
+```bash
+git clone https://github.com/js-krinay/klir.git
+cd klir
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest && ruff format . && ruff check . && mypy klir
+```
+
+Zero warnings, zero errors.
+
+## License
+
+[MIT](LICENSE)