← Back to archive

Repo of the Day

sanieldoe/companions: Self hosted, four purposed built ai helpers for organisation, creativity and reflection.

Published: Jun 23, 2026

Open repository ↗

Self hosted, four purposed built ai helpers for organisation, creativity and reflection. - sanieldoe/companions

Summary

Companions is a self-hosted, four-persona AI workspace written in TypeScript that runs on a local Node server. The personas (Tracker, Mentor, Shapeshifter, Keeper) share a plain-markdown vault and connect to Anthropic, OpenAI, Ollama, or a local oMLX inference server. The project ships with an Express server, a Vite 6/React 19 web app, an Expo 55 Android client, and a first-run setup wizard.

What it is useful for

Engineers who want a personal, local-first assistant without a cloud account will recognise a few concrete workflows:

  • Daily task and reflection tracking. Tracker's p1/p2/p3 todos carry forward, and "rhythms" support daily, every-N-days, weekly, monthly, and annual cadences. A Google Calendar OAuth integration is available for surfacing the day.
  • Slow vs. fast coding help. Mentor returns one next action at a time; Shapeshifter infers intent and emits a Canvas, a workspace built from 10 composable blocks (markdown, tasks, note, code, links, filetabs, button, input, section, html). The html block renders a sandboxed WebView, so a Shapeshifter output can be a live React component or chart.
  • A maintainable personal wiki. Keeper organises captures into a Johnny-Decimal folder tree (01-identity through 11-questions, 99-archive) and uses LanceDB with HuggingFace Transformers to surface older items.
  • A single shared vault. raw/, wiki/, journal/, and projects/ are plain markdown, so any editor works and content is portable.

The mobile story is Android-only by APK sideload; iOS users reach the same Expo web build through Tailscale. Fully local Apple Silicon setups are supported via oMLX, with the README explicitly noting a speed trade-off when running a 35B-A3B MoE model in 4-bit.

How engineers can use it

The README documents a one-line installer plus a manual path.

Quick start:

curl -fsSL https://raw.githubusercontent.com/sanieldoe/companions/main/install.sh | bash

Manual path (requires Node ≥ 20, git, npm):

git clone https://github.com/sanieldoe/companions.git
cd companions/server && npm install
cd ../web && npm install
cd ../app && npm install
cd ../server && npm run setup && npm start

Then open http://localhost:3000/install. The wizard configures vault path, identity, server secret, LLM provider, persona names, and optional Google Calendar. After setup, /dashboard exposes model switching (per-persona overrides supported), live server logs, vault backups, and a QR/deep link for pairing the Android APK.

The agent engine is the @mariozechner/pi-coding-agent package, so engineers extending the system work inside a documented TypeScript runtime rather than a black box. Models can be changed from the dashboard without restarting, and the persona prompt text is editable per-agent.