Gubernos
A personal OS for people who already pay for Claude or ChatGPT: your agent gets a model of your life, you get the
screens to steer it. Plain Markdown, open source, no account. → gubernos.app
Gubernos is a personal operating system: one working model of your life, steered day by day. What you are
responsible for, what you have promised, what you want and what you still have to decide, wired to your projects, your
tasks and today. It keeps that model in plain Markdown files you own and gives you, and your AI agents (Claude Code,
Codex), one place to steer it. The name is Latin gubernare, to steer. The method is inspired by David
Allen's Getting Things Done®, Gabriele Oettingen's WOOP and Brian Johnson's Heroic (Masterpiece Days, protocols);
Gubernos is not affiliated with any of them.
Beta. Gubernos is in beta: the iPhone and Apple Watch app is on TestFlight, the Mac app is a download from this
repository's Releases. Things change quickly, and your files stay yours whatever happens (plain Markdown on your own computer).
Install Gubernos
Before you install: you need an AI subscription. Claude with Claude Code (Pro or higher), or any ChatGPT subscription. Gubernos runs on it: the first interview, the chat and the agents all need it. Don't have one? Get it first: Claude plans · ChatGPT plans.
The easiest way: let your AI agent do the setup, on a Mac, Linux or Windows. Open Claude Code or Codex (the table in SETUP.md shows
how to get one) and paste:
Install Gubernos for me: read https://raw.githubusercontent.com/old-bozman/gubernos/main/SETUP.md and do the part "For the agent".
On your Mac (macOS 13 or later), no Terminal needed:
- Download Gubernos.dmg, open it and double-click Gubernos. macOS asks whether to open an app
downloaded from the Internet: Open.
- A page opens in your browser: your name, where your files live, and your AI model (it gets it for you, you sign in).
A few minutes, and Gubernos runs on your Mac.
- Gubernos interviews you, by voice if you like: about 10 minutes, and it ends with your plan for today.
On Windows: in PowerShell, irm https://gubernos.app/install.ps1 | iex (it gets WSL and Ubuntu when they're missing). On Linux: curl -fsSL https://raw.githubusercontent.com/old-bozman/gubernos/main/install.sh | bash -s -- --wizard. Then the same setup page in your browser (more).
By hand in the Terminal: curl -fsSL https://raw.githubusercontent.com/old-bozman/gubernos/main/install.sh | bash
(details: docs/install.md).
On your iPhone:
- Install TestFlight from the App Store.
- On the iPhone, open testflight.apple.com/join/rBUGmgJG → Accept →
Install.
- On the computer, Gubernos → ☰ → Settings → Your Mac → iPhone and other devices → Connect your iPhone,
then point the iPhone's Camera at the code. The phone keeps a copy of your files, so it works when the computer is away too.
On Android: open Gubernos in Chrome and install it as an app (how).
Feedback: in TestFlight take a screenshot → Share Beta Feedback, or open an issue here.
The model. Each ring is a slower horizon, and anything on an inner ring links outward to why it matters: today's #1
→ a project → a goal → an area of your life.
Life loops. A day inside a week inside a quarter. Every loop plans, does and looks back, and each review carries
what you learned back into the model. Everything you capture (voice, the watch, shared links, mail) lands in the Inbox
and feeds them; an agent proposes what each item is, you decide.
Where your data lives. Everything stays with you; there is no Gubernos server to send it to.
flowchart LR
subgraph yours["Yours: your devices, your files, your accounts"]
mac["Your computer<br/>a Mac, or a Linux or Windows PC"] <--> files[("Your files<br/>plain Markdown")]
phone["iPhone and Watch<br/>(a copy for offline)"]
web["Android or a browser<br/>(live from your computer)"]
agents["Your agents<br/>Claude Code · Codex"] <--> files
phone <-. "HTTPS through Cloudflare, paired devices only" .-> mac
web <-. "HTTPS through Cloudflare, paired devices only" .-> mac
end
agents -. "the text a task needs, your account" .-> ai["Your AI provider"]
mac -. "free time, blocks you apply" .-> cal["Your calendar"]
The app and your agent. Your agent can do anything you can describe. Gubernos adds the structure an agent does not
keep on its own: the model, the loops and a screen for each step (the morning plan against your calendar, habits on the
watch, inbox triage, weekly wins and review, handing tasks to agents and accepting their work). Both work on the same
files. The whole explainer is in the app (More → How it works) and at gubernos.app; its source
is public/concept.js (node scripts/build-concept.mjs refreshes the site and these pictures).
This repository
The app over the vault of Markdown files: the files are the only store, no database. Obsidian and agents keep working on
the same files.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
