Background
Running a household generates constant low-grade mental overhead — dentist appointments to reschedule, HVAC filters, school deadlines, follow-up calls that slip. My wife and I were managing all of it across text messages and memory.
I wanted a single shared system both of us could talk to in plain language, without installing anything new. Telegram was already on both our phones.
What it does
The assistant runs across three Telegram chats simultaneously — my personal chat, my wife's, and a shared family group. All three read and write to the same task inventory. Either of us can add, check, or complete a task and the other sees it instantly.
- Task management — Add, update, and complete tasks by category (Home, Health, Finance, Car, School, Family), with priority and due dates
- Reminders — One-shot or recurring reminders that fire a direct message at the right time, with no agent overhead
- Web lookup — Find a phone number, business hours, or service provider on demand and attach that context directly to the relevant task
- Daily morning briefing — Every morning at 8am, a conversational summary of overdue items, what's due this week, and high-priority tasks — grouped by category, not a raw dump
How it's built
The core is a Node.js/TypeScript process handling Telegram polling, a SQLite database for shared state, a cron-based scheduler, and an IPC file-watching loop — built on NanoClaw, a minimalist AI agent orchestration framework.
When a message comes in, it routes to an isolated Docker container running a Claude agent. Each family member's chat gets its own container with its own filesystem and session context. The agent communicates back to the host exclusively through IPC files — it cannot touch the database or network stack directly. The host validates intent and applies changes with authorization checks.
Agent capabilities are exposed as MCP tools — a typed interface between the agent and the host. Adding a new capability means adding a tool definition and a handler; the agent picks it up automatically on the next container start.
The two-tier scheduling decision
Not every scheduled job needs a full agent. Lightweight reminders write a row to a schedules table and fire a direct Telegram message at the right time — no container, near-zero cost. Complex recurring jobs like the morning briefing spin up a full agent container that queries the database, reasons over the results, and composes a response. The distinction keeps resource usage and latency where they should be.
What I took from it
This is a production system my family uses daily since March 2026. It covers process architecture and IPC design, containerization and security sandboxing, scheduling logic, and prompt engineering for reliable agent behavior across varied, unpredictable real-world inputs.
The constraint that shaped most architectural decisions: the agent should be capable enough to be genuinely useful, but the host should always be in control.