Duecoach

From what you meant to do to what you did.

Duecoach is an ADHD coach in your chat app, on Telegram (Greek and English), built around follow-through. It coaches with a structured method — goals, small weekly objectives, barrier analysis, a toolbox of what works, a weekly review — with a 106-card playbook of strategies in the prompt of every reply (one model call per message). New users are asked for their timezone first and then talk freely: the coach learns about them, sets goals and weekly steps and follows up on them in conversation, saving them with tools. It also keeps a running to-do list of whatever you say you need to do (no time attached) and brings one item back, with a tiny first step, in its check-ins when you have been quiet. It also notes what you say you did or are doing (kept 30 days; the last 2 weeks are shown with /log and used for suggestions) and suggests one related next step, which goes on the list only if you say yes. When you drift onto a tangent mid-task, it parks the idea on its own (/parked), keeps you on track, and brings it back in a later check-in as a yes/no offer. It is also a planner you run by talking: the coach keeps to-dos with due days, projects (bigger things with several steps) and notes, breaks a vague or big to-do into small literal steps (the first one tiny) and, when a step of a project is finished, adds the next one so every project always has a next step. Appointments with a time go on a calendar. It also files things by itself: after each message a small background call (on LLM_SIDE_MODEL) reads the latest exchange and adds the to-dos, projects and appointments you mentioned that the coach didn't save, through the same checked tools, and the coach tells you once what it filed. The first time it runs for a user it reads everything the bot still holds from them (messages, notes), so an existing user's planner fills in from their history after their next message. Everything is saved with tools, so there are no commands for changing anything; the plain views are /today (appointments, reminders, overdue and due to-dos), /calendar (the next 7 days), /tasks (to-dos by project, steps under their task), /projects (each project and its next step) and /notes (what you asked it to write down; what the coach has learned about you is /memory). Check-ins are handed the same facts, worked out by code: the morning one starts from today's appointments and due items, the evening one looks at what got done and what is on tomorrow, the mid-day one only mentions what is close, and morning and evening also point at projects with no next step (the coach offers one; check-ins cannot save, so it is saved once you say yes). Once the timezone is known, the bot checks in after 30 minutes of silence during the day and backs off when ignored (/interval off turns it off).

It is a coaching aid, not therapy or medical advice. Chats are stored in a local SQLite database and each message is sent to the language-model provider you configure, so users must agree to a privacy notice (/agree) before anything is processed. Messages older than RETENTION_DAYS (90) are deleted, people who have not written for INACTIVE_DELETE_DAYS (365) are deleted entirely, /deletedata erases everything at once, and writing about suicide or self-harm gets a fixed safety message with emergency numbers instead of a model reply (CRISIS_HELP can add a local helpline). A word list (English, Greek) catches plain wording without a model; for every other message, once the user has agreed, a short model call (about 1-2 s) judges whether it shows a crisis in any language or wording, and python -m evals.crisis scores it on labelled messages. Daily backups keep copies of the database for 7 days, so a deletion leaves the backups within a week.

Run it with Docker

cp .env.example .env        # fill in TELEGRAM_BOT_TOKEN, LLM_API_KEY and ALLOWED_USERS at least
docker compose up -d --build
docker compose logs -f

• The database lives in the data volume (named <project>_data, i.e. duecoach_data on the server) (/data/coach.db). Back that volume up.
• GET /healthz on port 8080 reports 503 when the reminder or check-in loop stops (the container's healthcheck uses it) and shows the model in use; a model outage alone does not fail it.
• Only one instance can use a database (a lock file enforces it). Don't run the bot twice with the same Telegram token.
• The container runs as an unprivileged user with a read-only root filesystem; docker-compose.yml has the details.

Moving an existing local database into Docker

docker compose stop
docker compose run --rm --no-deps -v "$PWD:/import:ro" --entrypoint sh duecoach -c 'cp /import/coach.db /data/coach.db'
docker compose up -d

(Stop any locally running python -m duecoach.bot first. The database is upgraded automatically on start.)

CI/CD: GitHub Actions + Ansible to the VPS

.github/workflows/ci-cd.yml runs on every push and pull request to main:

1. test: ruff check, ruff format --check, mypy, pip-audit (known vulnerabilities in the pinned dependencies), pytest.
2. build-and-push: builds the Docker image (always, so a broken Dockerfile fails CI) and, on main only, pushes it to ghcr.io/coreinch/duecoach tagged main-<short sha>.
3. deploy (main only): installs Ansible, generates the inventory from the DEPLOY_HOST secret, and runs ansible/playbooks/deploy.yml, which renders the compose file and .env on the VPS, logs in to GHCR, pulls the new image, restarts the stack, waits for the container to report healthy (a crashing bot fails the deploy), schedules a daily database backup, and removes this app's old image tags (keeping 3 for rollback).

Runs on the same branch are queued, never cancelled, so the newest commit is always the one deployed last.

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗