/xray - The AI Education Experience

Default behavior: Explain what just happened in THIS conversation — the specific tools, files, and context that were used, with educational explanations of WHY.

With qualifiers: Deep dive into specific topics (AI fundamentals, Dex architecture, how to extend).

Philosophy

The best way to learn is by examining what just happened, not abstract concepts. When you run /xray:

1. Show the work - What tools ran, what files were read/written
2. Explain why - Why each action was necessary
3. Connect to concepts - Link specific actions to how AI/Dex works
4. Empower extension - "You could customize this by..."

The outcome: Users learn AI by examining their own conversations, then go deeper if curious.

Tone: Like a senior engineer doing a code review of what just happened. "Here's what I did and why."

Step 1: Determine Mode

Default (no arguments): "This Conversation"

When user just says /xray with no qualifier: → Immediately explain what happened in this conversation → Don't show a menu, just show the work

With qualifiers: Specific topics

| Command | What it does | |---------|--------------| | /xray | (default) Explain what just happened in this chat | | /xray ai or /xray fundamentals | First principles: context windows, tokens, statelessness | | /xray dex or /xray architecture | How Dex works: CLAUDE.md, hooks, MCPs, skills | | /xray boot or /xray session start | The session startup sequence | | /xray extend or /xray customize | How to customize and build on Dex yourself |

DEFAULT MODE: This Conversation (Show Your Work)

This is the primary mode. When user runs /xray, explain what happened.

Step 1: Analyze the conversation

Look at the current conversation and identify:

1. What files were read
2. What files were written/modified
3. What tools/MCPs were used
4. What context was loaded at session start (check for <previous_session_memories> etc.)
5. Key decision points in the AI's reasoning

Step 2: Present as educational walkthrough

Output format:

markdown
## 🔬 X-Ray: What Just Happened

Let me explain what happened under the hood in our conversation.

---

### 📖 The Story of This Chat

Here's what I did, step by step:

**1. Session Started**
Before you typed anything, the system loaded:
- `CLAUDE.md` (~X tokens) — My personality, your preferences, available tools
- Session memories from earlier today — [list what was injected]
- [Any other context visible from hooks]

**Why this matters:** Without those session memories, I'd have no idea about 
[specific context]. That came from a **session hook** that runs before you type.

**2. You Asked: "[summarize their first message]"**

To respond, I:
- Read `[file 1]` — Because [reason]
- Read `[file 2]` — To check [what]
- Used [tool/MCP] — To [action]

**Why these files?** Your CLAUDE.md tells me where to look. It says [quote relevant 
instruction]. Without those instructions, I wouldn't know your file structure.

**3. [Continue for each major exchange in the conversation]**

---

### 🔧 Tools Used This Session

| Tool | Times Used | What For |
|------|------------|----------|
| `read` | X | Reading vault files |
| `write` | X | Creating new content |
| `edit` | X | Updating existing files |
| `bash` | X | Running commands |
| [other tools] | X | [purpose] |

**Why tools matter:** Without tools, I can only generate text. Tools let me 
actually DO things — read your files, write new ones, check your calendar, etc.

---

### 💡 Key Insight: The Context Window

Everything I "know" right now is what's in the **context window**:

┌─────────────────────────────────────────────────┐ │ What I can see (the context window) │ ├─────────────────────────────────────────────────┤ │ ✓ CLAUDE.md (loaded at start) │ │ ✓ Session memories (injected by hooks) │ │ ✓ Our full conversation so far │ │ ✓ Every file I've read this session │ │ ✓ Every tool result I've received │ ├─────────────────────────────────────────────────┤ │ ✗ Files I haven't read │ │ ✗ Previous sessions (unless summarized) │ │ ✗ Anything not loaded into context │ └─────────────────────────────────────────────────┘

If something isn't in this window, I literally don't know it exists.

---

### 📁 Files Touched This Session

**Read (loaded into my context):**
- `[file]` — [why it was needed]
- [continue for each file]

**Written/Modified:**
- `[file]` — [what was created/changed]
- [continue for each file]

**Why this matters:** Every file I read uses "tokens" (space in the context 
window). I try to read only what's relevant, not everything.

---

### 🎓 Concepts You Just Saw in Action

| What Happened | The Underlying Concept |
|---------------|------------------------|
| I knew about earlier conversations | **Session hooks** inject context at start |
| I read CLAUDE.md first | **System prompt** loads before anything |
| I created files with tools | **Tools** let AI take action, not just talk |
| I followed your file conventions | **CLAUDE.md instructions** define your structure |
| I didn't know about [X] | **Context limitation** — only know what's loaded |

---

### 🔮 What You Could Customize

Based on what just happened:

**1. Add to CLAUDE.md**
If you want me to always [behavior], add it to your `USER_EXTENSIONS` block.

**2. Create a Skill**
If you do [this workflow] often, create a skill to automate it.

**3. Add a Session Hook**
If you always want [context] loaded at start, write a hook that injects it.

---

### 🎓 Want to Go Deeper?

- `/xray ai` — First principles: context windows, tokens, statelessness
- `/xray dex` — Full architecture: CLAUDE.md, hooks, MCPs, skills, vault
- `/xray boot` — The session startup sequence in detail
- `/xray extend` — Step-by-step guide to customizing

Or ask anything: "How do hooks work?", "What's an MCP?", "How can I add my own tools?"

MODE: AI Fundamentals (/xray ai)

Purpose: Teach the core concepts that make everything else make sense.

Output Format

markdown
## 🧠 How AI Actually Works

Let me explain the core concepts that underpin everything Dex does.

---

### The Big Truth: AI Has No Memory

**The fundamental problem:** Every time you start a new chat, Claude has amnesia. 
It doesn't remember yesterday's conversation. It doesn't know your name, your 
projects, or what you discussed last week.

This is true for ALL LLM-based AI — ChatGPT, Claude, Gemini, all of them.

**Why?** LLMs are "stateless." They process text in, text out, with no permanent 
storage between sessions. Each conversation starts from zero.

**So how does Dex remember things?** We engineer around the limitation. 
That's what Dex is — clever engineering to give a forgetful AI the *appearance* 
of memory, context, and continuity.

---

### Concept 1: The Context Window

When you chat with an AI, there's an invisible "window" of text the AI can see:

┌─────────────────────────────────────────────────┐ │ THE CONTEXT WINDOW │ │ (Everything the AI knows about THIS chat) │ ├─────────────────────────────────────────────────┤ │ • System prompt (CLAUDE.md) │ │ • Injected context (session memories, etc.) │ │ • Our conversation so far │ │ • Any files I've read │ │ • Tool results (MCP responses) │ └─────────────────────────────────────────────────┘ ↓ AI generates response based on ALL of this

**Key insight:** The AI can only work with what's IN the context window. 
If information isn't in there, the AI doesn't know it exists.

**Dex's job:** Get the RIGHT information INTO that window at the RIGHT time.

---

### Concept 2: Tokens (The Currency)

Context windows are measured in "tokens" (roughly 4 characters = 1 token).

- Claude's window: ~200,000 tokens (~150,000 words)
- Your CLAUDE.md: ~4,500 tokens
- A typical person page: ~500 tokens

**Why it matters:** There's a budget. Load too much context and you hit limits 
or slow things down. Load too little and the AI lacks crucial information.

**Dex's approach:** Selective loading. Don't dump everything — load what's 
*relevant* to what you're asking about.

---

### Concept 3: System Prompts (The Personality)

Before your first message, there's already text in the context window: 
the **system prompt**. For Dex, that's `CLAUDE.md`.

┌─────────────────────────────────────────────────┐ │ CLAUDE.md (loaded before you type anything) │ ├─────────────────────────────────────────────────┤ │ "You are Dex, a personal knowledge assistant" │ │ "User's pillars: your pillars]" │ │ "When tasks are mentioned, use Work MCP" │ │ "Person pages are in 05-Areas/People/" │ │ ... (hundreds more lines of context) │ └─────────────────────────────────────────────────┘

**The power move:** Everything in CLAUDE.md influences EVERY response. 
It's like setting the AI's personality and knowledge before you say hello.

---

### Concept 4: Tools (How AI Does Things)

Claude can't *do* things by default — it can only generate text. But with 
**tools**, it can take actions:

- Read files from your computer
- Write new files
- Run commands
- Query databases
- Call APIs

In Dex, tools come from **MCP servers** (Model Context Protocol). Each MCP 
gives Claude new capabilities.

**Without tools:** Claude can only talk.
**With tools:** Claude can take action on your behalf.

---

### Concept 5: The Conversation Loop

Here's what happens every time you send a message:

1. Your message gets added to context window

↓

1. Claude sees: system prompt + history + your message

↓

1. Claude decides: should I use a tool?

• If yes → Tool runs → Result added to context → Back to step 3
• If no → Generate response

↓

1. Response appears (and gets added to context for next turn)

↓

1. Wait for your next message → Repeat from step 1

**Key insight:** Each turn, Claude sees MORE context (the history grows). 
Long conversations = more context = closer to limits.

---

### So What?

Understanding these fundamentals helps you:

1. **Know why Dex loads things at session start** — to get context into the window
2. **Understand why some info is "missing"** — it wasn't loaded into context
3. **See opportunities to extend** — what else could be loaded? what tools could help?

---

**Want to see Dex's specific architecture?** Try `/xray dex`

MODE: Dex Architecture (/xray dex)

Purpose: Explain the specific building blocks that make Dex work.

Output Format

markdown
## 🏗️ How Dex Works: The Architecture

Now that you understand AI fundamentals, here's how Dex engineers around 
the limitations to create something useful.

---

### The Core Insight

**Problem:** Claude forgets everything between sessions.  
**Solution:** Store everything in FILES and reload context intelligently.

┌─────────────────────────────────────────────────┐ │ YOUR VAULT │ │ (Plain Markdown files YOU own) │ ├─────────────────────────────────────────────────┤ │ • CLAUDE.md - Core context & personality │ │ • 05-Areas/People/ - Relationship memory │ │ • 03-Tasks/Tasks.md - Work in progress │ │ • System/Session_Memory/ - Past conversations │ │ • System/Work_In_Progress.md - Active projects │ └─────────────────────────────────────────────────┘ ↓ loaded at session start ↓ ┌─────────────────────────────┐ │ AI Context Window │ └─────────────────────────────┘

**The magic:** Your knowledge lives in files. AI reads files. 
Therefore, AI can "remember" by reading what was written before.

---

### Building Block 1: CLAUDE.md (The Brain)

The system prompt that defines who Dex is and how it behaves.

**Location:** `/CLAUDE.md` (root of your vault)

**Contains:**
- Your user profile (name, role, company)
- Your strategic pillars
- How Dex should behave
- What skills are available
- References to other docs

**Why it matters:** This loads FIRST, before anything else. It shapes every 
response. Edit this, and you change how Dex thinks.

**You can customize:**

USER_EXTENSIONS_START

<!-- Your personal additions go here -->

USER_EXTENSIONS_END

---

### Building Block 2: Session Hooks (The Boot Sequence)

When you start a chat, things happen BEFORE you type anything.

**What hooks do:**
- Inject session memories from recent conversations
- Surface relevant context (person info, project status)
- Pre-load data you'll likely need

**Current hooks in Dex:**
- Session memories injection
- Person context surfacing
- Company context surfacing

**The power:** You can ADD hooks. Want weather loaded at session start? 
Your calendar? Write a hook, and it's there every session.

---

### Building Block 3: MCP Servers (The Toolbox)

MCP = Model Context Protocol. It's how Claude gets superpowers.

Each MCP server gives Claude new abilities:

| Server | What It Does |
|--------|--------------|
| **Work MCP** | Task management with deduplication and pillar alignment |
| **Calendar MCP** | Reads your Apple Calendar |
| **Granola MCP** | Searches meeting transcripts |
| **Career MCP** | Career evidence tracking and analysis |

**Why MCPs instead of just reading files?**
- **Speed:** Pre-process data instead of parsing raw files
- **Logic:** Implement business rules (like "can't have 4 P0 tasks")
- **Integration:** Connect to external systems

---

### Building Block 4: Skills (The Playbook)

Skills are structured instructions for multi-step workflows.

**Location:** `.claude/skills/[skill-name]/SKILL.md`

**Examples:**
- `/daily-plan` - Check calendar, review tasks, generate plan
- `/meeting-prep` - Load person context, surface recent discussions
- `/xray` - This skill you're running right now!

**Why skills?**
- **Consistency:** Same workflow every time
- **Complexity:** Handle multi-step processes
- **Reusability:** Build once, use forever

---

### Building Block 5: The Vault (The Memory)

Everything persists to Markdown files:

Your Vault/ ├── 00-Inbox/ ← Capture zone ├── 03-Tasks/ ← Active tasks ├── 04-Projects/ ← Time-bound work ├── 05-Areas/ ← Ongoing responsibilities │ ├── People/ ← Person pages │ └── Companies/ ← Company profiles ├── 06-Resources/ ← Reference material └── System/ ← Dex configuration

**Why plain Markdown?**
- You own it forever (no vendor lock-in)
- Works anywhere (Obsidian, VS Code, any editor)
- AI can read and write it
- Version control with Git if you want

---

### How It All Connects

Session starts ↓ Hooks fire (inject context) ↓ CLAUDE.md loads (personality + instructions) ↓ You type your message ↓ Claude reads relevant files (on-demand) ↓ Claude uses MCPs (if needed) ↓ Response generated + files updated ↓ Repeat for each message

---

### Key Insight: It's All Text

There's no magic database. No proprietary format. No cloud service.

- CLAUDE.md is text
- Skills are text
- Your notes are text
- Session memories are text

Claude reads text, processes it, generates text, writes text.

**Everything you're experiencing is text transformation.**

Understanding this is liberating — you can read, edit, and extend anything.

---

**Want to see the session startup in detail?** Try `/xray boot`
**Ready to customize?** Try `/xray extend`

MODE: Session Boot Sequence (/xray boot)

Purpose: Detailed walkthrough of what happens when a session starts.

Output Format

markdown
## 🚀 What Happens When You Start a Chat

Let me walk you through exactly what happens from the moment you open 
a new chat to when you type your first message.

---

### The Boot Sequence (In Order)

#### Step 1: Environment Detection

Is this Claude Desktop? Claude Code? Cursor? PI? ↓ Each environment has slightly different capabilities

#### Step 2: Settings Load

Read configuration files ↓ This defines which hooks to run and which MCPs are available

#### Step 3: Hooks Fire (CRITICAL)

Pre-session hooks run in order: ↓ ┌─────────────────────────────────────────────┐ │ Session memory injection │ │ → Reads System/Session_Memory/date].md │ │ → Injects summaries of recent conversations │ │ → AI "remembers" what you discussed before │ └─────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────┐ │ Context injectors │ │ → Person context ready when you mention │ │ names │ │ → Company context ready when relevant │ └─────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────┐ │ (Your custom hooks could go here) │ │ → Whatever YOU want loaded at start │ └─────────────────────────────────────────────┘

**This is where the magic happens!** Hooks let you inject ANY context 
before the conversation starts.

#### Step 4: CLAUDE.md Loads

The entire CLAUDE.md file enters the context window: ↓ • Your profile (name, role, company) • Your strategic pillars • Behavior guidelines • Reference to skills and tools • User extensions (YOUR customizations)

#### Step 5: MCPs Connect

MCP servers become available: ↓ • Calendar MCP → Ready to check schedule • Work MCP → Ready to manage tasks • Granola MCP → Ready to search meetings

#### Step 6: Ready for Input

NOW you can type your first message.

The AI already has: • Your personality and preferences (CLAUDE.md) • Recent conversation summaries (from hooks) • Relevant context (from hooks) • Access to tools (MCPs)

---

### What This Means for You

**The AI doesn't start from zero.** By the time you type your first message, 
Claude already knows who you are, what you've been working on, and what 
tools are available.

**The boot sequence IS the memory system.** It's how a stateless AI 
"remembers" who you are.

---

### 💡 Customization Opportunity

**What else could be loaded at session start?**

Ideas for hooks:
1. Today's calendar events
2. Current sprint goals
3. Recent Git commits
4. Weather for outdoor planning
5. Your daily intention

**The pattern:** Anything you want the AI to "know" at the start of every 
session can be injected via a hook.

---

**Ready to create your own customizations?** Try `/xray extend`

MODE: How to Extend (/xray extend)

Purpose: Practical guide to customization.

Output Format

markdown
## 🛠️ How to Extend Dex

Now that you understand how it works, here's how to make it your own.

---

### Level 1: Edit CLAUDE.md (5 minutes)

**The simplest customization.** Add your own instructions:

1. Open `CLAUDE.md` in any editor
2. Find the `USER_EXTENSIONS` section
3. Add your rules:

USER_EXTENSIONS_START

My Preferences

• I'm a morning person — suggest important work before noon
• "The board" always means my company's board of directors
• Never suggest scheduling meetings on Wednesdays (my focus day)

USER_EXTENSIONS_END

**This survives updates.** When you run `/dex-update`, this block is preserved.

---

### Level 2: Create a Skill (30 minutes)

**Make a reusable workflow:**

1. Create folder: `.claude/skills/my-skill/`
2. Create file: `SKILL.md`

name: my-skill description: What it does in one line

My Custom Skill

When to Use

Trigger conditions]

Steps

Instructions for Claude to follow]

Output Format

What the result should look like]

3. Use it: Just type `/my-skill`

**Example ideas:**
- `/standup-prep` - Generate daily standup update
- `/client-brief` - Create client meeting brief
- `/weekly-email` - Draft weekly summary email

---

### Level 3: Create a Hook (1 hour)

**Inject context at every session start:**

1. Create a script that outputs the context you want
2. The output gets injected into the AI's context window
3. Now every conversation starts with that knowledge

**Example ideas:**
- Inject today's calendar at start
- Load current sprint goals
- Show recent Git commits

---

### Level 4: Create an MCP Server (Half day)

**Give Claude new capabilities:**

Run `/create-mcp` for guided setup.

**Example ideas:**
- Todoist MCP - Sync tasks with Todoist
- Notion MCP - Read/write to Notion
- Weather MCP - Get current conditions

---

### The Extension Philosophy

**Dex is scaffolding, not a finished product.** It's a starting point you customize.

The goal isn't to use Dex "as is" forever — it's to understand it well 
enough to make it truly yours.

**Question for you:** What do you wish the AI knew at the start of 
every session? That's your first extension.

Usage Tracking

After running /xray, silently update System/usage_log.md:

• Check X-ray transparency (/xray) in the discovery section

If user runs specific educational modes, update the AI Education Progress section:

• /xray ai → Check "Understands context windows", "Understands tokens"
• /xray dex → Check "Understands system prompts", "Understands tools/MCPs"
• /xray boot → Check "Understands session hooks"
• /xray extend → Check "Understands vault architecture"

Tone Guidelines

• Concrete over abstract — Use specific examples from their conversation
• Show don't tell — Point to actual files, tools, actions
• Empowering not impressive — Goal is their understanding, not your cleverness
• Inviting curiosity — End with pathways to learn more

Track Usage (Silent)

Update System/usage_log.md to mark AI transparency education as used.

Analytics (Silent):

Call track_event with event_name xray_used and properties:

• mode (context/tokens/prompts/tools/hooks/vault/extend)

This only fires if the user has opted into analytics. No action needed if it returns "analytics_disabled".