A local-first, open-source personal operating system. Your data lives as plain files on your own disk (the "vault"); AI agents you run through Claude Code help you set goals, capture what you learn, and keep a profile of who you are so every session has context. A local Next.js dashboard is the visual window — and the place you handle quick human actions (ticking tasks, writing diary entries, adding quotes, editing your profile).
Core principles:
- Local-first. Source of truth is plain files on disk in a
vault/. No database brain. - Private by default. Your
diary/is categorically off-limits to every AI agent and skill, andtype: privatenotes are human-only. - Trivial setup. One command scaffolds a blank vault — no database, no API keys.
- Modular. You pick the modules you want at install time, and change your mind later.
- Open. MIT-licensed; anyone can clone and use it.
npx create-achieve my-osThe installer clones this repo, asks which modules the vault should run, records the answer in
vault/config.yaml, scaffolds a blank vault for those modules only, and prints how to start:
cd my-os
npm run dev # dashboard at http://localhost:3000The picker is generated from the module registry of the version it just cloned, so it always offers
exactly what that version ships — descriptions, defaults and dependencies included. A module another
one depends on comes along automatically with a notice (Jobs pulls in Profile, because the CV skill
may use no facts but the ones in profile/); decline it in the picker and the module that needed it
is skipped instead, with the reason.
Scripted installs skip the questions:
npx create-achieve my-os --modules notes,goals,diary # exactly these, plus dependencies
npx create-achieve my-os --all # everything
npx create-achieve my-os --yes # the recommended set, unattendedYou get a normal checkout, not generated code: upgrade with git pull, and change modules
afterwards by editing vault/config.yaml. Needs Node 22.18+ (or 24+) and git; nothing native and no
headless browser is pulled, by the installer or by the project.
Already have a clone? npm install && npm run setup && npm run dev does the same thing, and
ACHIEVE_MODULES=notes,goals npm run setup is the flagged install by another name.
That's it — no database to provision, no credentials to paste. Your real content lives in vault/,
which is gitignored and never published. The skills below run inside Claude Code from within the
vault.
A read-mostly window over your vault, with the simple human write actions built in:
- Dashboard — to-do list (add / complete / delete, optionally linked to a weekly goal), quote of the day, and your goal tree.
- Goals — your direction → yearly → monthly → weekly tree, read-only apart from one checkbox per leaf step. Progress is derived from what you tick and rolls up the tree; a step whose prerequisites are unfinished shows as blocked and cannot be ticked.
- Diary — write dated entries. This is yours alone (see Privacy below).
- Notes / Projects — surfaced from the vault's
notes/andprojects/directories. - Profile — your skills, experience and recent evidence, plus the
user.mdsummary Claude loads at the start of every session. - Jobs — the application pipeline (
saved → applied → interview → offer | rejected, with the date of each stage), the gap analysis behind each saved job, and a print view of the CV you tailored for it. - Learn — one folder per topic: why you are learning it, an ordered curriculum whose items tick
like goal steps (progress derived from what you tick, never typed), and every study session
/teachhas written on it. - Fitness — the training plan
/fitnesscut for you, your logged sessions and measurements, weekly adherence (a double week never buys back a missed one) and a progress chart.
Every write goes through a server action into the vault I/O layer — the browser never touches disk, and each change is one atomic write plus one labeled git commit.
/goals— finds candidate goals in gaps your own data already shows (each cited to the file it came from), pushes back on the infeasible, and decomposes the one you pick into orderedlearn/dosteps under a direction → yearly → monthly → weekly tree, then writesgoals.yaml. Twelve months is a hard ceiling for anything trackable; anything longer is a direction — a north star with no status, progress or deadline. Progress is never typed: it is the share of leaf steps ticked, rolled up the tree./profile— maintains the structured profile database (profile/: experience, skills, education, preferences), proposes skill promotions from the evidence log, and regenerates the shortuser.mdsummary (approve-gated)./note— turns raw input into a summarized, categorized note undernotes/, written through the vault I/O path as one labeled commit./teach— runs an active-recall learning session on a topic underlearn/<topic>/: it works out why the topic exists (the goal step or missing job requirement that demanded it), proposes an ordered curriculum whose items tick exactly like goal steps, and writes each session's summary intolearn/<topic>/sessions/— everything about a topic in one folder, not scattered notes./fitness— interviews you first (training history, injuries, equipment, days a week, level, when you train), stores the answers infitness/intake.yamlso it never asks twice, and only then proposes an approve-gated training plan built around them — never more days a week than you said you have. It builds general training programs only: injuries, pain, medications and health conditions go to a doctor or physiotherapist, and nutrition is deliberately out of scope./cv— saves a job description underjobs/<company>-<role>/, writes a gap analysis citing your own profile evidence for what you already have (and naming what you don't), and fills your CV template (jobs/cv-template.md) for that role. It may use only facts already inprofile/: it re-orders, re-weights and re-words real experience, and never invents — a CV is a document you sign. The missing requirements are what/goalsreads to propose goals worth having.
Skills are approve-gated, never write outside the files they own, and never read your diary or
type: private notes. They ship in template/.claude/skills/ and are copied into each vault by
npm run setup.
npm run rotate— advance the quote-of-the-day pointer (run on a daily schedule or by hand).npm run quotes:import <file>— load a quote database you curate into the pool. CSV, JSON or YAML, withtextandauthorfields plus optionalsourceandtags; CSV headers may be in any order (and aquotecolumn counts astext). Nothing is fetched and nothing is generated — a machine-written line attributed to a real person is a fake quote. Safe to re-run: entries already in the pool are skipped, quotes you added in the dashboard are never touched, and a file with a bad row is rejected whole, leaving the pool as it was.npm run migrate-profile— parse an older hand-writtenuser.mdinto theprofile/stores.npm run cv:pdf jobs/<company>-<role>— print an approvedcv.mdtocv.pdfusing a browser you already have (Chrome, Edge, Brave or Chromium — no 300 MB dependency). With none installed it says so and points you at the dashboard's print view, which produces the same document. The PDF is gitignored;cv.mdis the version that stays in your history.npm run migrate-goals— move a vault off the old3yrhorizon and typedprogresspercentages (preview by default;-- --writeafter you approve). Prints a preview and writes nothing until you pass--write; never overwrites existing content.
npm run setup scaffolds this blank structure (the committed template/ is the source):
vault/
CLAUDE.md # auto-loaded by Claude Code; imports user.md
config.yaml # which modules this vault runs (delete it to enable all)
user.md # the short profile summary Claude auto-loads (/profile + dashboard)
profile/ # the profile context database, read on demand
experience/ # one markdown file per role (/profile-owned)
skills.yaml # skill levels (/profile-owned)
education.yaml # schooling (/profile-owned)
preferences.yaml # how you work best (/profile-owned)
evidence.yaml # append-only log of skill-tagged work (dashboard-owned)
tasks.yaml # to-do items (dashboard-owned)
goals.yaml # goal tree definitions (/goals-owned)
goal-status.yaml # which leaf steps are ticked (dashboard-owned)
quotes.yaml # quotes + rotation pointer
notes/ # markdown notes
projects/ # project notes
jobs/ # one folder per application: jd.md, fit.md, cv.md (/cv-owned)
applications.yaml # the pipeline and its dates (dashboard-owned)
cv-template.md # your CV's sections and style — you own this file
diary/ # dated entries — human-only, never read by AI
Each file has exactly one primary writer, so no two writers ever contend on the same file.
Which parts land there is a choice: every feature is a module declared once in
lib/modules/registry.ts (label, description, sidebar entry, vault paths, skills, seed files, guide
steps, dependencies, and whether the installer pre-ticks it), and vault/config.yaml lists the ones
this vault runs. npx create-achieve asks; ACHIEVE_MODULES=notes,goals npm run setup is the same
choice made on the command line. Modules a module depends on come along automatically. No
config.yaml means everything is enabled, so a vault scaffolded before modules existed keeps
working.
Changing your mind later is editing one file: add or remove ids in vault/config.yaml and the
dashboard follows. What that cannot conjure is a module's seed files and its skill, which were never
copied in — npm run setup only ever runs against an empty vault, so it never overwrites your
data. Copy the ones you want out of the committed template/ and you're done.
Every note in notes/ declares a type in its frontmatter, drawn from a small,
validated enum — the /note write path rejects anything outside it, so the
vocabulary stays consistent instead of drifting. Membership reflects observed
usage rather than being invented up front:
type |
For |
|---|---|
working |
active work — ideas, meeting notes, todos-in-prose |
learning |
things being learned or studied (structured study lives in learn/ instead) |
validation |
evidence and findings while checking something out |
private |
human-only — agents never read the body |
private is load-bearing: it is the note-level half of the privacy boundary
below, and every AI-facing surface filters it out. The set can grow as real
usage warrants, but each addition is a deliberate, documented change here and in
NOTE_TYPES (lib/dashboard/note-content.ts).
diary/is categorically off-limits to every AI agent and skill. It is never read, summarized, or quoted, and its content never entersCLAUDE.mdoruser.md. The dashboard is the only thing that touches it — because it's your own writing tool.fitness/photos/is off-limits on the same terms. Body photos are the most sensitive thing in the vault and git history is effectively permanent, so they are gitignored and carry a permission deny rule. No agent goes looking; you attach a photo in the conversation on the rare occasion you want feedback on one.type: privatenotes are human-only — agents never read their bodies.
These contracts are enforced in code (sanctioned-writer modules), in the vault's shipped permission deny rules, and guarded by tests.
The dashboard is the primary, source-of-truth interface — Obsidian is purely an optional way to
browse the same vault/ folder with a nicer reading experience (backlinks, graph view, a
properties panel for frontmatter). It never changes what's true on disk; both just read/write the
same files.
Setup: open Obsidian → "Open folder as vault" → select your vault/ directory. npm run setup
already ships sensible defaults under vault/.obsidian/ (see below), so panes and plugins are
pre-configured on first open — no manual setup required.
What's pre-configured:
- Core plugins: Backlinks, Outgoing links, Graph view, Tag pane, Templates, Note composer, Outline, Quick switcher.
- Frontmatter (
type,tags,project,created,status) renders natively as a Properties panel in modern Obsidian — no plugin required. - Links use plain relative markdown links (
useMarkdownLinks: true), matching how the dashboard and every skill already read note/project bodies as plain text — nothing Obsidian-specific leaks into file content.
Recommended community plugin: Dataview —
lets you query frontmatter directly (e.g. list every type: learning note, or every project whose
status isn't private) without hand-maintaining an index. Not bundled (community plugins are
binaries we don't vendor); install it from Obsidian's Community Plugins browser if you want it.
Note: project:/type: frontmatter fields are plain strings, not [[wikilinks]] — Obsidian's
backlinks graph won't auto-connect a note to its project unless you rewrite the value as a wikilink
(e.g. project: "[[streaming]]"). Doing so is purely a human-side markup choice; every skill and the
dashboard already read the field as a string either way.
vault/.obsidian/workspace.json and any installed plugin binaries are gitignored (noisy,
machine-specific state) — only the meaningful settings (app.json, core-plugins.json,
community-plugins.json) are tracked in your vault's own git history.
- Source of truth = files on disk in
vault/(its own git repo, gitignored from this one). - A vault I/O layer mediates every read/write: atomic writes (temp → fsync → rename) plus one labeled git commit per mutation.
- The dashboard is Next.js (App Router) + shadcn/ui. Reads are
server-only; writes go through server actions that call the vault layer server-side.
See CLAUDE.md for the full developer context (architecture, write ownership, and the privacy boundary).
- Product spec / PRD (v1) — problem, solution, user stories, v1 scope.
- v2 roadmap · v3 roadmap — what's next.
- Implementation issues — the v1 vertical slices.
- Design handoff — locked design decisions; do not reopen.
v2 complete. All nine phases of the v2 plan are shipped: the module
registry, the Reviews/Search removals, the profile context database, the goals redesign, the Jobs,
Learn and Fitness modules, the quotes importer, and npx create-achieve — the installer that makes
the whole thing modular in practice rather than only in the code. Next work is scoped in the v3
roadmap above.
MIT.