{"id":51433017,"url":"https://github.com/jimovonz/claude-assist","last_synced_at":"2026-07-05T05:03:10.036Z","repository":{"id":346027554,"uuid":"1188301760","full_name":"jimovonz/claude-assist","owner":"jimovonz","description":"Personal AI assistant — multi-channel access to Claude Code via Conduit","archived":false,"fork":false,"pushed_at":"2026-04-17T10:18:03.000Z","size":319,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-17T12:23:06.271Z","etag":null,"topics":["ai-assistant","bun","claude-code","memory","telegram"],"latest_commit_sha":null,"homepage":null,"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/jimovonz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-21T22:17:42.000Z","updated_at":"2026-04-17T10:18:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jimovonz/claude-assist","commit_stats":null,"previous_names":["jimovonz/claude-assist"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jimovonz/claude-assist","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimovonz%2Fclaude-assist","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimovonz%2Fclaude-assist/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimovonz%2Fclaude-assist/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimovonz%2Fclaude-assist/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jimovonz","download_url":"https://codeload.github.com/jimovonz/claude-assist/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jimovonz%2Fclaude-assist/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35143802,"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-07-05T02:00:06.290Z","response_time":100,"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-assistant","bun","claude-code","memory","telegram"],"created_at":"2026-07-05T05:03:09.389Z","updated_at":"2026-07-05T05:03:10.028Z","avatar_url":"https://github.com/jimovonz.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# claude-assist\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n\u003e **Work in Progress.** This project is functional but experimental and tightly coupled to a specific personal Linux infrastructure setup — a particular GCE instance, Google Cloud project, OAuth credentials, and Telegram bot. It is built for and tested on Linux only (Ubuntu/Debian with systemd). No effort has been made yet to generalise configuration, provide setup automation, or support other platforms. If you're interested in running something similar, the code and architecture are here to learn from, but expect to adapt significantly to your own environment.\n\n**Talk to Claude Code from anywhere. Telegram, browser, terminal. One session, full memory, all your tools.**\n\nclaude-assist wraps Claude Code in a multi-channel routing layer called **Conduit**. You message a Telegram bot on your phone, Conduit pipes it into a persistent `claude -p` process with full tool access, streams status updates back, and delivers the response — with rich HTML views for long output via a GCE edge server.\n\nPaired with [Cairn](https://github.com/jimovonz/cairn), every conversation across every channel feeds the same persistent memory. Context from a terminal session surfaces in Telegram. A decision made on your phone is remembered on your laptop.\n\n---\n\n## How it works\n\n```\n┌──────────────────────────────────────────────────┐\n│                Conduit (Bun)                      │\n│                                                   │\n│  Telegram ──┐                                     │\n│  TUI ───────┤── Router ── Session Manager         │\n│  Remote TUI ┘      │          │                   │\n│                    │     claude -p (persistent)    │\n│               Commands    stream-json I/O          │\n│               Cairn Hooks                          │\n│                                                   │\n│  Scheduler ── Task CLI ── Scheduled Tasks (SQLite) │\n│  Email Agent ── Gmail Push ── Classification       │\n│  Location ── OwnTracks ── Geofences (SQLite)       │\n│  View Server ── GCE Edge ── HTTPS (SSL)           │\n└──────────────────────────────────────────────────┘\n         ↕                ↕              ↕\n    Gmail Pub/Sub    Google Calendar   OwnTracks\n```\n\n1. **Message arrives** from any channel (Telegram, TUI, Remote TUI)\n2. **Commands intercepted** (`/tasks`, `/clear`, etc.) or **Cairn prompt hook** injects memory context\n3. **Persistent Claude process** receives the message via stream-json stdin\n4. **Status streams back** — tool calls, text previews, heartbeats — edited in place\n5. **Cairn stop hook** stores memories, retrieves context if insufficient\n6. **Response delivered** — short text inline, long responses as HTML view links\n7. **Scheduled tasks** fire on cron/one-shot, results route to Telegram\n8. **Gmail push** triggers email classification, labeling, calendar events, actionable alerts\n\n## Key features\n\n- **Persistent sessions** — one `claude -p` process per channel, kept alive. No cold start after the first message.\n- **Full Claude Code** — tools, file access, shell commands, web search. Not a limited chat mode.\n- **Cairn memory** — proactive context injection via prompt hook, memory storage via stop hook. Cross-session, cross-channel.\n- **Streaming status** — Telegram shows what Claude is doing in real time (reading files, running commands, thinking). Edits one message in place, 5s throttle.\n- **Rich HTML views** — long responses rendered as styled pages served via GCE edge server (HTTPS). Interactive action buttons (button, select, checkbox, text) with POST-back routing.\n- **Scheduled tasks** — cron and one-shot scheduling with per-task model selection (Haiku for monitoring, Opus for analysis), LLM-controlled notifications (`auto` mode — Claude decides whether to alert), context files, Cairn memory queries, session strategies (fresh/resume), and reply-to routing.\n- **Email agent** — Gmail push notifications via Pub/Sub trigger instant email classification. Applies intelligent labels (`CA/` prefix), creates calendar events for time-sensitive items, only notifies for personally-addressed actionable emails. Silent for newsletters, marketing, automated. Deduplication via SQLite persistence survives restarts — processed emails tracked with 7-day retention.\n- **Location tracking** — OwnTracks GPS updates via edge server, stored in SQLite with accuracy/velocity/battery metadata. Named geofences with configurable radius, haversine distance calculations, automatic geofence matching on each update.\n- **Google API access** — Gmail (read/send/label/watch) and Calendar (create/list/free) available from any channel. Natural language calendar creation (\"put a meeting with Dave on Thursday at 2pm\").\n- **Session isolation** — each channel gets its own conversation context. Telegram chat doesn't bleed into TUI work.\n- **Message queuing** — rapid messages are queued per channel, preventing concurrent session corruption.\n\n## Quick start\n\n```bash\n# Clone\ngit clone https://github.com/jimovonz/claude-assist.git\ncd claude-assist\n\n# Install\nbun install\n\n# Configure\ncp .env.example .env\n# Edit .env: add your TELEGRAM_BOT_TOKEN from @BotFather\n\n# Run\nbun run start\n```\n\n### Requirements\n\n- [Bun](https://bun.sh) runtime\n- [Claude Code](https://code.claude.com) with a claude.ai subscription\n- A Telegram bot token from [@BotFather](https://t.me/BotFather)\n- [Cairn](https://github.com/jimovonz/cairn) for memory (optional but recommended)\n- Python 3.10+ with `google-auth-oauthlib` and `google-api-python-client` (for Gmail/Calendar — uses Cairn's venv)\n- Google Cloud project with OAuth credentials and Gmail/Calendar/Pub/Sub APIs enabled (for email agent)\n- GCE instance with Apache + SSL for edge server (for remote TUI and Gmail push webhook)\n\n### Environment variables\n\n```\nTELEGRAM_BOT_TOKEN=     # Required — from @BotFather\nTELEGRAM_OWNER_ID=      # Optional — receives restart notifications\nVIEW_PORT=8099          # Optional — view server port (default: 8099)\nVIEW_BASE_URL=          # Optional — base URL for view links\nEDGE_URL=               # Optional — GCE edge server for remote TUI access\nEDGE_API_SECRET=        # Optional — edge API auth token\nTUI_AUTH_TOKEN=          # Optional — WebSocket auth for TUI clients\nCAIRN_DIR=              # Optional — path to cairn repo (default: ~/Projects/cairn)\nCLOUDFLARE_TUNNEL_TOKEN= # Optional — for named Cloudflare tunnel\n```\n\n## Architecture\n\nSee [ARCHITECTURE.md](ARCHITECTURE.md) for the full architectural breakdown, design decisions, and lessons learned.\n\n### Components\n\n| Component | File | Purpose |\n|-----------|------|---------|\n| **Session Manager** | `src/conduit/session.ts` | Persistent `claude -p` processes per channel, stream-json I/O, per-session model selection |\n| **Router** | `src/conduit/router.ts` | Channel routing, Cairn hook integration, status streaming, view creation, centralized commands |\n| **Scheduler** | `src/conduit/scheduler.ts` | Cron + one-shot task scheduling, LLM-controlled notifications, context injection |\n| **Commands** | `src/conduit/commands.ts` | Centralized `/tasks`, `/task`, `/clear`, `/context`, `/sessions`, `/help` |\n| **Task CLI** | `bin/task-cli.ts` | CLI for Claude subprocess to create/manage scheduled tasks |\n| **Email Agent** | `src/conduit/email-agent.ts` | Gmail push processing: classification, labeling, calendar events, notifications |\n| **Gmail Helpers** | `bin/gmail-*.py` | Gmail API: check, label, send, watch (OAuth, Python) |\n| **Calendar Helper** | `bin/gcal.py` | Google Calendar: create, list, today, free slots (OAuth, Python) |\n| **Telegram** | `src/conduit/channels/telegram/` | Grammy bot, status edits, typing indicator, task reply routing |\n| **WebSocket/TUI** | `src/conduit/channels/websocket/` | WebSocket channel for local and remote TUI clients |\n| **Edge Relay** | `src/service/edge-relay.ts` | Outbound WebSocket to GCE edge for NAT-friendly remote TUI access, OwnTracks location forwarding |\n| **State** | `src/conduit/state.ts` | SQLite persistence — sessions, tasks, processed emails, locations, location history |\n| **Hooks** | `src/conduit/hooks.ts` | Cairn prompt/stop hook runners |\n| **View Renderer** | `src/views/renderer.ts` | Markdown-to-HTML with XSS prevention |\n| **View Server** | `src/views/server.ts` | Bun.serve() for HTML views, WebSocket, health endpoint, auto-cleanup |\n| **Tunnel** | `src/service/tunnel.ts` | Cloudflare Tunnel management (named or quick) |\n| **Watchdog** | `src/service/watchdog.ts` | systemd watchdog integration via FFI |\n| **systemd** | `src/service/systemd.ts` | Service unit generation, install, status, logs |\n\n### Conduit naming\n\n- **claude-assist** — the project\n- **Conduit** — the session manager and channel routing layer\n- **Cairn** — the persistent memory system ([separate repo](https://github.com/jimovonz/cairn))\n\n## Status\n\nFunctional multi-channel assistant with Telegram, TUI, remote TUI access, and HTML views.\n\n**Done:**\n- [x] Telegram channel with status streaming, message chunking, and commands\n- [x] WebSocket/TUI channel with auth, streaming, and session restore\n- [x] Remote TUI access via GCE edge relay (NAT-friendly outbound WebSocket)\n- [x] Cloudflare Tunnel integration (named or quick)\n- [x] systemd service with watchdog integration\n- [x] Session persistence across restarts (SQLite)\n- [x] HTML view rendering with edge push and Telegram Mini App support\n- [x] Cairn memory integration (prompt and stop hooks)\n- [x] Scheduled agent tasks — cron, one-shot, per-task model, LLM-controlled notifications, context files/queries, reply-to routing\n- [x] Centralized commands (`/tasks`, `/task`, `/clear`, `/context`, `/sessions`, `/help`) across all channels\n- [x] Email agent — Gmail push notifications, intelligent classification/labeling, auto calendar events, actionable-only alerts, dedup persistence\n- [x] Google API integration — Gmail (read/send/label), Calendar (CRUD), accessible from all channels via system prompt\n- [x] Location tracking — OwnTracks integration, geofences, location history\n- [x] SSL on GCE edge server (Let's Encrypt)\n- [x] Global operational docs — `CLAUDE-global.md` symlinked to `~/.claude/rules/` for cross-project Claude sessions\n\n**Planned:**\n- [ ] Location-aware features — reminders, context injection based on geofence transitions\n- [ ] Email drafting with review/approval flow (careful scoping required)\n- [ ] Generalised setup and configuration for wider accessibility\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjimovonz%2Fclaude-assist","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjimovonz%2Fclaude-assist","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjimovonz%2Fclaude-assist/lists"}