📋 Companion Planning
Plan your days, privately. A local-first todo and planning app — tasks, time blocks, tags, an auto-scheduler, and review-queue automation — all in one SQLite file on your own Hub.
Install & availability
Available now. Install from the Companion Hub App Store. Runs entirely on your Hub; works without any cloud account.
| Hub App Store | Search Companion Planning (app id ci-planning) → Install |
| Container image | ghcr.io/companionintelligence/ci-planning:latest (public) |
| Internal port | 3848 |
| Architecture | linux/amd64 and linux/arm64 (multi-arch) |
| Persistence | SQLite at DB_PATH=/data/companion.db |
Overview
Companion Planning is a private, local-first planning app. It manages your tasks, time blocks, and tags, and includes an auto-scheduler and review-queue automation — all stored in a single SQLite file on your Hub. The frontend is a SolidJS PWA and the backend is a Koa API, served together on one port.
Everything is deterministic without AI. If you connect Ollama, Companion Planning layers on optional intelligence — a generated day briefing, task extraction from email/calendar, and embedding-based dedupe — and degrades gracefully to its deterministic behavior when AI is unavailable.
Current capabilities
What Companion Planning does today, as shipped:
- Tasks, time blocks, and tags in a single SQLite database
- Auto-scheduler that lays tasks into your day
- Review-queue automation — proposals collect in an Inbox until you promote them
- Background jobs for ingestion, grooming, and scheduling (see below)
- REST API + SSE so agents and other tools can read and drive your plan
- Optional Ollama for AI assistance, with deterministic fallbacks throughout
Persistence
State lives in one SQLite file at DB_PATH (default /data/companion.db). The Hub mounts ${APP_DATA_DIR}/data to /data, so back up that directory to back up everything — tasks, blocks, tags, and history.
Configuration
| Variable | Purpose |
|---|---|
PORT | HTTP port (internal 3848) |
DB_PATH | SQLite file path (default /data/companion.db) |
OLLAMA_URL | Ollama endpoint (Hub wires ${APP_OLLAMA_URL}); optional |
OLLAMA_SMALL / OLLAMA_MEDIUM / OLLAMA_EMBED | Models for small/medium generation and embeddings |
TZ | Timezone — set this so “today” and cron jobs match your local time |
GOOGLE_MODE | Controls Google (gmail/gcal) ingestion behavior |
LOG_LEVEL | Log verbosity |
Set TZ. “Today,” day boundaries, and the scheduled jobs all key off the timezone. If TZ is wrong, your day briefing and 2am/3am jobs will run against the wrong calendar day.
Optional AI (Ollama)
Ollama is optional and gracefully degraded. With it connected, Companion Planning can:
- Generate an AI day briefing
- Extract tasks from email and calendar items
- Dedupe similar tasks using embeddings
Without Ollama, all of these fall back to deterministic behavior, and Settings shows the live AI status so you always know which mode you’re in.
Background jobs
Companion Planning runs scheduled jobs you can view and trigger manually from the Jobs view:
| Job | Cadence | What it does |
|---|---|---|
| Gmail / Google Calendar ingestion | every 30 min | Pulls in mail and calendar items |
| Nightly grooming + task promotion | 2:00 AM | Cleans up and promotes tasks |
| Auto-schedule | 3:00 AM | Lays tasks into the day |
Proposals produced by these jobs land in the Inbox and stay there until you promote them into your plan. Job timing follows TZ.
REST API for agents
Companion Planning exposes an HTTP API so agents and scripts can read and act on your plan:
| Endpoint | Purpose |
|---|---|
GET /api/tasks | List/read tasks |
GET /api/blocks | List/read time blocks |
GET /api/summary | Plan summary |
POST /api/schedule/run | Trigger the auto-scheduler |
GET /api/events (SSE) | Live event stream |
Use Cases
- Keep a private, local todo list with time-blocked days and tags
- Let the auto-scheduler lay out your day from your task list
- Turn email and calendar items into draft tasks (with Ollama) for review in the Inbox
- Drive your plan from a Companion Agent via the REST API and SSE stream
Setup
Install from Hub
Search for Companion Planning (ci-planning) in the Hub app store and install. The Hub mounts ${APP_DATA_DIR}/data to /data for persistence.
Set your timezone
Set TZ to your local timezone so “today” and the nightly jobs run on the correct day.
(Optional) Connect Ollama
The Hub wires ${APP_OLLAMA_URL} into OLLAMA_URL. Set OLLAMA_SMALL / OLLAMA_MEDIUM / OLLAMA_EMBED to enable the day briefing, task extraction, and embedding dedupe. Skip this to run fully deterministically.
Review the Inbox
As ingestion and grooming run, proposals collect in the Inbox. Promote the ones you want into your plan.
Troubleshooting
“Today” looks off / jobs run at the wrong time
TZ is likely unset or wrong. Set it to your local timezone and restart.
AI features aren’t doing anything Ollama is optional — check Settings for the live AI status. Without it, the app runs deterministically by design.
My data disappeared after an update
State is the SQLite file at DB_PATH under the mounted /data. Ensure ${APP_DATA_DIR}/data is persisted and backed up.
Proposals never appear in my plan Ingestion/grooming proposals stay in the Inbox until you promote them. Promote items to move them into the plan.