Based on repository activity, growth velocity and community engagement.
24
Growth1/30
Activity10/25
Popularity1/25
Trust12/20
1
Stars
High
Sentiment
Votes
1
README.md
WingmanOS
A personal AI operating system that runs on Claude Code. Markdown files, a
handful of skills, and a web dashboard — no database, no framework, no
subscriptions beyond the one you already have.
It plans your day, tracks every deadline against a compressed "crunch" date,
tutors you without doing the thinking for you, and builds a second brain that
compounds instead of rotting.
Built to run on a Pro plan. Token efficiency is a design constraint here,
not an afterthought — see Token discipline.
Quick start
New to Claude Code? Read START-HERE.md instead — it
covers installing everything from scratch, assumes no coding experience, and
takes about 15 minutes.
git clone https://github.com/sadmanc/wingmanos.git ~/wingmanos
cd ~/wingmanos
claude
Then type:
/onboard
That's it. The onboarding interview asks about your life and builds the OS
around it — your domains, your priorities, how you learn. You get a working
system after step 2 (about five minutes); everything after that is optional
and can happen whenever.
There is nothing to install, no API key to get, and no account to create.
What you get
The daily loop
morning /day energy check → today's stack → state/today.md
midday /checkin where am I, what now
evening /wrap roll unfinished tasks, log the day, set tomorrow's opener
weekly /week pick max 3 outcomes
anytime /deadlines capture anything with a date
anytime /capture dump anything, it gets routed
Three tasks a day, not eight. Each one names its first two minutes, because
starting is the hard part, not doing. Slipped tasks roll forward and nothing
scolds you.
Crunch dates
Every deadline gets two dates: the real one, and a crunch date at ~40% of
the runway. The OS only ever talks about the crunch date. A midterm two weeks
out is treated as five days out, and the remaining nine days are a safety
margin you never see. This is Parkinson's law used deliberately.
The learning loop
/study zero-prep tutor session — starts in under a minute from whatever exists
/drill practice + honest grading + weak-spot tracking
/crunch test-prep mode, planned backwards from the crunch date
/review spaced repetition (FSRS-6)
The tutor is question-first on purpose. A 2025 RCT found students with
unrestricted AI help scored 57.5% vs 68.5% on a surprise retention test 45 days
later. An AI that explains things beautifully is the worst case. So this one
makes you explain, then probes, then corrects with the mechanism.
The second brain
A three-layer knowledge base based on Karpathy's LLM-wiki pattern, with the
2026 upgrades that the original design is missing:
brain/raw/ — sources you keep. Immutable. The agent reads, never edits.
brain/wiki/ — interlinked pages the agent writes and maintains.
brain/CLAUDE.md — the schema governing both.
/ingest a video, article, PDF, or note → deduped, cross-linked wiki pages
/recall search everything you've ever saved
/lint hunt contradictions, stale claims, and orphaned pages
/recall is grep-first and costs zero tokens to search. Anthropic removed
vector search from Claude Code in 2025 because plain grep outperformed it; a
2026 paper found the same across every model tested. Semantic search is
available as an optional upgrade for when literal search genuinely fails, but
most of the time you find your notes with the words you actually wrote.
/lint is the piece almost every second-brain setup skips, and it's the reason
they die. Notes don't fail by disappearing — they fail by quietly going stale
until you stop trusting the pile.
A web command center for desktop and phone: today's stack with tap-to-check
boxes, the deadline ledger, idea capture, and a chat tab that is full Claude
Code in the browser. Zero npm dependencies — Node built-ins only. Add it to
your phone's home screen and it behaves like a native app.
Nudges that cost nothing
Scheduled local scripts push to your phone: a morning plan nudge, a midday
check that only fires if the day has no plan, an evening wrap warning, and
crunch-date alerts. These run as plain shell scripts. They never invoke
Claude, so they consume zero tokens.
bash scripts/install-automations.sh
It becomes yours by growing its own skills
WingmanOS ships 17 skills and nothing about your job. That's deliberate.
A teacher, a nurse, a founder, and a second-year CS student need completely
different things, and no template can guess which. So instead of shipping forty
profession packs you'll never use — each one costing context at every session
start — the OS ships the ability to grow one:
/new-skill
Describe something you do repeatedly. Ten minutes later you have a working,
tested, registered skill. No code — a skill is a markdown file with
instructions. If you can explain how you do something, it can be a skill.
/level-up is the weekly version: it reads your logs, finds the thing you did
by hand three times, and ships a skill for it.
Anti-rot checks
Every fragile dependency in your setup gets a one-file predicate in checks/.
A daily run verifies each one and pushes a notification only when something
actually breaks. This is what keeps the OS from silently degrading — the
failure mode where three integrations died two months ago and you never noticed.
Token discipline
This runs on a Pro plan, which means the design fights for context on purpose:
CLAUDE.md stays under 200 lines. Past that, adherence measurably drops.
Skills load lazily. Only a skill's one-line description sits in context at
session start; the body loads when you invoke it. Skills with side effects
are marked disable-model-invocation: true, which drops them to zero
startup cost until you type their name.
Every subagent pins model: haiku explicitly. An omitted model field
silently inherits your session's model — which is how people accidentally run
a fleet of Opus subagents.
Deterministic work lives in hooks, which run as shell scripts outside the
model and cost literally nothing.
The OS reads indexes, not directories. This is an accuracy decision as
much as a cost one: model accuracy drops 30–50% on long contexts, well before
the documented limit.
Run /context-budget any time to audit what your setup is actually costing.
Python 3.9+ (scripts only — optional, stdlib only)
The core OS needs none of these. It's markdown.
Philosophy
Read references/psych-playbook.md before
changing anything. Almost every rule that looks arbitrary is downstream of a
specific finding — the energy check, the three-task cap, the crunch dates, the
refusal to moralize a missed day, the question-first tutor. That file is the
argument for all of it.
The two rules everything else follows from:
Value in the first minute. Any flow that needs three setup steps before
it pays off will be abandoned before it pays off.
Protect trust in retrieval. These systems don't die from too much work.
They die when you stop believing the pile is worth adding to.
Fork it, change anything
This is meant to be taken apart. Rename it, delete half of it, rewrite the
prompts, build a business on it. The only ask is that you keep
CREDITS.md in the repo.
FORKING.md is the map: what's a real contract (four parsing
formats the dashboard depends on) versus what's just an opinion you should feel
free to overrule. Everything else — every skill, the whole dashboard, the
psych playbook, the name — is yours to change.
If you build something good on top of it, publish it. A skill written for
teachers or nurses or musicians is worth more to those people than anything a
generic template could ship.
License
MIT — see LICENSE. Attributions and prior art in
CREDITS.md; keep that file and you're square.
Ecosystem Role
Standard MoltPulse indexed agent.
Embed Badge
Show off your Pulse Score in your GitHub README to build trust and rank higher.