Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@selfos-mcp help me set a goal to run a half marathon by May"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Turn any AI assistant into a goal coach that actually helps you follow through.
self.os is a plain-text vault your AI agents share: your goals, the habits that drive them, your reasons, your plans for when things go wrong, plus the context a good assistant needs (who you are, how you like to work, the people in your life). It ships with a CLI and an MCP server, so Claude, Cursor, OpenClaw and any MCP-capable agent can coach you from the same files, and your data never leaves your machine.
It's built around what research on goal pursuit consistently supports, rather than a to-do list:
Practice | In self.os |
Specific if-then plans ("When X, I'll do Y") | Every goal needs a |
Planning for obstacles up front |
|
Tracking measurable progress |
|
Outcomes driven by habits |
|
Regular review and re-planning | A weekly review that asks the questions worth answering |
Focus | A soft cap on active goals; agents ask what a new goal replaces |
Supportive accountability | After a miss, agents ask what got in the way and adjust the plan, never shame |
Related MCP server: big-brain
Requires Python 3.10+ and uv (or pipx). No other dependencies.
uvx --from git+https://github.com/AmineBenaceur/self.os selfos initThat creates your private vault at ~/.selfos/vault. Then connect your assistant, below,
and say "help me set a goal."
To install the selfos command permanently:
uv tool install git+https://github.com/AmineBenaceur/self.os # or: pipx install git+https://...
selfos --helpClaude Code
claude mcp add selfos -- uvx --from git+https://github.com/AmineBenaceur/self.os selfos-mcpClaude Desktop, Cursor, Windsurf, VS Code and other MCP clients. Add to the client's MCP config
(claude_desktop_config.json, .cursor/mcp.json, …):
{
"mcpServers": {
"selfos": {
"command": "uvx",
"args": ["--from", "git+https://github.com/AmineBenaceur/self.os", "selfos-mcp"]
}
}
}To use a different vault, add "env": {"SELFOS_VAULT": "/path/to/vault"}.
OpenClaw. Install selfos, then the skill in adapters/openclaw/. It drives the
same guarded actions through selfos commands, with heartbeat nudges for habits, check-ins and birthdays.
Anything else. Point the agent at AGENTS.md, or paste
adapters/generic/system-prompt.md plus selfos bundle.
Tool | Purpose |
| Preferences, identity, goals with pace, habits, birthdays. Called first |
| Creates a goal; requires an if-then plan and respects the active-goal cap |
| Logs progress (with a number if there's a metric) and returns pace |
| Pause (with a resume date), finish, re-date, add plans or obstacles |
| Habits with cues and minimum versions; log done or missed with a reason |
| Builds the weekly review and saves it to the vault |
| Remember facts about people, projects, preferences; look things up |
| Housekeeping |
It also provides the prompts set-goal, check-in, weekly-review and coach (the full protocol).
Set. The agent walks you through why, what done looks like, a metric (if any), an if-then plan, likely obstacles, and the habit that drives it.
Do. It nudges at the habit's cue and logs done or missed — <reason>.
Check in. At the goal's cadence it asks for the number and compares it to pace. When you're behind, it asks what got in the way and offers one adjustment.
Review. Weekly, it summarizes goals, habits, what's coming up, and the questions worth answering. You re-plan; it updates the files.
The full agent protocol is in AGENTS.md.
---
type: goal
title: Run a half marathon
description: Finish the Calgary half marathon in under 2:15
status: active
start_date: 2026-09-28
target_date: 2027-05-30
checkin_every_days: 7
metric: weekly distance
unit: km
baseline: 8
target: 40
updated: 2026-10-16
---
## Why
- I want proof I can commit to something hard outside work [stated]
## Plan
- When my alarm goes off Tue/Thu/Sat at 6:00, I put on the clothes I laid out and go. [stated]
## Obstacles
- If it's below -15°C, then I run on the treadmill instead. [stated]
## Log
- 2026-10-12: value=14 skipped Saturday, cold [stated]Plain Markdown: read it, edit it by hand, grep it, version it. See examples/vault/
for a complete vault, and schema/frontmatter.md for every field.
selfos init [--git] # create your vault (optionally as its own private git repo)
selfos goals [--all] # goals with pace, check-in status, linked habits
selfos habits # this week's habit progress, streaks, last miss
selfos review [--write] # weekly review; --write saves to reviews/
selfos birthdays [DAYS] # upcoming birthdays
selfos validate # check every file; warns on missing plans and too many goals
selfos index # regenerate INDEX.md
selfos bundle # whole vault as one file, for models without file access
selfos mcp # run the MCP server on stdio
# for shell-based agents (OpenClaw etc.): same guarded writes as the MCP tools, JSON output
selfos context # everything an agent needs at session start
selfos checkin "Run a half marathon" --value 14 long run felt good
selfos log-habit run-3x-week missed too cold
selfos note people/jane-doe "Loves bouldering"
selfos tool create_goal '{"title": "...", "plan": ["When ..., I will ..."], ...}' # any MCP tool
selfos tool --list
selfos --vault examples/vault review # try it on the demo data (from a clone)From a clone without installing, use python tools/selfos.py <command>.
self.os/ ← this repo (public framework)
├── AGENTS.md ← the contract every agent follows
├── llms.txt ← map of the repo for AI agents
├── selfos/ ← CLI + MCP server (stdlib only)
├── template/ ← starter vault copied by `init`
├── examples/vault/ ← a fictional filled-in vault
├── schema/ ← frontmatter field reference
├── adapters/ ← OpenClaw skill, Claude, generic prompt
└── tests/
~/.selfos/vault/ ← YOUR data (or <clone>/vault, git-ignored, or $SELFOS_VAULT)
├── INDEX.md profile/ goals/ habits/ people/ areas/ journal/ reviews/The vault is plain files on your machine. self.os has no server, account or telemetry.
In a clone, vault/ is git-ignored. selfos init --git makes the vault its own repo;
push it only to a private remote.
The MCP server can only read and write inside the vault.
Agents are told never to store passwords, account numbers or ID numbers, and to record
only what you actually said (tagged [stated]) apart from clearly marked [inferred] notes.
Adapters for more runtimes, better coaching prompts and new check-in types are all welcome. See CONTRIBUTING.md and the good first issues.
Append a fact the user told you to a vault file (one subject per file), e.g. 'people/jane-doe.md', 'profile/preferences.md', 'journal/2026-10-16.md' (auto-created). Pass create to make a new person/area file.
Inputs: path (required), text (required), create, section, +1 more.
Create a goal after coaching the user through it. Requires at least one if-then plan. Refuses if over the active-goal cap unless confirm_over_cap is true.
Inputs: why (required), plan (required), title (required), description (required), +13 more.
Create a repeatable habit, optionally linked to a goal, with a cue and a minimum version for bad days.
Inputs: title (required), frequency (required), cue, goal, +2 more.
Call first. Returns today's date, the user's preferences and identity, active/paused goals with pace and check-in status, habits, upcoming birthdays, and a list of all vault files.
Inputs: no named parameters.
Create the vault from the template if it doesn't exist yet.
Inputs: git.
Goals with progress vs pace, days since check-in, whether a check-in is due, and linked habits.
Inputs: include_inactive.
Active habits with this period's count vs required, streak, recent hit rate and last miss reason.
Inputs: no named parameters.
Log a check-in on a goal (by name or title), optionally with the metric value. Returns updated pace.
Inputs: goal (required), date, note, value.
Log a habit occurrence as done, or missed with the reason the user gave.
Inputs: done (required), habit (required), date, note, +1 more.
Read any vault file by path relative to the vault, e.g. 'people/jane-doe.md'.
Inputs: path (required).
Case-insensitive text search across the vault.
Inputs: query (required).
Birthdays in the next N days.
Inputs: days.
Change a goal: status (pausing needs resume_date), dates, target, cadence; add plans, obstacles or reasons; optionally log a note. Only change status when the user says so.
Inputs: goal (required), note, status, target, +7 more.
Check every vault file's frontmatter; reports errors and coaching warnings.
Inputs: no named parameters.
Build this week's review: goals, habits, what's coming up, and the questions worth asking. Walk the user through it: wins first, then questions one at a time, then next week's focus.
Inputs: write.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 15 tools
Most tools have clearly distinct purposes across goals, habits, files, search, birthdays, and reviews. There is some overlap between get_context and the dedicated list_goals/list_habits/upcoming_birthdays tools, and between weekly_review and those listing tools, but descriptions provide enough guidance to select correctly.
Names are consistently snake_case and mostly follow a verb_noun pattern such as list_goals, create_goal, log_habit, and add_note. A few outliers like search, validate, weekly_review, and upcoming_birthdays break the pattern but remain readable and predictable.
At 15 tools, the surface is well-scoped for a personal operating system covering goals, habits, notes, vault admin, and reviews. Each tool maps to a concrete workflow and none appear redundant enough to remove.
Goal workflows are reasonably covered with create, update, list, check-in, and review support, but habit lifecycle coverage is notably incomplete: there is no update_habit or delete/archive operation for habits. Vault file operations are also limited to reading, searching, and appending notes, with no general file update capability.
Notes and memory assistant: one Markdown vault that Claude, ChatGPT and any MCP client can share.
MCP-native notes and memory for ChatGPT, Claude, and other AI tools.
Your planner in every AI chat: tasks, calendar, docs, habits, goals and memory, over MCP.
Persistent memory for AI assistants. Save once; recall from Claude, ChatGPT, or any MCP client.
