Skip to Content
DocumentationCompanion Planning

📋 Companion Planning

Plan your days, privately. Companion Planning keeps your tasks, schedule, and planning history in a SQLite database on your Hub. Google Calendar, AI, Companion Memory, and crash reporting are optional connections.

Install & availability

Available now. Install from the Companion Hub App Store. Version 4.2.2. The app runs on your Hub and works without optional integrations.

Hub App StoreSearch Companion Planning (app id ci-planning) → Install
Port18829 in the store listing. The container listens on 3848.
Architecturelinux/amd64 and linux/arm64 (multi-arch)
RequiresCompanion Hub v0.2.27 or later
PersistenceSQLite at DB_PATH=/data/companion.db
Install optionsAdmin username, admin password (required), Ollama URL, timezone, token encryption key, and Share crash reports

Overview

Companion Planning is a local-first planner. Today and Calendar show scheduled work, open time, and availability windows. Tasks include priorities, tags, recurrences, and links to objectives; separate sections support routines, habits, and someday tasks. Weekly Review and Life Balance help users reflect and set priorities. The Settings → People tab manages people assigned to tasks and time blocks.

The SolidJS PWA and Koa API run together on the Hub. Planning works without AI. When a model endpoint is configured, AI can help with briefings, task extraction, and grooming; the deterministic planner remains available without it.

Current capabilities

What Companion Planning does today, as shipped:

  • Tasks, time blocks, tags, routines, habits, objectives, and someday tasks in SQLite
  • Day types and availability windows for Workday, Weekend, and custom schedules; open time shows where nothing is planned
  • Auto-scheduling guided by availability, task priority, and a trust setting: Cautious schedules nothing automatically, Balanced waits for the user to ask, and Hands-off schedules new work as it arrives
  • Weekly Review and Life Balance for reviewing work and setting weekly priorities
  • People directory for assigning responsible people and beneficiaries to tasks and blocks
  • New Today — every task created today, whether you added it or an automation suggested it, appears in a New Today section at the top of Tasks until the day rolls over
  • Optional Google Calendar sync, Companion Memory, and Web Push (see Google Calendar)
  • Background jobs for ingestion, grooming, reminders, and scheduling (see below)
  • REST API + SSE so agents and other tools can read and drive your plan
  • Optional AI assistance through a configured Ollama or Hub model endpoint

First run

Fill in the install form

When you install from the Hub App Store, the form asks for:

  • Admin username (default admin) and Admin password. The password is required: the app refuses to start without a way to log in. Hub cannot show you a generated value later, so choose a strong password and store it. The pair creates one owner account on first boot only; changing them later does not rename or re-password that account.
  • Timezone, an IANA name such as America/Los_Angeles (default UTC). It sets the container clock, which decides what “today” means and when the nightly jobs run.
  • Ollama URL, filled in from Hub → Settings → AI. Leave it blank to use the Hub default.
  • Token encryption key, generated for you. It encrypts stored Google tokens. Back it up with your app data.
  • Share crash reports, on by default.

Sign in

Open the app from its card on the Hub dashboard and sign in with the admin username and password you chose.

The Companion Planning sign-in screen: the heading Sign in, the text Enter your username and password, a Username field, a Password field, a Sign in button, and a Forgot password linkThe Companion Planning sign-in screen: the heading Sign in, the text Enter your username and password, a Username field, a Password field, a Sign in button, and a Forgot password link
The sign-in screen on a Hub install.

Complete first-time setup

New accounts see a ten-step setup. Saved steps update the account’s preferences and schedule.

  1. Welcome — add your name and email.
  2. Time and place — set usual wake and bed times; the browser supplies the timezone.
  3. Pattern Tags — edit the Home, Work, and Community names, icons, and colors.
  4. Set up your first Workday — choose availability windows for each direction. Add another day type here if needed.
  5. Set up Weekend — configure different hours for days off, or skip this step.
  6. Choose your default days — assign a day type to each weekday.
  7. Connect a source — admins can load sample data or connect a configured integration. Google requires an admin to add an OAuth client under Settings → Connections first.
  8. Trust dial — choose how much the planner may schedule automatically. Change it later from the top bar.
  9. Run your first sync — fetch connected sources now; this has no effect when none is connected.
  10. Life Balance — finish setup or start the priorities wizard to set weekly life-area targets.
Step 7 of 10, Connect a source: the setup offers Connect Google, Try with sample data, and status for Companion Memory and AI.Step 7 of 10, Connect a source: the setup offers Connect Google, Try with sample data, and status for Companion Memory and AI.
Step 7 of the current ten-step setup, captured with synthetic data.

The initial admin username and password are set at install. Local sign-up is open by default and can be set to invite-only or disabled with AUTH_SIGNUP; operators can also manage accounts under Settings → Accounts. Setup can be reopened from Settings.

After Try with sample data, Today shows the day planner and Tasks lists the sample tasks, with items created that day under New Today.

The Today view with the sample data loaded: the date and the open time windows at the top, a planner below with blocks for Breakfast, Gym, and Deep work and several scheduled tasks, and a Flight Plan panel on the rightThe Today view with the sample data loaded: the date and the open time windows at the top, a planner below with blocks for Breakfast, Gym, and Deep work and several scheduled tasks, and a Flight Plan panel on the right
Today, with the sample data loaded. The tasks, times, and date are example data.
The Tasks view with the sample data loaded: a New Today section listing three tasks, Review notes, Get groceries, and Drop off donations, each with a duration, a tag, and priority buttons, and a Scheduled section belowThe Tasks view with the sample data loaded: a New Today section listing three tasks, Review notes, Get groceries, and Drop off donations, each with a duration, a tag, and priority buttons, and a Scheduled section below
Tasks, with the sample tasks created today under New Today (example data).

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. A daily job at 2:00 AM also writes a point-in-time snapshot to a backups folder beside the database and keeps the newest seven.

Configuration

On a Hub install you set these options in the install form. The variables below are what the container reads.

VariablePurpose
PORTHTTP port (internal 3848)
DB_PATHSQLite file path (default /data/companion.db)
OLLAMA_URLOllama endpoint (Hub wires ${APP_OLLAMA_URL}); optional
OLLAMA_FAST / OLLAMA_QUALITY / OLLAMA_EMBEDModels for fast extraction, quality briefings, and embeddings. The older names OLLAMA_SMALL and OLLAMA_MEDIUM still work.
TZTimezone — set it so “today” and the nightly jobs match your local time. The install form sets it from Timezone.
GOOGLE_MODEPins Google integration to live or fixture. Leave it unset to configure Google in the app.
LOG_LEVELLog verbosity

Set your timezone at install. “Today,” day boundaries, and the scheduled jobs all key off the container’s timezone, which defaults to UTC. If it is wrong, your day briefing and 2 AM and 3 AM jobs run against the wrong calendar day. If the stored timezone is still the UTC default, the web app adopts your browser’s timezone the first time you open it.

Google Calendar

Google integration is off until you set it up. An admin pastes a Google OAuth client into Settings → Connections → Integrations, and each user then connects their own Google account. Inbound sync is read-only until write-back is enabled. Gmail access is a separate opt-in. Until you connect Google, no email or calendar data is ingested and none of the Google jobs below do anything.

Settings on the Connections tab: cards for Models, showing Ollama as unavailable, Companion Memory, showing Not connected with a Connect button and a Sync with Companion Memory switch, Email suggestions, and Integrations, which starts with Google MCP and a Google OAuth client fieldSettings on the Connections tab: cards for Models, showing Ollama as unavailable, Companion Memory, showing Not connected with a Connect button and a Sync with Companion Memory switch, Email suggestions, and Integrations, which starts with Google MCP and a Google OAuth client field
Settings → Connections on an install with no Ollama, Companion Memory, or Google connected. The Integrations card holds the Google OAuth client.

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 that you can view and run manually from the Jobs view. The main ones:

JobCadenceWhat it does
Remindersevery minuteFires each due reminder once
Gmail ingestionevery 15 minFinds action items in email (needs Google connected with Gmail access enabled)
Calendar syncevery 15 minTwo-way calendar reconcile (needs Google connected)
Calendar task extractionevery 30 minExtracts tasks from calendar text (needs Google connected)
Nightly grooming2:00 AMEmbedding-based dedupe, overdue bump, and straggler promotion
Database snapshot2:00 AMWrites a backup and keeps the newest seven
Auto-schedule3:00 AMProposes candidates for your flight plan and sweeps missed blocks. It does not pack your whole backlog.

Other jobs handle routine rollover, tagging, recurring tasks, and weekly learning passes. Job timing follows TZ. Suggestions that ingestion finds are promoted into New Today automatically; the old Inbox view is retired and /inbox redirects to Tasks.

REST API for agents

Companion Planning exposes an HTTP API so scripts and agents can read and act on your plan:

EndpointPurpose
GET /api/tasksList and filter tasks
GET /api/blocksList time blocks for a date range
GET /api/summary?date=YYYY-MM-DDDay briefing
POST /api/schedule/runRun the auto-scheduler for a date
GET /api/events (SSE)Live event stream

On a Hub install, the app uses local username and password sign-in, and the API accepts your login session cookie. API-key access (x-api-key) belongs to the app’s standalone auth mode, which the Hub install does not use, so an agent needs a signed-in session.

Technical architecture

Companion Planning is open source under the PolyForm Noncommercial 1.0.0 license . It is engineered as a local-first, AI-augmented personal planning platform that runs as a private server on your Hub appliance or local machine.

Data layer: owner-scoped SQLite and WAL invariants

  1. Strict foreign-key enforcement: Every connection is initialized through a shared openDb() helper that unconditionally activates PRAGMA foreign_keys = ON; and covers foreign-key paths with indexes to eliminate lock contention.
  2. Deterministic schema migrations: Managed by an internal migration runner (server/src/db/migrations/index.ts) with forward verification.
  3. Multi-tenant owner scoping: Every table, REST endpoint, and GraphQL resolver strictly filters by owner_id. Rows without owners are retired, ensuring full isolation when running under organization accounts.
  4. WAL reliability and replication: Operates in SQLite Write-Ahead Log (WAL) mode. Supports zero-downtime replication via Litestream (litestream replicate) to S3-compatible storage without stopping the database.

The auto-scheduler and time-sense loop

  • Natural scheduling semantics: Companion Planning separates start intentions from deadlines: scheduled_for and task_time dictate when focus begins; due_at defines the hard deadline.
  • Reactive reflow: The scheduler evaluates task estimates, priority weights, and calendar container outlines, packing unscheduled tasks into available daytime slots.
  • Time-sense calibration: Tracks actual completion duration against initial task estimates. The calibration loop adjusts future auto-planning estimates dynamically based on your historical velocity.

External boundaries and connectors

  • Ollama AI integration: Analyzes inbox dumps, calendar entries, and task titles locally. Generates a daily morning brief, structures action items, and deduplicates tasks. When Ollama is offline, the system degrades to deterministic sorting.
  • Companion Memory connector: When connected to Companion Memory, the memory_suggest agent stages upcoming life events as suggestions in New Today and provides memory-informed briefings.
  • Encrypted Google Calendar sync: Connects to Google Calendar using OAuth 2.1 with PKCE. Tokens are encrypted at rest using AES-256 with a 32-byte key (CP_KEK_B64). With CP_SYNC_WRITEBACK=true, local blocks sync bidirectionally to external calendars.
  • Model Context Protocol (MCP): Exposes planning intents (create_task, reschedule, get_daily_brief, mark_done) so local autonomous agents can plan your day on your behalf.

Use cases

  • Keep a private, local todo list with time-blocked days and tags
  • Let the auto-scheduler propose a day from your task list
  • Turn email and calendar items into draft tasks (with Google connected and Ollama running)
  • Read and drive your plan from a script or agent through the REST API and SSE stream

Privacy

Your tasks, calendar, and reflections are stored on your Hub. The app sends nothing to Companion Intelligence except optional crash reports: errors only, scrubbed of credentials and home paths, with no tracing or session replay and none of your tasks, calendar items, or reflections. Crash reports are on by default. Turn them off with the Share crash reports switch when you install, or with CI_TELEMETRY=off. If you connect Google, the app also talks to Google to sync your calendar. Whenever you open the app, your browser also loads the Manrope typeface from Google Fonts (fonts.googleapis.com and fonts.gstatic.com).

Troubleshooting

The app won’t start after install The install form requires an Admin password. Reinstall with one set.

“Today” looks off / jobs run at the wrong time The timezone is likely UTC. Set the Timezone option to your local IANA timezone and restart.

AI features aren’t doing anything Ollama is optional — check Settings for the live AI status and use Re-check. Without it, the app runs deterministically by design.

Nothing is coming in from email or calendar Google is off until you connect it. Set it up under Settings → Connections.

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.

I forgot the admin password The in-app password reset emails a link, which needs SMTP configured on the container. Without SMTP, the link is written to the container log instead.

Last updated on