@sbains2/lifeos

Scaffold a personal LifeOS — life-quadrant folders, a council of AI agent voices, and curated MCP wiring.

⚠️ BETA — early seed release. v0.1.2. See ../BETA.md for what's stable vs not.

Usage

# Full wizard (~2-4 minutes for thoughtful first install)
npx @sbains2/lifeos [target-dir]

# Speed-optimized: skips longer-arc focus + role/affiliations + all
# quadrant/council/MCP confirmations. Uses template defaults everywhere.
# Target: <60 seconds.
npx @sbains2/lifeos [target-dir] --minimal

# Show help
npx @sbains2/lifeos --help

If target-dir is omitted, the CLI scaffolds into the current working directory.

What it does

7-step wizard:

1. Persona — pick grad-student / early-career-ic / solo-researcher
2. Profile — name, role, affiliations
3. Foci — what you're working toward (now / quarter / year / arc) with priority enum
4. Quadrants — auto-detects keywords (e.g. "president" → flips Leadership Role on); confirm or customize
5. Council — 10 voices with priority defaults from your persona
6. Apps & MCPs — checkbox of suggested servers, trust defaults applied
7. Validate + generate — refuses to write invalid configs; scaffolds folders + council files + INSTALL_MCPS.md + lifeos.config.json

Trust defaults

• Local-first. No network calls.
• Draft-only outreach. Gmail and similar MCPs ship with send_permission: false.
• Tokens by env-var name only. Auth tokens stay in your shell environment — never copied into config files, never logged.
• Validation before write. Refuses to write a config that fails any cross-reference check. No partial writes.

See ../docs/TRUST.md for the full commitments.

Now what? (post-install workflow)

After the wizard prints Done in Xm Ys., here's the path from "scaffold exists" to "council convenes on real artifacts":

1. Set env vars + restart Claude (~3-5 min the first time)

As of v0.1.5, the wizard does the heavy lifting for you:

• .mcp.json is already written in your scaffold dir — Claude Code, Cursor, and Cline auto-detect this
• Claude Desktop config was offered for merge (with backup) if you said yes
• Per-MCP setup status was already printed at the end of the wizard — read it carefully

What you still need to do, listed in the wizard's status report:

• For needs_env MCPs: set the env var in your shell (export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_...) — the wizard surfaced exactly which env vars + the URL to get each one. Add to your ~/.zshrc or ~/.bashrc for persistence.
• For needs_oauth MCPs: Claude will trigger the OAuth flow on first invocation — usually opens a browser, you click Authorize, done.
• For manual MCPs: read .lifeos/INSTALL_MCPS.md for install hints; these are MCPs without a single-command auto-install (e.g., Canvas, Discord, Apple Notes). One-time clone + build per repo.
• For risk MCPs (only LinkedIn at v0.1.5): if you said "yes, include in auto-config" the entry was wired; if "no" the MCP is in your lifeos.config.json but skipped from .mcp.json — install manually.

Then restart Claude Desktop (Cmd+Q, then reopen) so the new MCPs load. For Claude Code, restart your terminal or run claude /mcp to see the wired list.

2. Open the folder in Claude Code

cd <your-scaffolded-dir>
claude

(Or open in your IDE if you use the Claude Code IDE integration.)

Claude Code will pick up lifeos.config.json and the .claude/agents/council/ files automatically — they're conventional locations.

3. Try a council convening on a real artifact

The fastest way to feel the difference between LifeOS and "ChatGPT, please review my X" is to convene multiple council voices on a single artifact. Examples that work today:

• Resume / job-search: "Read my resume PDF in JobSearch/. Convene Career Coach, Writing Critic, Network Builder, and Devil's Advocate. Give me their reads as one synthesized session report. Write the result to JobSearch/council-sessions/[date]-resume-review.md."
• Class deliverable: "Look at my draft for [class] in Classes/. Convene Academic Advisor + Writing Critic. What's the methodological weakness most likely to undermine the argument?"
• Code change: "Read my recent commits in SideProjects/[repo]. Convene Tech Lead + Devil's Advocate. Surface the load-bearing assumption and the test that would falsify it cheaply."
• Week ahead: "Look at my Google Calendar via the calendar MCP and my open quadrant folders. Convene Time Manager + Performance Coach. What's at risk this week and what would the highest-leverage block of focused time look like?"

The council members are in .claude/agents/council/ — read them to see what each voice is for.

4. Edit lifeos.config.json to tune

The wizard accepts defaults at v0.1; granular per-member adjustment in the wizard is planned for v0.2. For now, just open the file and adjust:

• Council priorities: change priority: "warm" to "hot" for voices you want emphasized in synthesis sections, "cold" to disable
• Quadrant priorities: elevate "hot" for what's in the limelight this quarter
• Foci: add or remove entries; tune horizons and priorities
• MCPs: add config_overrides to tune per-server behavior (e.g., send_permission: true to enable Gmail send if you're sure)

Re-running npx @sbains2/lifeos against the same dir will prompt before overwriting your config.

5. Add your own quadrant or council member

Adding a quadrant: edit quadrants[] in your config, set active: true, set a priority, list council_member_ids and mcp_server_ids to wire, then mkdir <path> to create the folder.

Adding a council member: drop a markdown file in .claude/agents/council/<name>.md with the system prompt, then add an entry to council[] in your config with id, name, system_prompt_path, and priority.

The CLI's validation will refuse the config if any reference is broken — re-run npx @sbains2/lifeos --help to see flags, or just re-edit and re-validate manually with node cli/test/smoke-scaffold.mjs (during local dev).

Local development

git clone <repo>
cd lifeos/cli
npm install
node --test test/*.test.js   # unit tests (validate + quadrants)
node test/smoke-scaffold.mjs # end-to-end scaffold pipeline test
npm start ~/lifeos-trial     # run the wizard against a fresh dir

The bundled templates at cli/templates/ are the canonical copy. The npm run sync-templates script (legacy from when templates were duplicated at the repo root) is a no-op in this repo.

Status

v0.1.2 — second runnable iteration after first cold-start trial. See ../CHANGELOG.md for what shipped when.

What's NOT yet implemented (see ../BETA.md):

• lifeos doctor / brain / migrate commands
• Granular per-quadrant / per-council priority adjustment in the wizard
• ~/.lifeos/wizard-history.json reuse for second-machine installs
• Custom-persona path
• Telemetry plumbing
• npm publish (install via git clone for now)