LifeOS USER Tree Structure and Personal Configuration Templates: A Complete Guide

The LifeOS USER tree is a private git repository at ~/.config/LIFEOS/USER that stores all personal data and configuration templates, safely isolated from the public system code and never overwritten during upgrades.

The danielmiessler/LifeOS repository separates system code from user data through a strict directory architecture. All personal state lives in the USER tree—a symlinked private repository that lets you customize identity, goals, assistant behavior, and skill configurations without touching public source files. This guide explains the canonical structure and how to leverage personal configuration templates effectively.

---

LifeOS USER Tree Structure Overview

The USER tree follows a deliberate scaffolding pattern with blank template files you populate after installation. As documented in README.md, the installer only adds new template files without overwriting your edits during upgrades【/README.md†L117-L119】.

LIFEOS/USER/
├─ ARCHITECTURE_SUMMARY.md          # Auto-generated routing table

├─ CONFIG/
│   ├─ OPERATIONAL_RULES.md         # Global policy for hooks, safety-gates

│   ├─ LIFEOS_CONFIG.toml           # Runtime configuration (user-overridden)

│   └─ CREDENTIALS/                 # Private API keys (never shipped)

├─ PRINCIPAL/
│   ├─ PRINCIPAL_IDENTITY.md        # Core identity (name, values, story)

│   ├─ WRITINGSTYLE.md              # Personal voice for generative tasks

│   ├─ RHETORICALSTYLE.md
│   └─ ...                          # Optional resume, pronunciations, etc.

├─ DIGITAL_ASSISTANT/
│   ├─ DA_IDENTITY.md               # Assistant's persona

│   └─ DA_MEMORY.md                 # Persistent memory for the assistant

├─ TELOS/
│   ├─ TELOS.md                     # Primary life-context (goals, beliefs)

│   ├─ PRINCIPAL_TELOS.md           # Auto-generated derivative

│   ├─ MISSION.md
│   ├─ GOALS.md
│   ├─ CURRENT_STATE/               # Snapshots of present reality

│   └─ IDEAL_STATE/                 # Desired future state

├─ CUSTOMIZATIONS/
│   └─ SKILLS/
│       ├─ WriteStory/              # Skill-specific config

│       ├─ ThreatModel/             # Private data for security modeling

│       ├─ LocalIntelligence/       # Personal news-source preferences

│       └─ ...                      # One folder per installed skill

├─ WORK/
│   ├─ PROJECTS.md
│   └─ ...                          # Project-specific artifacts

├─ FINANCES/
│   ├─ ACCOUNTS.md
│   ├─ TAXES.md
│   └─ ...                          # Budget, investments

└─ ...                              # HEALTH, GEAR, etc.

---

Key USER Tree Directories Explained

TELOS/ — Your Life Operating System

The TELOS directory stores goals, beliefs, and state definitions. The TELOS.md file serves as the single source of truth for personal context. Skills reference this to align outputs with your values and priorities.

Template location: LifeOS/install/USER/TELOS/TELOS.md

PRINCIPAL/ — Identity and Voice Configuration

The PRINCIPAL directory contains your core identity and stylistic preferences. The WRITINGSTYLE.md template biases generative output across all skills that produce text.

Key templates:

• PRINCIPAL_IDENTITY.md — Core identity (name, values, story)
• WRITINGSTYLE.md — Tone, vocabulary, structural preferences
• RHETORICALSTYLE.md — Argumentation patterns

DIGITAL_ASSISTANT/ — AI Persona and Memory

The DIGITAL_ASSISTANT directory defines your AI assistant's behavior. DA_IDENTITY.md sets the persona, while DA_MEMORY.md persists context across sessions.

CUSTOMIZATIONS/SKILLS/ — Per-Skill Private Data

The CUSTOMIZATIONS/SKILLS directory contains one subdirectory per installed skill. Each skill reads its configuration from here, keeping private data separate from system code.

---

How to Use Personal Configuration Templates

Initial Installation and Scaffolding

When you run the LifeOS installer, it executes the ScaffoldUser tool to populate your private repository:

# During initial setup

./install.sh

# Or apply updates to add new templates (never overwrites existing files)

bun Tools/ScaffoldUser.ts --apply

The ScaffoldUser.ts tool adds only missing files—your existing customizations remain untouched【/LifeOS/Workflows/Update.md†L30-L31】.

Editing Templates for Customization

Modify any template directly with your preferred editor. Changes take effect immediately for skills that read those files.

Example: Customizing writing style

vim ~/.claude/LIFEOS/USER/PRINCIPAL/WRITINGSTYLE.md

# Writing Style

- Tone: conversational, direct, occasionally humorous
- Vocabulary: precise technical terms explained in plain English
- Structure preference: problem-solution format with numbered steps
- Avoid: passive voice, filler words, corporate jargon

Skills like WriteStory and Remotion read this file to bias generated content【/skills/Remotion/Workflows/GeneratedContentVideo.md†L33-L34】.

Applying Templates to Specific Skills

Skills declare their expected USER tree paths in their SKILL.md files. The ThreatModel skill, for example, expects data at LIFEOS/USER/SECURITY/THREATMODEL/【/skills/ThreatModel/SKILL.md†L23-L24】.

Creating a custom risk register:

mkdir -p ~/.claude/LIFEOS/USER/SECURITY/THREATMODEL

cat > ~/.claude/LIFEOS/USER/SECURITY/THREATMODEL/risk-register.json <<'EOF'
{
  "infrastructure": {
    "owner": "platform-team",
    "impact": 4,
    "likelihood": 3,
    "mitigation": "automated patching, segmented networks"
  },
  "supply-chain": {
    "owner": "security-team",
    "impact": 5,
    "likelihood": 2,
    "mitigation": "signed artifacts, dependency scanning"
  }
}
EOF

Running LifeOS run ThreatModel incorporates this data via RiskRegister.ts, which defaults to the USER tree location【/skills/ThreatModel/Tools/RiskRegister.ts†L6-L7】【/skills/ThreatModel/Tools/RiskRegister.ts†L65-L66】.

Programmatic Template Access

From TypeScript tools, read USER templates using standard filesystem operations:

import { readFileSync } from "fs";
import { join } from "path";

const USER_ROOT = join(process.env.HOME!, ".claude", "LIFEOS", "USER");

// Load personal writing style for generative tasks
const stylePath = join(USER_ROOT, "PRINCIPAL", "WRITINGSTYLE.md");
const writingStyle = readFileSync(stylePath, "utf-8");

// Extract structured preferences
const preferences = writingStyle
  .split("\n")
  .filter(line => line.startsWith("- "))
  .map(line => line.slice(2).trim());

console.log("Active writing preferences:", preferences);

Safe Upgrades and Template Recovery

The upgrade mechanism guarantees configuration preservation. If you need to restore a default template, delete the file and rescaffold:

# Remove corrupted or unwanted customization

rm ~/.claude/LIFEOS/USER/PRINCIPAL/WRITINGSTYLE.md

# Restore default template (only affects missing files)

bun Tools/ScaffoldUser.ts --apply

---

Configuration Files Reference

File	Purpose	Location in Source
OPERATIONAL_RULES.md	Safety-gate definitions for hook behavior	LifeOS/install/USER/CONFIG/OPERATIONAL_RULES.md
LIFEOS_CONFIG.toml	Runtime configuration overrides	LifeOS/install/USER/CONFIG/LIFEOS_CONFIG.toml
TELOS.md	Primary life context (goals, beliefs)	LifeOS/install/USER/TELOS/TELOS.md
PRINCIPAL_IDENTITY.md	Core identity for interview workflows	LifeOS/install/USER/PRINCIPAL/PRINCIPAL_IDENTITY.md
DA_IDENTITY.md	Assistant persona definition	LifeOS/install/USER/DIGITAL_ASSISTANT/DA_IDENTITY.md

---

Summary

• USER tree location: ~/.config/LIFEOS/USER (symlinked at LIFEOS/USER) keeps personal data isolated from public system code.
• Template editing: Modify markdown/yaml files in PRINCIPAL/, TELOS/, CONFIG/, or CUSTOMIZATIONS/SKILLS/ to personalize behavior.
• Skill integration: Skills reference USER paths via their SKILL.md declarations and load configurations at runtime.
• Upgrade safety: ScaffoldUser.ts only adds missing templates—existing files are never overwritten.

---

Frequently Asked Questions

Where is my LifeOS USER directory physically stored?

Your USER directory lives at ~/.config/LIFEOS/USER as a private git repository. The LIFEOS/USER path in your working directory is a symlink to this location. This design ensures personal data never commits to the public LifeOS repository while remaining accessible to all system tools.

Will installing LifeOS updates overwrite my personal configurations?

No. The ScaffoldUser.ts tool explicitly checks for existing files and only adds missing templates【/README.md†L117-L119】. Your edits to TELOS.md, WRITINGSTYLE.md, skill configurations, and all other USER tree files persist across upgrades indefinitely.

How do I add custom configuration for a new skill I installed?

Create a directory under LIFEOS/USER/CUSTOMIZATIONS/SKILLS/ matching the skill name. Add a config.yaml, PREFERENCES.md, or whatever the skill's SKILL.md documentation specifies. The skill will automatically detect and load your configuration on next execution.

Can multiple machines share the same LifeOS USER configuration?

Yes. Since the USER tree is a standard git repository at ~/.config/LIFEOS/USER, you can push to a private remote and clone it on other machines. Run bun Tools/ScaffoldUser.ts --apply on each new installation to ensure any newly added system templates are present without disrupting your synced customizations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}