{"id":34707706,"url":"https://github.com/avivsinai/telclaude","last_synced_at":"2026-05-28T14:31:24.911Z","repository":{"id":329571311,"uuid":"1106890773","full_name":"avivsinai/telclaude","owner":"avivsinai","description":"Secure Telegram-Claude bridge with LLM-based command screening and tiered permissions","archived":false,"fork":false,"pushed_at":"2026-05-22T13:19:14.000Z","size":5633,"stargazers_count":3,"open_issues_count":10,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-22T18:49:01.413Z","etag":null,"topics":["ai-agent","anthropic","claude","cryptography","docker","isolation","llm","llm-security","permission-tiers","sandbox","security","telegram-bot","typescript"],"latest_commit_sha":null,"homepage":"https://github.com/avivsinai/telclaude","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/avivsinai.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-11-30T06:36:41.000Z","updated_at":"2026-05-17T16:59:02.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/avivsinai/telclaude","commit_stats":null,"previous_names":["avivsinai/telclaude"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/avivsinai/telclaude","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avivsinai%2Ftelclaude","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avivsinai%2Ftelclaude/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avivsinai%2Ftelclaude/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avivsinai%2Ftelclaude/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/avivsinai","download_url":"https://codeload.github.com/avivsinai/telclaude/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/avivsinai%2Ftelclaude/sbom","scorecard":{"id":1240923,"data":{"date":"2025-12-17T10:07:56Z","repo":{"name":"github.com/avivsinai/telclaude","commit":"78cb5a18043ed2c1f1be36bb9fea6241b2ee78dc"},"scorecard":{"version":"v5.0.0","commit":"ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4"},"score":5,"checks":[{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#binary-artifacts"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during branchesHandler.setup: internal error: githubv4.Query: Resource not accessible by integration","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#branch-protection"}},{"name":"CI-Tests","score":10,"reason":"3 out of 3 merged PRs checked by a CI test -- score normalized to 10","details":null,"documentation":{"short":"Determines if the project runs tests before pull requests are merged.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#ci-tests"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#cii-best-practices"}},{"name":"Code-Review","score":0,"reason":"Found 0/27 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#code-review"}},{"name":"Contributors","score":0,"reason":"project has 0 contributing companies or organizations -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project has a set of contributors from multiple organizations (e.g., companies).","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#contributors"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#dangerous-workflow"}},{"name":"Dependency-Update-Tool","score":10,"reason":"update tool detected","details":["Info: detected update tool: Dependabot: .github/dependabot.yml:1"],"documentation":{"short":"Determines if the project uses a dependency update tool.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#dependency-update-tool"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#license"}},{"name":"Maintained","score":0,"reason":"project was created in last 90 days. please review its contents carefully","details":["Warn: Repository was created in last 90 days."],"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#maintained"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#packaging"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:41: update your workflow using https://app.stepsecurity.io/secureworkflow/avivsinai/telclaude/ci.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/ci.yml:44: update your workflow using https://app.stepsecurity.io/secureworkflow/avivsinai/telclaude/ci.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:47: update your workflow using https://app.stepsecurity.io/secureworkflow/avivsinai/telclaude/ci.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:63: update your workflow using https://app.stepsecurity.io/secureworkflow/avivsinai/telclaude/ci.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/ci.yml:66: update your workflow using https://app.stepsecurity.io/secureworkflow/avivsinai/telclaude/ci.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:69: update your workflow using https://app.stepsecurity.io/secureworkflow/avivsinai/telclaude/ci.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:86: update your workflow using https://app.stepsecurity.io/secureworkflow/avivsinai/telclaude/ci.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/ci.yml:89: update your workflow using https://app.stepsecurity.io/secureworkflow/avivsinai/telclaude/ci.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:92: update your workflow using https://app.stepsecurity.io/secureworkflow/avivsinai/telclaude/ci.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:121: update your workflow using https://app.stepsecurity.io/secureworkflow/avivsinai/telclaude/ci.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/ci.yml:124: update your workflow using https://app.stepsecurity.io/secureworkflow/avivsinai/telclaude/ci.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:127: update your workflow using https://app.stepsecurity.io/secureworkflow/avivsinai/telclaude/ci.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:19: update your workflow using https://app.stepsecurity.io/secureworkflow/avivsinai/telclaude/ci.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/ci.yml:22: update your workflow using https://app.stepsecurity.io/secureworkflow/avivsinai/telclaude/ci.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:25: update your workflow using https://app.stepsecurity.io/secureworkflow/avivsinai/telclaude/ci.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/gitleaks.yml:21: update your workflow using https://app.stepsecurity.io/secureworkflow/avivsinai/telclaude/gitleaks.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/gitleaks.yml:26: update your workflow using https://app.stepsecurity.io/secureworkflow/avivsinai/telclaude/gitleaks.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/release.yml:17: update your workflow using https://app.stepsecurity.io/secureworkflow/avivsinai/telclaude/release.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/release.yml:22: update your workflow using https://app.stepsecurity.io/secureworkflow/avivsinai/telclaude/release.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/release.yml:25: update your workflow using https://app.stepsecurity.io/secureworkflow/avivsinai/telclaude/release.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/release.yml:52: update your workflow using https://app.stepsecurity.io/secureworkflow/avivsinai/telclaude/release.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/scorecard.yml:32: update your workflow using https://app.stepsecurity.io/secureworkflow/avivsinai/telclaude/scorecard.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/scorecard.yml:37: update your workflow using https://app.stepsecurity.io/secureworkflow/avivsinai/telclaude/scorecard.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/scorecard.yml:46: update your workflow using https://app.stepsecurity.io/secureworkflow/avivsinai/telclaude/scorecard.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/scorecard.yml:54: update your workflow using https://app.stepsecurity.io/secureworkflow/avivsinai/telclaude/scorecard.yml/main?enable=pin","Warn: containerImage not pinned by hash: docker/Dockerfile:15","Warn: containerImage not pinned by hash: docker/Dockerfile:64","Warn: containerImage not pinned by hash: docker/Dockerfile:72","Warn: containerImage not pinned by hash: docker/Dockerfile.totp:11","Warn: containerImage not pinned by hash: docker/Dockerfile.totp:49","Warn: npmCommand not pinned by hash: docker/Dockerfile:66","Info:   0 out of  16 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of   9 third-party GitHubAction dependencies pinned","Info:   0 out of   5 containerImage dependencies pinned","Info:   0 out of   1 npmCommand dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#pinned-dependencies"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 3 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#sast"}},{"name":"Security-Policy","score":10,"reason":"security policy file detected","details":["Info: security policy file detected: SECURITY.md:1","Info: Found linked content: SECURITY.md:1","Info: Found disclosure, vulnerability, and/or timelines in security policy: SECURITY.md:1","Info: Found text in security policy: SECURITY.md:1"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#security-policy"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#signed-releases"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Info: jobLevel 'contents' permission set to 'read': .github/workflows/scorecard.yml:27","Info: jobLevel 'actions' permission set to 'read': .github/workflows/scorecard.yml:28","Warn: no topLevel permission defined: .github/workflows/ci.yml:1","Info: topLevel 'contents' permission set to 'read': .github/workflows/gitleaks.yml:10","Warn: topLevel 'contents' permission set to 'write': .github/workflows/release.yml:9","Info: topLevel permissions set to 'read-all': .github/workflows/scorecard.yml:15","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#token-permissions"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2026-01-05T21:59:13.501Z","repository_id":329571311,"created_at":"2026-01-05T21:59:13.512Z","updated_at":"2026-01-05T21:59:13.512Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33613431,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-28T02:00:06.440Z","response_time":99,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","anthropic","claude","cryptography","docker","isolation","llm","llm-security","permission-tiers","sandbox","security","telegram-bot","typescript"],"created_at":"2025-12-24T23:31:59.610Z","updated_at":"2026-05-28T14:31:24.904Z","avatar_url":"https://github.com/avivsinai.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# telclaude\n\nIsolation-first Telegram ⇄ agent relay for Claude Code, Codex, and operator workflows, with LLM pre-screening, approvals, and tiered permissions.\n\n[![CI](https://github.com/avivsinai/telclaude/actions/workflows/ci.yml/badge.svg)](https://github.com/avivsinai/telclaude/actions/workflows/ci.yml)\n[![Gitleaks](https://github.com/avivsinai/telclaude/actions/workflows/gitleaks.yml/badge.svg)](https://github.com/avivsinai/telclaude/actions/workflows/gitleaks.yml)\n[![CodeQL](https://github.com/avivsinai/telclaude/actions/workflows/codeql.yml/badge.svg)](https://github.com/avivsinai/telclaude/actions/workflows/codeql.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\n\u003e **Alpha** — Security-first defaults; expect breaking changes until 1.0.\n\n## Highlights\n- Mandatory isolation boundary: SDK sandbox (Seatbelt/bubblewrap) in native mode, relay+agent containers + firewall in Docker mode.\n- Credential vault: sidecar daemon stores API keys and injects them into requests — agents never see raw credentials.\n- Relay-authoritative memory: trusted semantic memory + episodic shared history archive + compiled Claude `MEMORY.md` working set. Private recall is aggressive, but source boundaries remain hard.\n- Hard defaults: secret redaction (CORE patterns + entropy), rate limits, audit log, and fail-closed chat allowlist.\n- Soft controls: Haiku observer, nonce-based approval workflow for FULL_ACCESS, and optional TOTP auth gate for periodic identity verification.\n- Four permission tiers mapped to agent runtime capabilities: READ_ONLY, WRITE_LOCAL, SOCIAL, FULL_ACCESS.\n- Generic social services integration (X/Twitter, Moltbook, Bluesky, etc.) via config-driven `SOCIAL` agent context with unified social persona.\n- External provider sidecars: Google Services (Gmail, Calendar, Drive, Contacts) with approval-gated actions; extensible pattern for adding new providers.\n- Private network allowlist for homelab services (Home Assistant, NAS, etc.) with port enforcement.\n- Runs locally on macOS/Linux or via the Docker Compose stack (Windows through WSL2).\n- No telemetry or analytics; only audit logs you enable in your own environment.\n\n## Documentation map\n| Document | Purpose |\n|----------|---------|\n| This `README.md` | Overview, quick start, configuration |\n| `examples/` | Configuration examples (minimal, personal, team) |\n| `CLAUDE.md` | Agent playbook (auto-loaded by Claude Code) |\n| `AGENTS.md` | Agents guide pointer |\n| `docs/architecture.md` | Architecture design rationale, security model, invariants |\n| `docs/providers.md` | Provider integration guide (sidecar pattern, adding new providers) |\n| `docker/README.md` | Container deployment, firewall, volumes |\n| `CHANGELOG.md` | Version history |\n| `SECURITY.md` | Vulnerability reporting, threat model |\n| `docs/soul.md` | Agent identity, voice, interests |\n\n## Support \u0026 cadence\n- Status: alpha — breaking changes possible until 1.0.\n- Platforms: native mode on macOS 14+ or Linux (bubblewrap+socat+rg); Docker/WSL recommended for prod.\n- Issues/PR triage: weekly; security reports acknowledged within 48h.\n- Releases: ad-hoc during alpha; aim for monthly.\n- Security contact: project maintainer(s) via GitHub security advisory.\n\n## Permission tiers (at a glance)\n| Tier | What it can do | Safeguards |\n| --- | --- | --- |\n| READ_ONLY | Read files, search, web fetch/search | No writes; sandbox + secret filter |\n| WRITE_LOCAL | READ_ONLY + write/edit/bash | Blocks destructive bash (rm/chown/kill, etc.); denyWrite patterns |\n| SOCIAL | File tools + Bash + WebFetch/WebSearch | Bash trust-gated by actor type; WebFetch permissive; protected paths blocked |\n| FULL_ACCESS | All tools | Every request requires human approval; still sandboxed |\n\n## Architecture\n\n```\n                            Telegram\n                               │\n                               ▼\n┌──────────────────────────────────────────────────────────────────┐\n│                        Security Layer                            │\n│  ┌────────────┐   ┌────────────┐   ┌──────────┐   ┌──────────┐  │\n│  │ Fast Path  │──▶│  Observer  │──▶│   Rate   │──▶│ Approval │  │\n│  │  (regex)   │   │  (Haiku)   │   │  Limit   │   │ (human)  │  │\n│  └────────────┘   └────────────┘   └──────────┘   └──────────┘  │\n└──────────────────────────────────────────────────────────────────┘\n                               │\n                               ▼\n┌──────────────────────────────────────────────────────────────────┐\n│                       Permission Tiers                           │\n│  READ_ONLY    WRITE_LOCAL    SOCIAL         FULL_ACCESS        │\n│  (5 tools)    (8 tools)     (trust-gated)  (all, +approval)   │\n└──────────────────────────────────────────────────────────────────┘\n                               │\n                               ▼\n┌──────────────────────────────────────────────────────────────────┐\n│            Isolation Boundary (mode-dependent)                   │\n│   Docker: relay+agent + firewall  │  Native: SDK sandbox         │\n│          (SDK sandbox off)        │  (Seatbelt/bwrap)            │\n└──────────────────────────────────────────────────────────────────┘\n                               │\n                               ▼\n                        Claude Agent SDK\n\n┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐\n│   TOTP Daemon    │  │  Vault Daemon    │  │ Google Services  │\n│  (OS keychain)   │  │ (credential      │  │ (Gmail, Calendar │\n└──────────────────┘  │  injection)      │  │  Drive, Contacts)│\n                      └──────────────────┘  └──────────────────┘\n```\n\n## Requirements\n- Node 20+, pnpm 9.x\n- Claude CLI (`brew install anthropic-ai/cli/claude`) — current primary runtime. In Docker, telclaude routes Anthropic access through the relay proxy; if you use OAuth, run `claude login` in the relay container with `CLAUDE_CONFIG_DIR=/home/telclaude-auth` so tokens live in the dedicated auth profile.\n- Codex CLI (`codex`) — first-class peer runtime surface. For write-capable Codex work, configure a dedicated `CODEX_HOME`; `telclaude runtimes status` reports whether Codex would use controlled or global config.\n- Telegram bot token from @BotFather\n- Native mode: macOS 14+ or Linux with `bubblewrap`, `socat`, and `ripgrep` available on PATH\n- Docker/WSL: Docker + Compose (no host bubblewrap required)\n- Optional but recommended: TOTP daemon uses the OS keychain (keytar)\n\n## Third-party terms\n- This project depends on `@anthropic-ai/claude-agent-sdk`, which is distributed under Anthropic's Claude Code legal agreements (see its `LICENSE.md` in `node_modules/` after install).\n\n## Quick start (Docker, recommended for prod)\n```bash\ngit clone https://github.com/avivsinai/telclaude.git\ncd telclaude/docker\ncp .env.example .env   # set TELEGRAM_BOT_TOKEN, WORKSPACE_PATH, TOTP_ENCRYPTION_KEY, run `telclaude keygen telegram` and `telclaude keygen social` for RPC keys, ANTHROPIC_PROXY_TOKEN\ncp telclaude.json.example telclaude.json\ncp telclaude-private.json.example telclaude-private.json\ndocker compose up -d --build\ndocker compose exec -e CLAUDE_CONFIG_DIR=/home/telclaude-auth telclaude claude login  # optional if not using ANTHROPIC_API_KEY\n```\nSee `docker/README.md` for firewall, volume, and upgrade details.\nThis starts 6 containers: `telclaude` (relay), `telclaude-agent` (private persona), `agent-social` (social persona), `google-services` (Google sidecar), `totp`, and `vault`.\n\nNote: Docker uses a shared **skills** profile (`/home/telclaude-skills`) and a relay-only **auth** profile (`/home/telclaude-auth`). Agents access Anthropic through the relay proxy; credentials never mount in agent containers.\n\nThe relay also compiles private Telegram memory into the agent's Claude project-memory path under `/home/telclaude-skills/projects/\u003cproject-slug\u003e/memory/MEMORY.md`. That file is a working-set cache, not the source of truth.\n\n## Quick start (local)\n1) Clone and install\n```bash\ngit clone https://github.com/avivsinai/telclaude.git\ncd telclaude\npnpm install\n```\n2) Create config (JSON5) at `~/.telclaude/telclaude.json` — allowlist is required or the bot will ignore all chats (fail-closed).\n```json\n{\n  \"telegram\": {\n    \"botToken\": \"123456:ABC-DEF\",\n    \"allowedChats\": [123456789]      // your Telegram numeric chat ID\n  },\n  \"security\": {\n    \"profile\": \"strict\",             // simple | strict | test\n    \"permissions\": {\n      \"users\": {\n        \"tg:123456789\": { \"tier\": \"FULL_ACCESS\" }\n      }\n    }\n  }\n}\n```\nNotes: `defaultTier=FULL_ACCESS` is intentionally rejected at runtime. Prefer putting `botToken` in the config for native installs; `TELEGRAM_BOT_TOKEN` is accepted (mainly for Docker).\n\n3) Authenticate Claude\n```bash\nclaude login             # API key is not forwarded into sandboxed agent\n```\n\n4) (Recommended) Start TOTP daemon in another terminal\n```bash\npnpm dev maintenance totp-daemon\n```\n\n5) Health check\n```bash\npnpm dev doctor --network --secrets\n```\n\n6) Run the relay\n```bash\n# Development (native: SDK sandbox via @anthropic-ai/sandbox-runtime; if unavailable, use Docker below)\npnpm dev relay --profile simple\n\n# Recommended / Production: Docker or WSL with container boundary + firewall\ndocker compose up -d --build\ndocker compose exec telclaude pnpm start relay --profile strict\n```\n\n7) First admin claim\n- DM your bot from the allowed chat; it replies with `/approve \u003ccode\u003e`.\n- Send that command back to link the chat as admin (FULL_ACCESS with per-request approvals).\n- In the same chat, run `/auth setup` to bind TOTP for periodic identity verification (daemon must be running). `/auth skip` is allowed but not recommended.\n- Optional hardening: set `TELCLAUDE_ADMIN_SECRET` and start with `/claim \u003csecret\u003e` to prevent scanner bots claiming admin first (see `SECURITY.md`).\n\n## Telegram command surface\n- Chat normally — anything not starting with `/` goes to the AI agent.\n- `/help \u003ctopic\u003e` — contextual help for approvals, 2fa, sessions, etc.\n- `/system` — system status, sessions, cron (card-based with inline buttons).\n- `/me`, `/auth`, `/social`, `/skills` — identity, 2FA, social persona, skill management.\n- `/profile list|switch \u003cid\u003e|reset` — inspect or switch the active operator profile for the chat.\n- `/curator` — review local automation suggestions and accept/reject without executing the action.\n- `/codex [--model \u003cid\u003e] [--cwd \u003crelative-path\u003e] [--write] \u003cprompt\u003e` — queue a single-shot Codex work unit; results return as a background job card. Supported overrides are `gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.3-codex`, `gpt-5.3-codex-spark`, and `gpt-5.2`.\n- `/approve`, `/new` — fast-path shortcuts for approvals and session reset.\n\n## Memory model\n\nTelclaude uses three memory layers for the private persona:\n\n1. **Semantic memory** — durable entries in the relay database (`profile`, `interests`, `meta`, `threads`). This is the authoritative store.\n2. **Episodic archive** — relay-owned summaries of private turns used for recent and query-relevant shared-history recall.\n3. **Compiled Claude working memory** — a generated `MEMORY.md` file materialized into Claude's local project-memory path before a query starts.\n\nThe agent never owns the source of truth. The relay assembles a scoped memory bundle, injects it into the prompt as read-only data, materializes the compiled `MEMORY.md`, and then captures successful turns back into the episodic archive. Automatic memory extraction is conservative: explicit durable facts are promoted automatically, while secrets and instruction-like content are rejected or sanitized.\n\nInspect the current private memory bundle with:\n\n```bash\npnpm dev memory context --chat-id \u003ctelegram-chat-id\u003e --query \"oauth vault refresh\"\npnpm dev memory context --chat-id \u003ctelegram-chat-id\u003e --markdown\n```\n\n`--chat-id` resolves that chat's active operator profile before reading memory. Private memory is stored under `telegram:\u003cprofile-id\u003e` sources, so switching `/profile` changes the semantic and episodic memory namespace used by normal replies, scheduled private runs, and local memory inspection.\n\n## Configuration\n- Default path: `~/.telclaude/telclaude.json` (override with `TELCLAUDE_CONFIG` or `--config`).\n- Security profiles:\n  - `simple` (default): sandbox + secret filter + rate limits + audit.\n  - `strict`: adds Haiku observer, approval workflow, and tiered tool gates.\n  - `test`: disables all enforcement; requires `TELCLAUDE_ENABLE_TEST_PROFILE=1`.\n- Operator profiles:\n  - Configure top-level `profiles[]` entries with `id`, `label`, optional `description`, `soulPath`, `allowedSkills`, and `defaultModel`.\n  - `soulPath` points to a profile-specific prompt overlay.\n  - `allowedSkills` narrows private-agent skill loading for that profile; omit it to allow all private skills.\n  - `defaultModel` uses `{ \"providerId\": \"anthropic\", \"modelId\": \"claude-sonnet-4-5-20250929\" }` and is overridden by explicit chat `/model` choices.\n  - Telegram admins switch a chat with `/profile switch \u003cid\u003e` and return to the implicit default with `/profile reset`.\n- Permission tiers:\n  - `READ_ONLY`: read/search/web only; no writes.\n  - `WRITE_LOCAL`: read/write/edit/bash with destructive commands blocked.\n  - `SOCIAL`: file tools + Bash + WebFetch/WebSearch; Bash trust-gated by actor; protected paths blocked.\n  - `FULL_ACCESS`: unrestricted tools but every request needs human approval.\n  - Set per-user under `security.permissions.users`; `defaultTier` stays `READ_ONLY`.\n- Optional group guardrail:\n  - `telegram.groupChat.requireMention: true` to ignore group/supergroup messages unless they mention the bot or reply to it.\n- OpenAI/GitHub key exposure (tier-based):\n  - FULL_ACCESS tier automatically gets configured API keys (OpenAI, GitHub) exposed to sandbox.\n  - READ_ONLY and WRITE_LOCAL tiers never get keys.\n  - Configure keys via `telclaude secrets setup-openai` / `telclaude secrets setup-git` or env vars.\n  - **Security note:** keys are exposed to the model in FULL_ACCESS; use restricted keys if concerned.\n- Rate limits and audit logging are on by default; see `CLAUDE.md` for full schema and options.\n\n## Credential vault\n\nThe vault daemon stores API credentials and injects them into HTTP requests transparently — agents never see raw credentials. This feature is primarily designed for Docker deployments with a remote agent.\n\n**How it works (Docker/remote agent mode):**\n1. Vault daemon runs as a sidecar (Unix socket, no network except OAuth refresh)\n2. HTTP proxy on relay (port 8792) intercepts requests like `http://relay:8792/api.openai.com/v1/...`\n3. Proxy looks up credentials by host, injects auth headers, forwards to upstream\n4. Agent receives response without ever seeing the API key\n\n**Note:** The HTTP credential proxy is only started when a remote agent is configured (`TELCLAUDE_AGENT_URL`). Native mode uses direct key exposure for FULL_ACCESS tier instead (see Configuration section).\n\n**Supported auth types:** `bearer`, `api-key`, `basic`, `query`, `oauth2` (with automatic token refresh)\n\n**Security properties:**\n- Credentials encrypted at rest (AES-256-GCM)\n- Host allowlist prevents injection to unexpected destinations\n- Optional path restrictions per host\n- Socket permissions 0600\n\n**Quick setup:**\n```bash\n# Generate encryption key\nexport VAULT_ENCRYPTION_KEY=$(openssl rand -base64 32)\n\n# Start vault daemon\ntelclaude maintenance vault-daemon\n\n# Add a credential\ntelclaude vault add http api.openai.com --type bearer --label \"OpenAI\"\n# (prompts for token securely)\n\n# List credentials\ntelclaude vault list\n```\n\nSee `docs/architecture.md` for vault design rationale. CLI reference: `telclaude vault --help`.\n\n## Private network allowlist\n\nFor local services (Home Assistant, NAS, Plex, etc.), configure explicit private endpoints:\n\n```json\n{\n  \"security\": {\n    \"network\": {\n      \"privateEndpoints\": [\n        { \"label\": \"home-assistant\", \"host\": \"192.168.1.100\", \"ports\": [8123] },\n        { \"label\": \"homelab\", \"cidr\": \"192.168.1.0/24\", \"ports\": [80, 443] }\n      ]\n    }\n  }\n}\n```\n\n**CLI:**\n```bash\ntelclaude dev network list\ntelclaude dev network add ha --host 192.168.1.100 --ports 8123\ntelclaude dev network test http://192.168.1.100:8123/api\n```\n\nMetadata endpoints (169.254.169.254) and link-local addresses remain blocked regardless of allowlist.\n\n## External providers (sidecars)\nTelclaude integrates with private REST API sidecars via relay-proxied requests. Agents never call provider endpoints directly (enforced at both application and firewall layers).\n\n**Built-in provider:** Google Services (Gmail, Calendar, Drive, Contacts) -- 4 services, 20 actions with approval-gated mutations. Setup: `telclaude providers setup google --base-url http://google-services:3001`.\n\n**Configuration:**\n- Add providers to `telclaude.json` under `providers[]` (id, baseUrl, services list).\n- See `docs/providers.md` for the full integration guide, including how to add new providers.\n\n**Required endpoints:**\n\n| Endpoint | Method | Purpose |\n|----------|--------|---------|\n| `/v1/health` | GET | Health check (returns JSON with status field) |\n| `/v1/schema` | GET | Action catalog for auto-discovery and skill docs |\n| `/v1/fetch` | POST | Dispatch service action (body: `{ service, action, params }`) |\n\nOptional: `/v1/challenge/respond` (POST) for OTP/2FA completion.\n\n## CLI reference\n\n### Core\n| Command | Description |\n|---------|-------------|\n| `telclaude relay [--profile simple\\|strict\\|test] [--dry-run]` | Start the relay |\n| `telclaude quickstart` | Interactive first-time setup |\n| `telclaude doctor [--network] [--secrets]` | Health check |\n| `telclaude status [--json]` | Show relay status |\n| `telclaude runtimes status [--json]` | Show Claude Code and Codex runtime readiness |\n\n### Authentication \u0026 access control\n| Command | Description |\n|---------|-------------|\n| `telclaude link \u003cuser-id\u003e \\| --list \\| --remove \u003cchat-id\u003e` | Manage identity links |\n| `telclaude maintenance totp-daemon [--socket-path \u003cpath\u003e]` | Start TOTP daemon |\n| `telclaude auth totp-setup \u003cuser-id\u003e` | Set up TOTP for a user |\n| `telclaude auth totp-disable \u003cuser-id\u003e` | Disable TOTP for a user |\n| `telclaude maintenance reset-auth [--force]` | Reset auth state |\n| `telclaude admin ban \u003cchat-id\u003e [-r \u003creason\u003e]` | Block a chat |\n| `telclaude admin unban \u003cchat-id\u003e` | Restore access |\n| `telclaude auth force-reauth \u003cchat-id\u003e` | Invalidate TOTP session |\n| `telclaude admin list-bans` | Show banned chats |\n\n### Credential vault\n| Command | Description |\n|---------|-------------|\n| `telclaude maintenance vault-daemon` | Start vault daemon |\n| `telclaude vault list` | List stored credentials |\n| `telclaude vault add http \u003chost\u003e --type \u003ctype\u003e [--label \u003cname\u003e]` | Add credential |\n| `telclaude vault remove http \u003chost\u003e` | Remove credential |\n| `telclaude vault test http \u003chost\u003e` | Test credential injection |\n\n### API key \u0026 service setup\n| Command | Description |\n|---------|-------------|\n| `telclaude secrets setup-openai` | Configure OpenAI API key |\n| `telclaude secrets setup-git` | Configure Git credentials |\n| `telclaude secrets setup-github-app` | Configure GitHub App |\n| `telclaude secrets setup-google` | Configure Google OAuth credentials (for Google Services sidecar) |\n\n### Network \u0026 providers\n| Command | Description |\n|---------|-------------|\n| `telclaude dev network list` | List private endpoints |\n| `telclaude dev network add \u003clabel\u003e (--host \u003cip\u003e \\| --cidr \u003crange\u003e) [--ports \u003cports\u003e]` | Add endpoint |\n| `telclaude dev network remove \u003clabel\u003e` | Remove endpoint |\n| `telclaude dev network test \u003curl\u003e` | Test endpoint access |\n| `telclaude providers init \u003cid\u003e [--services \u003ccsv\u003e]` | Scaffold a provider sidecar |\n| `telclaude providers list` | List configured providers |\n| `telclaude providers add \u003cid\u003e --base-url \u003curl\u003e --services \u003ccsv\u003e` | Add a custom provider |\n| `telclaude providers edit \u003cid\u003e --base-url \u003curl\u003e --services \u003ccsv\u003e` | Edit a provider |\n| `telclaude providers remove \u003cid\u003e` | Remove a provider |\n| `telclaude providers refresh` | Refresh provider schema and runtime skill state |\n| `telclaude providers schema [id]` | Fetch provider schema |\n| `telclaude providers query \u003cid\u003e \u003csvc\u003e \u003cact\u003e` | Query external provider |\n| `telclaude providers doctor [id]` | Check provider health |\n| `telclaude providers setup google --base-url \u003curl\u003e` | Configure Google provider end-to-end |\n\n### Media \u0026 messaging\n| Command | Description |\n|---------|-------------|\n| `telclaude send \u003cchatId\u003e [message] [--media \u003cpath\u003e] [--caption \u003ctext\u003e]` | Send message/media |\n| `telclaude send-file --path \u003cpath\u003e [--filename \u003cname\u003e]` | Send workspace file to Telegram |\n| `telclaude send-local-file --path \u003cpath\u003e [--filename \u003cname\u003e]` | Backward-compatible alias for sending workspace files |\n| `telclaude send-attachment --ref \u003cref\u003e` | Send provider attachment via ref token |\n| `telclaude fetch-attachment --provider \u003cid\u003e --id \u003cattachment-id\u003e` | Download provider attachment |\n| `telclaude generate-image \u003cprompt\u003e [-s \u003csize\u003e] [-q \u003cquality\u003e]` | Generate image (requires OpenAI) |\n| `telclaude text-to-speech \u003ctext\u003e [-v \u003cvoice\u003e] [-f \u003cformat\u003e]` | Text-to-speech (requires OpenAI) |\n\n### Memory, cron \u0026 Curator\n| Command | Description |\n|---------|-------------|\n| `telclaude memory read --chat-id \u003cid\u003e --categories profile,interests` | Read memory entries for the chat's active profile |\n| `telclaude memory context --chat-id \u003cid\u003e [--markdown]` | Render the compiled private memory bundle |\n| `telclaude memory write \"fact\" --chat-id \u003cid\u003e --category meta` | Write memory under the chat's active profile |\n| `telclaude maintenance cron status` | Cron scheduler status |\n| `telclaude maintenance cron list [--all] [--json]` | List cron jobs |\n| `telclaude maintenance cron add --name \u003cn\u003e --every \u003cdur\u003e\\|--cron \u003cexpr\u003e` | Add cron job |\n| `telclaude maintenance cron run \u003cid\u003e` | Run cron job immediately |\n| `telclaude curator scan\\|list\\|show\\|accept\\|reject` | Review local Curator suggestions |\n| `telclaude curator sign-producer --item item.json --producer-kind codex --producer-id codex:\u003cid\u003e` | Sign a Codex/Claude Curator item through the vault |\n| `telclaude curator submit-signed --item item.json --envelope envelope.json` | Verify and submit a signed producer Curator item |\n\n### Diagnostics\n| Command | Description |\n|---------|-------------|\n| `telclaude diagnose-sandbox-network` | Debug sandbox network issues |\n| `telclaude integration-test [--all] [--agents]` | Run SDK integration tests (optional direct agent transport check with `--agents`) |\n| `telclaude reset-db [--force]` | Delete SQLite database (requires `TELCLAUDE_ENABLE_RESET_DB=1`) |\n\n## Usage example\nRun strict profile with approvals and TOTP:\n```bash\npnpm dev maintenance totp-daemon \u0026\npnpm dev relay --profile strict\n# In Telegram (allowed chat):\n# 1) bot replies with /approve CODE for admin claim\n# 2) run /auth setup to bind TOTP\n```\n\nUse `pnpm dev \u003ccommand\u003e` during development (tsx). For production: `pnpm build \u0026\u0026 pnpm start \u003ccommand\u003e` (runs from `dist/`).\n\n## Deployment\n- **Production (mandatory): Docker/WSL Compose stack** (`docker/README.md`). Relay+agent containers + firewall; SDK sandbox disabled in Docker mode. Use this on shared or multi-tenant hosts.\n- **Development:** Native macOS/Linux with SDK sandbox (Seatbelt/bubblewrap). SDK sandbox provides OS-level isolation for Bash; WebFetch/WebSearch are filtered by hooks/allowlists. Keep `~/.telclaude/telclaude.json` chmod 600.\n\n## Development\n- Lint/format: `pnpm lint`, `pnpm format`\n- Types: `pnpm typecheck`\n- Tests: `pnpm test` or `pnpm test:coverage`\n- Build: `pnpm build`\n- Local CLI: `pnpm dev relay`, `pnpm dev doctor`, etc.\n- Secrets scan: `brew install gitleaks` (or download binary) then `pnpm security:scan` (uses `.gitleaks.toml`)\n\n## Security \u0026 reporting\n- Default stance is fail-closed (empty `allowedChats` denies all; `defaultTier=FULL_ACCESS` is rejected).\n- Native mode requires the SDK sandbox; relay exits if Seatbelt/bubblewrap (or socat on Linux) is unavailable. Docker mode requires the firewall (containers enforce it).\n- Vulnerabilities: please follow `SECURITY.md` for coordinated disclosure.\n- Security contact: project maintainer(s) via GitHub security advisory.\n\n## Troubleshooting (quick)\n| Symptom | Likely cause | Fix |\n| --- | --- | --- |\n| Bot silent/denied | `allowedChats` empty or rate limit hit | Add your chat ID and rerun; check audit/doctor |\n| Sandbox unavailable (native) | seatbelt/bubblewrap/rg/socat missing | Install deps (see Requirements section above) |\n| TOTP fails | Daemon not running or clock drift | Start `telclaude maintenance totp-daemon`; sync device time |\n| SDK/observer errors | Claude CLI missing or not logged in | `brew install anthropic-ai/cli/claude \u0026\u0026 claude login` (Docker: `docker compose exec -e CLAUDE_CONFIG_DIR=/home/telclaude-auth telclaude claude login`) |\n| Vault not injecting | Daemon not running or host not configured | Start `telclaude maintenance vault-daemon`; check `vault list` |\n\n## Community\n- Issues \u0026 discussions: open GitHub issues; we triage weekly.\n- Changelog: see `CHANGELOG.md`.\n\n## Acknowledgments\n\nInspired by [Clawdis](https://github.com/steipete/clawdis) by [@steipete](https://github.com/steipete).\n\n## Disclaimer\n\nProvided as-is for authorized use only. Use at your own risk.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Favivsinai%2Ftelclaude","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Favivsinai%2Ftelclaude","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Favivsinai%2Ftelclaude/lists"}