Self-hosted, four purpose-built AI helpers for organisation, creativity, and reflection.

One generic AI can't hold all the roles you need it to. Reflection needs patience. Creation needs guardrails and momentum. Knowledge needs structure. It's not that most tools can't do it, but this one is the one that helps my brain.

Your data shouldn't live on someone else's server. Companions runs on your machine. Your vault is plain markdown files. No cloud account, no subscription, no lock-in. All local.

Context gets lost when your tools don't talk to each other. All four agents share one vault. A calendar event from Tracker shows up if Mentor needs context. A draft from Shapeshifter becomes a wiki entry Keeper can find later.

Each ships with a default name, emoji, and character. Rename them and tune the personality during setup or any time from the dashboard.

	Weekly phrase — a short line to sit with and return to through the week Calendar — pulls in Google Calendar events so the day has context and shape
	To-dos — p1 / p2 / p3 priorities; incomplete tasks carry forward automatically Rhythms — recurring commitments across any cadence: daily, every N days, every N weeks, weekly, monthly, annual
	Haiku — three lines written fresh every evening as a reflective practice for the day

Two agents, one shared space. They're opposites by design — Mentor slows you down, Shapeshifter speeds you up. Which one you reach for depends on whether you need to understand something or build something.

The Chat tab lets you talk to either. Switch between them at any point. Mentor One step at a time, one next action per response,Canvas only when you ask. Shapeshifter infers your intent and acts. States one assumption in a line, then builds.

Shapeshifter's default output is not a chat reply. It's a persistent, structured workspace saved to your vault — a live app rendered inside the tab.

Canvases are built from 10 composable blocks:

The html block is where it becomes a playground. Write a self-contained React component, a chart, a custom layout — anything. Shapeshifter generates it, the app renders it live.

	Surfaces forgotten knowledge — prioritising older, reinforced memories you've likely lost track of.
	Drop in raw notes, voice dumps, or rough ideas. Keeper extracts the signal, organises it into the wiki, and keeps the index clean.
	The wiki follows a Johnny Decimal structure so nothing gets lost in an undifferentiated pile: 01-identity · 02-knowledge · 03-projects · 04-areas · 05-relationships · 06-creativity · 07-systems · 08-resources · 09-media · 10-events · 11-questions · 99-archive

vault/
  raw/        quick captures — notes, clips, voice transcripts
  wiki/       linked knowledge — Keeper-maintained articles
  journal/    dated entries — Tracker reflections and logs
  projects/   long-form work — plans, drafts, active projects

Plain markdown. No database. Open any file in any editor.

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

Requires Node ≥ 20, git, and npm. Clones the repo, installs dependencies, and builds the server, dashboard, and Expo web app. Then start the server and open the setup wizard in your browser. The wizard covers vault path, your name, server secret, LLM provider, persona names, and optional Google Calendar.

Manual:

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 first-run wizard at /install gets the server into a usable state without hand-editing config files.

• Vault path — points Companions at an existing vault or creates a fresh one with the required folders
• Identity + auth — stores your name and server secret
• Model setup — sets the default local or cloud model and any provider credentials you need
• Personas — rename the four companions and pick their emoji before first use
• Google Calendar — optional OAuth setup for Tracker
• Pairing — once the server is configured, the dashboard exposes the pairing URL, QR code, and deep link for the mobile app

What it produces:

• a ready server .env
• a usable vault structure
• persona files updated with your chosen names and emoji
• the hosted routes for /install, /dashboard, and /app

	The dashboard at /dashboard is the control surface after setup. It is separate from the chat UI and is meant for server administration, model changes, and maintenance. Personas — rename each persona, swap emoji, and edit the underlying prompt text
	Models — connect providers, store API keys, choose a default model, and override models per persona
	Vault — inspect vault stats, change the vault path, and run backups Logs — watch the live server log stream in the browser Setup — copy connection details, generate QR/deep links for pairing, inspect version info, and run in-place updates

Change the model any time from the dashboard — no restart needed.

Companions runs well (for the cost of speed) on Apple Silicon with omlx — an OpenAI-compatible inference server built for Apple's unified memory architecture.

Chat model: Qwen3.6 35B A3B 4bit — a mixture-of-experts model with 35B total parameters and ~3.6B active per token. The 4-bit quantisation fits comfortably in 32 GB of unified memory (M1 Max) with room to spare, while the MoE architecture keeps reasoning quality high despite the reduced footprint.

Vision model: Gemma 4 E2B 4bit (Heretic-Uncensored) — Google's 2B effective-parameter edge model with a built-in 150M Vision Transformer encoder. Handles images, screenshots, and documents natively. The MLX 4-bit quantisation brings it to ~2–3 GB on-device with near-zero quality loss, running on the Neural Engine alongside the chat model.

DEFAULT_MODEL=openai-compat:http://localhost:8000/v1:Qwen3.6-35B-A3B-4bit
DEFAULT_MODEL_KEY=your-omlx-api-key
VISION_MODEL=openai-compat:http://localhost:8000/v1:gemma-4-E2B-Heretic-Uncensored-mlx-4bit
VISION_MODEL_KEY=your-omlx-api-key

• Android: Download APK — sideload and scan the QR code from the setup wizard
• Web: http://<your-server>/app — full Expo web build, identical to Android. Works on desktop and iOS Safari over Tailscale.
• Dashboard: http://<your-server>/dashboard — manage vault, models, personas, and updates

Recommended remote access: Tailscale — the wizard detects it automatically.

• Pi coding agent — the core agent engine
• Andrej Karpathy — inspiration for the Keeper wiki model
• Expo / EAS — Android build infrastructure

MIT — see LICENSE.