personal-os

Personal OS (Claude Code plugin)

A personal operating system for Claude Code. A PA (Personal Assistant) agent is your single point of contact: it classifies every input and delegates to a worker tier running a leaf SOP skill. Out of the box it ships generic — zero personal data baked in — and a first-run wizard personalizes your workspace.

What you get

• Agents: pa plus three worker tiers (junior-worker, senior-worker, lead-worker).
• PA as the default driver — see below.
• Core SOP skills: sop-task, sop-wiki, sop-plan, sop-schedule, sop-draft-reply, research, setup-skill-permissions, plus the knowledge/* sub-skills.
• Workflows: workflow-setup-os (the setup wizard), workflow-process-message, workflow-ingest-notes, workflow-triage-tasks.
• Dev pack: sop-dev-ingest-repo, sop-dev-requirements, sop-dev-architecture, sop-dev-work-breakdown, sop-dev-implement, sop-dev-test, and the workflow-deliver-feature SDLC orchestrator. The dev SOPs are stack-agnostic — they read the target repo's PROJECT_CONTEXT.md and follow its existing conventions.
• Templates: generic CLAUDE.md (with a ## Config section), framework.md, wiki SCHEMA.md, and the task template.

Prerequisites

• Claude Code with plugin support.
• A calendar MCP server (optional). Scheduling skills (sop-schedule, sop-plan) can create real calendar events when a calendar MCP (e.g. mcp-ical) is available. It is optional: if you set mcp_ical_present = n in your Config, scheduling degrades gracefully — the skill still recommends a slot and records it in the task/plan, but does not create an event. Configure your calendar MCP in your environment's .mcp.json if you want live events.

Install

From a marketplace:

/plugin marketplace add ygavrilov/plugin-personal-os
/plugin install personal-os@personal-os-marketplace

Or load locally for testing:

claude --plugin-dir /path/to/plugin-personal-os

After install, run /reload-plugins (or restart) so the skills and agents register.

First run

1. Open Claude Code in the directory you want to use as your Personal OS workspace.
2. Invoke the setup wizard: personal-os:workflow-setup-os (or say "set up personal os").
3. Answer the grouped interview:
   • Identity — name, role, employer, timezone, working language.
   • Work rhythm — work-hour start, anchor meeting, calls window, no-go hours.
   • Daily slots (optional) — recurring slots and what each is best for.
   • Calendars — mcp_ical_present (y/n), primary calendar, read-only reference calendars.
   • Framework dimensions are deferred — you set your benefit dimensions and weights during your first planning session, not in the wizard.
4. The wizard writes your answers into the ## Config section of CLAUDE.md, lays down framework.md from template, scaffolds your workspace (wiki/, tasks/, weeks/, drafts/, research/, inbox.md), and regenerates skill permissions.

The wizard is idempotent — re-run it any time to change a group; it never destroys your data.

Establishing your priority framework

Personal OS scores work by self-benefit using dimensions and weights you choose. There are no defaults. Run sop-plan (quarterly or weekly) for your first planning session — that's where you define your dimensions and their weights. They are recorded in the ## Config section of CLAUDE.md, which framework.md treats as the authoritative source.

PA is the default driver

On install, the plugin makes the PA agent the active orchestrator and enforces the route-everything-through-PA workflow. Two supported plugin mechanisms do this:

1. Default agent. The plugin ships a root settings.json containing { "agent": "pa" }. Claude Code applies this when the plugin is enabled, activating the PA agent as the main thread (its system prompt, tools, and model) — so PA is the single point of contact without any manual selection.
2. Workflow enforcement hook. A UserPromptSubmit hook (hooks/hooks.json → hooks/enforce-workflow.js, resolved via ${CLAUDE_PLUGIN_ROOT}) injects a MANDATORY PA PROTOCOL into context on every prompt: before spawning any worker/Agent, PA must invoke workflow-process-message and route the input. Build, config, and meta requests are not exempt.

Together these make installing the plugin enough to have PA drive the workspace. After install run /reload-plugins (or restart) so the agent setting and hook register. The consuming workspace's CLAUDE.md (from the template) also states PA is the single entry point, reinforcing the behavior for any session.