Skip to content

danielmiessler/Personal_AI_Infrastructure

Repository files navigation

PAI Logo

Personal AI Infrastructure

Typing SVG


GitHub Release GitHub Stars Last Commit License

Packs Bundles Contributors

Built with Claude TypeScript Bun UL Community


Getting Started: AI-First Install · What is PAI? · New to This? · The Algorithm · Principles · Primitives

Installation: Packs & Bundles · How AI Install Works · Browse Packs · Browse Bundles · Quick Start

Development: Create a Pack · Platform Support · Contributing

Resources: FAQ · Documentation · Community · Roadmap · v1 → v2 Journey · Updates


PAI Overview Video

Watch the full PAI walkthrough | Read: The Real Internet of Things


AI should magnify everyone—not just the top 1%.

The most powerful AI systems are being built inside companies for companies. The richest people and the biggest corporations are getting AI that knows their goals, learns from their history, and gets better at helping them over time.

Everyone deserves that.

PAI exists to democratize access to world-class AI infrastructure. Not a chatbot. Not a generic assistant. A system that helps you become your best self—one that understands your goals, remembers your context, and improves at helping you specifically.

This is open-source. This is free. This is for everyone.


What makes PAI powerful technically: It's built on a universal algorithm (Current → Ideal via verifiable iteration) that works at every scale—from fixing a typo to building a company to figuring out what to do with your life. But the mission comes first: giving everyone access to the kind of AI infrastructure that was previously only available to the privileged few.


Important

🤖 This README Is For Your AI Assistant

Manually reading READMEs is pre-2026 behavior. In 2026+, software gets installed by your AI assistant.

Here's how to use this:

  1. Give this URL to your AI: https://github.com/danielmiessler/PAI
  2. Say: "Look at this system and walk me through installing it. Customize it for me."

The PAI documentation will guide your AI on how best to install it for your specific needs.

Feel free to read on yourself—this README explains the full system. But these instructions are primarily designed for AI consumption.


What is PAI?

PAI (Personal AI Infrastructure) started as a framework for building personalized AI assistants. But in building it, we noticed something.

Every goal—whether it's fixing a bug, writing a book, building a company, or figuring out what to do with your life—follows the same basic structure. There's where you are. There's where you want to be. And there's the process of getting there.

We didn't invent this pattern. Evolution uses it. Science uses it. Every successful human endeavor uses it. We just made it explicit and built tools around it.

PAI is three things:

  • A universal algorithm - Current → Ideal via verifiable iteration, at any scale
  • Personal infrastructure - Skills, memory, and context that make AI actually useful for your life
  • Open-source packs - Battle-tested capabilities anyone can install or contribute

Wait, Hold On—Assume I'm New to All This

You've probably used ChatGPT or Claude. Type a question, get an answer. Simple.

You can think of it as three levels:

The AI Evolution - From chatbots to your personal AI system

Level 1: Chatbots

ChatGPT, Claude, Gemini—you ask something, it answers, and then it forgets everything. Next conversation starts fresh. No memory of you, your preferences, or what you talked about yesterday.

The pattern: Ask → Answer → Forget

Level 2: Agentic Platforms

Tools like Claude Code, Cursor, and Windsurf. The AI can actually do things—write code, browse the web, edit files, run commands.

The pattern: Ask → Use tools → Get result

More capable, but it still doesn't know you—your goals, your preferences, your history.

Level 3: PAI (Personal AI Infrastructure)

Now your AI knows:

  • Your goals — What you're working toward
  • Your preferences — How you like things done
  • Your history — Past decisions and learnings
  • Your context — Who you are and what matters to you

It gets better at helping you over time. It learns from feedback and remembers what you taught it.

The pattern: Observe → Think → Plan → Execute → Verify → Learn → Improve

That's what PAI builds—an AI system that actually knows you.


The Algorithm

At the foundation of PAI is a universal pattern: Current State → Ideal State via verifiable iteration.

This isn't two separate loops—it's one unified algorithm that works at every scale:

  • Fixing a typo — Current: wrong word. Ideal: right word.
  • Building a feature — Current: doesn't exist. Ideal: works, tested, deployed.
  • Building a company — Current: idea. Ideal: profitable business.
  • Human flourishing — Current: wherever you are. Ideal: the best version of your life.

The algorithm has 7 phases:

The Algorithm - 7 Phases

Phase What You Do
OBSERVE Gather context. Understand where you actually are.
THINK Generate ideas. What might work?
PLAN Pick an approach. Sequence the work.
BUILD Define success criteria. How will you know if it worked?
EXECUTE Do the work.
VERIFY Test against your criteria. Did it work?
LEARN Harvest insights. Iterate or complete.

The crucial insight: verifiability is everything. Most people skip VERIFY. They try things, vaguely check if it worked, and move on. The algorithm's power comes from defining success criteria before execution and measuring against them after.

Tip

The Algorithm Pack is now available: pai-algorithm-skill provides the full implementation—effort classification, capability loading, ISC (Ideal State Criteria) management, and visual progress tracking.

⚠️ Early Alpha: This pack is in early alpha and not yet fully integrated with the rest of the PAI system. Expect breaking changes and incomplete features as we iterate.

Where Are You on the Journey?

See the Personal AI Maturity Model (PAIMM)—a 9-tier progression from basic chatbots to a full AI companion.


The 15 PAI Principles

These principles guide how PAI systems are designed and built. Full breakdown →

# Principle Summary
1 The Algorithm Current → Ideal via verifiable iteration. Define success criteria before execution.
2 Clear Thinking First Good prompts come from clear thinking. Clarify the problem before writing the prompt.
3 Scaffolding > Model System architecture matters more than which model you use.
4 Deterministic Infrastructure AI is probabilistic; your infrastructure shouldn't be. Use templates and patterns.
5 Code Before Prompts If you can solve it with a bash script, don't use AI.
6 Spec / Test / Evals First Write specifications and tests before building. Measure if the system works.
7 UNIX Philosophy Do one thing well. Make tools composable. Use text interfaces.
8 ENG / SRE Principles Treat AI infrastructure like production software: version control, automation, monitoring.
9 CLI as Interface Command-line interfaces are faster, more scriptable, and more reliable than GUIs.
10 Goal → Code → CLI → Prompts → Agents The decision hierarchy: clarify goal, then code, then CLI, then prompts, then agents.
11 Self-Updating System The system should modify itself. Encode learnings so you never forget.
12 Skill Management Modular capabilities that route intelligently based on context.
13 History System Everything worth knowing gets captured. History feeds future context.
14 Agent Personalities Different work needs different approaches. Specialized agents with unique voices.
15 Science as Meta-Loop Hypothesis → Experiment → Measure → Iterate. Every decision follows this pattern.

PAI Primitives

While the 15 Principles describe the philosophy of PAI, the Primitives are the architecture—the core systems that make everything work.

Primitive What It Does Key Features
🔄 Learning Loop Self-improvement through feedback Ratings, signals, phase-based learning
🧠 Memory System Persistent context and history Three-tier architecture, per-task traces
Hook System Event-driven automation 8 event types, composable, graceful failure
🔒 Security System Defense-in-depth protection Command validation, repo separation, injection defense
📁 User/System Separation Clean customization boundaries Portable identity, upgrade-safe
🎯 TELOS Deep goal understanding 10 files capturing your mission, beliefs, strategies
⚙️ Customization Adapt everything to your workflow 6 levels from identity to memory

🔄 The Continuous Learning Loop

PAI isn't static. Every interaction feeds a learning loop that makes the system better over time.

User Interaction → Hook Captures → Signal Detection → Learning Directory → System Improvement

How it works:

  1. User gives feedback - Explicit ratings (type "7" or "8 - good work") or implicit sentiment ("this is frustrating")
  2. Hooks capture signals - Ratings, failures, loopbacks, and patterns are written to MEMORY/Signals/
  3. Low ratings trigger learning - Scores below 6 auto-capture to MEMORY/Learning/ for analysis
  4. System improves - Learnings are organized by algorithm phase for targeted retrieval

This isn't just logging—it's a feedback mechanism that identifies what's working and what isn't.

🧠 Memory System

The Memory System is PAI's brain—what happened, what we learned, what we're working on.

Location: $PAI_DIR/MEMORY/

Three-Tier Architecture:

Tier Temperature Purpose Location
CAPTURE Hot Active work with real-time traces Work/[Task-Name]/
SYNTHESIS Warm Learnings organized by algorithm phase Learning/{OBSERVE,THINK,PLAN,BUILD,EXECUTE,VERIFY}/
APPLICATION Cold Immutable historical archive History/

Directory Structure:

MEMORY/
├── History/           # All historical recordings (immutable archive)
│   ├── research/      # Research session outputs
│   ├── sessions/      # Session summaries (auto-captured)
│   ├── learnings/     # Learning moments
│   ├── decisions/     # Architectural decisions
│   └── ...
├── Learning/          # Phase-based curated learnings
│   ├── OBSERVE/       # Learnings about gathering context
│   ├── THINK/         # Learnings about hypothesis generation
│   ├── PLAN/          # Learnings about execution planning
│   ├── BUILD/         # Learnings about success criteria
│   ├── EXECUTE/       # Learnings about implementation
│   ├── VERIFY/        # Learnings about verification
│   └── ALGORITHM/     # Meta-learnings about the algorithm itself
├── State/             # Real-time operational state
│   ├── algorithm-stats.json
│   ├── algorithm-streak.json
│   └── active-work.json
├── Signals/           # Pattern detection and anomalies
│   ├── failures.jsonl
│   ├── loopbacks.jsonl
│   ├── patterns.jsonl
│   └── ratings.jsonl
└── Work/              # Per-task memory (active work items)
    └── [Task-Name_TIMESTAMP]/

Key Insight: VERIFY failures are the richest source of improvement. When verification fails, it traces back to a weakness in an earlier phase—that weakness gets captured in LEARN.

⚡ Hook System

Hooks are event-driven automation that make PAI "alive"—they respond to what's happening and take action.

Hook Types:

Event When It Fires Common Uses
SessionStart Opening a new session Load context, set up environment
SessionEnd Session closing Capture summary, archive learnings
UserPromptSubmit User sends a message Update tab title, detect sentiment
Stop AI completes response Voice notification, capture completion
SubagentStop Spawned agent completes Capture agent output
PreToolUse Before tool execution Security validation, logging
PostToolUse After tool execution Capture results, observability
PreCompact Before context compaction Preserve critical state

Design Principles:

  • Graceful failure - Hooks always exit 0; failures log but don't block
  • Composable - Multiple hooks can respond to the same event
  • Fast - Hooks run synchronously; keep them lightweight

Example Flow:

User types message
  → UserPromptSubmit hook updates tab title
  → AI generates response
  → Stop hook extracts completion message
  → Stop hook sends to voice server
  → Stop hook captures to history

🔒 Security System

Security is layered, not bolted on. PAI implements defense-in-depth across multiple layers.

Key Protections:

  • Command validation - Dangerous commands (rm -rf, sudo, etc.) blocked before execution
  • Repository separation - Private (Kai) and public (PAI) repos are completely isolated
  • Prompt injection defense - External content is read-only; commands only come from the principal
  • Secret management - All API keys in $PAI_DIR/.env, never in code

The Two-Repository Rule:

~/.claude/ (PRIVATE)          ~/Projects/PAI/ (PUBLIC)
├── Contains secrets          ├── Example code only
├── Personal data             ├── No personal data
├── Your actual system        ├── Community template
└── NEVER PUBLIC              └── Safe to share

📁 User/System Separation

PAI cleanly separates what's yours from what's system.

$PAI_DIR/skills/CORE/
├── USER/              # Your customizations
│   ├── CONTACTS.md    # Your contacts
│   ├── TELOS/         # Your goals (see below)
│   ├── TECHSTACK.md   # Your preferences
│   └── SECURITY.md    # Your security rules
└── SYSTEM/            # PAI infrastructure
    ├── PAISYSTEMARCHITECTURE.md
    ├── MEMORYSYSTEM.md
    ├── THEHOOKSYSTEM.md
    └── ...

Why This Matters:

  • Upgrades don't clobber customizations - System files update; your files persist
  • Clear ownership - You know what's yours to modify
  • Portable identity - Move USER/ to a new system; your preferences follow

🎯 Deep Goal Capture (TELOS)

TELOS is PAI's framework for understanding you—your goals, beliefs, strategies, and what you're working toward.

The TELOS Files:

File Purpose
MISSION.md Your life mission and purpose
GOALS.md Current goals across life areas
PROJECTS.md Active projects with status
BELIEFS.md Core beliefs that guide decisions
MODELS.md Mental models you use
STRATEGIES.md Strategies you employ
NARRATIVES.md Stories you tell about yourself
LEARNED.md Key lessons learned
CHALLENGES.md Current challenges
IDEAS.md Ideas worth capturing

Why TELOS Exists:

Generic AI assistants don't know what you're trying to accomplish. They treat every request as isolated. TELOS gives your AI the context to:

  • Prioritize based on your actual goals
  • Suggest based on your strategies
  • Warn when something conflicts with your beliefs
  • Connect today's task to your bigger picture

⚙️ Granular Customization

PAI doesn't force you into a structure. Everything is customizable at the level you choose.

Customization Levels:

Level What You Change Example
Identity Your AI's name, voice, personality DA="Kai", voice settings
Preferences Tech stack, tool choices TypeScript over Python, bun over npm
Workflows How skills execute Custom research flow, different commit style
Skills What capabilities exist Add new skills, modify existing ones
Hooks How events are handled Custom logging, different notifications
Memory What gets captured and how Retention rules, archive frequency

The Principle: Start with defaults. Customize when you have a reason. PAI works out of the box but adapts to how you work.


Packs & Bundles

PAI capabilities are distributed as Packs—self-contained, AI-installable modules that add specific capabilities to your system.

  • Packs are individual capabilities (e.g., History System, Voice Notifications, Browser Automation)
  • Bundles are curated collections of packs that work together (e.g., the PAI Bundle)

Each pack includes everything needed: code, workflows, installation instructions, and verification tests. Your AI reads the pack and installs it into your system—no manual copying required.

Browse Available Packs → · Browse Bundles →


How AI Installation Works

See 🤖 This README Is For Your AI Assistant for the quick start. This section explains the technical details.

Your system is unique—existing skills, different directory structures, conflicting configurations, missing prerequisites. A static install script can't handle this. But your AI can:

  1. Analyze your current state — What's already installed? What conflicts exist?
  2. Ask smart questions — Only ask about things that matter for YOUR setup
  3. Adapt the installation — Different paths, different configurations, different choices
  4. Verify the results — Confirm everything works before declaring success

The Wizard Pattern

Every pack's INSTALL.md follows a wizard-style flow:

Phase What Happens AI Tool Used
1. System Analysis Detect current state, find conflicts, check prerequisites Bash, Read
2. User Questions Ask only relevant questions based on analysis AskUserQuestion
3. Backup Create timestamped backups if replacing existing content Bash
4. Installation Execute installation with live progress tracking TodoWrite, Bash, Write
5. Verification Run all checks from VERIFY.md, confirm success Bash, VERIFY.md

How to Install Any Pack

Give the pack directory to your AI and say:

Install this pack into my system using PAI_DIR="~/.claude"

Your AI will:

  • Read README.md for context on what the pack does
  • Follow INSTALL.md with the wizard flow
  • Copy files from src/ to appropriate locations
  • Run VERIFY.md checks to confirm success
  • Report what was installed and how to use it

No manual command copying. No guessing about your system state. Dynamic installation that adapts to you.


How PAI Works

This section explains the technical architecture, installation process, and runtime mechanics of the Personal AI Infrastructure (PAI) system.

1. High-Level Architecture

PAI is not a standalone application but a configuration and automation layer that sits on top of Claude Code (Anthropic's CLI agent). It transforms a generic AI agent into a personalized system with persistent memory, security controls, and defined skills.

The architecture consists of three main layers:

  1. The Engine (Claude Code): The underlying AI agent that executes commands and processes prompts.
  2. The Middleware (Hooks): A system of event listeners that intercept Claude Code's operations (like tool use, session start) to enforce security, inject context, and log activity.
  3. The Content (Packs): Modular bundles of markdown files and scripts that define "Skills" (workflows), "Tools" (executable code), and "Identity" (system prompts).

PAI Architecture

2. The Hook System (The "Magic")

The core mechanism that makes PAI work is the Hook System. Claude Code has a native capability to run scripts when certain events occur. PAI leverages this to inject its logic.

How Hooks Work:

  1. Configuration: Hooks are registered in ~/.claude/settings.json. This file maps events (like PreToolUse) to specific scripts.
  2. Events:
    • SessionStart: Fires when you open Claude Code. PAI uses this to load your "CORE" skill and context.
    • PreToolUse: Fires before the AI runs a command (e.g., bash, edit). PAI uses this for Security Validation (blocking rm -rf, etc.).
    • PostToolUse: Fires after a command. Used for logging and observability.
    • UserPromptSubmit: Fires when you type a message. Used to update terminal tab titles.
  3. Execution: When an event fires, Claude Code runs the corresponding TypeScript script (using bun) located in ~/.claude/hooks/.
  4. Communication: The script receives event data via stdin (JSON) and can control the outcome (e.g., allow or block a command) via exit codes or stdout.

3. Installation Process

The installation is a two-phase process: Bootstrapping (Manual) and Pack Installation (AI-Driven).

Phase 1: Bootstrapping (The install.ts script) The user runs bun run Bundles/Official/install.ts. This script does not install the full system. Instead, it:

  1. Creates Directory Structure: Sets up ~/.claude/ (or $PAI_DIR) with folders for skills, hooks, history, etc.
  2. Generates Config Files: Creates SKILL.md, Contacts.md, and CoreStack.md with user preferences (name, timezone).
  3. Sets Environment Variables: Updates .zshrc or .bashrc with DA (Assistant Name), PAI_DIR, etc.
  4. Updates settings.json: Injects environment variables into Claude Code's settings.

Crucially, this phase does not install the hooks or skills. It prepares the environment for the AI to do it.

Phase 2: Pack Installation (AI-Driven) The user is instructed to "give each pack file to your AI". This is where the actual installation happens.

  1. User Action: The user pastes the content of a pack file (e.g., Packs/pai-hook-system.md) into Claude Code.
  2. AI Execution: The pack file contains natural language instructions and code blocks. The AI reads these instructions and:
    • Writes Files: Creates the TypeScript hook files (e.g., hooks/security-validator.ts) and skill definitions.
    • Configures System: Updates settings.json to register the new hooks.
    • Verifies: Runs verification commands to ensure the pack is working.

This "Inception-style" installation (using the AI to build the AI's infrastructure) ensures that the system is self-documenting and the AI "knows" about its own components.

4. Runtime Flow

Here is what happens when you use PAI:

sequenceDiagram
    participant User
    participant Claude as Claude Code
    participant Hooks
    participant Skills
    participant Memory as MEMORY

    User->>Claude: Run `claude`
    Claude->>Hooks: SessionStart
    Hooks->>Skills: Load CORE/SKILL.md
    Skills-->>Claude: Context injected

    User->>Claude: "Create a new blog post"
    Claude->>Skills: Route to CreateContent
    Claude->>Hooks: PreToolUse (touch blog.md)
    Hooks-->>Claude: ✓ Safe (exit 0)
    Claude->>Claude: Execute command

    Claude->>Hooks: Stop
    Hooks->>Memory: Capture session
    Claude-->>User: Task complete
Loading
  1. Start: You run claude.
  2. Initialization (SessionStart): Hooks load your CORE skill and context. Now the AI knows who it is and what skills it has.
  3. User Interaction: You ask "Create a new blog post".
  4. Routing: The AI recognizes this matches a skill (e.g., CreateContent) and loads the specific workflow.
  5. Execution (PreToolUse): Before running commands, hooks validate safety. Safe commands proceed; unsafe ones are blocked.
  6. Completion: The AI finishes and updates memory via the MEMORY system.

5. Key Components

  • pai-hook-system: The engine room. Provides the event bus and security layer.
  • pai-core-install: The brain. Defines the "CORE" skill, identity, routing logic, and MEMORY system (session capture, learnings, signals).
  • pai-voice-system: (Optional) Adds voice capabilities via ElevenLabs.

📦 Available PAI Packs

Features (Architectural Systems)

Pack Version Description
pai-core-install 1.4.0 Core skills, identity, MEMORY system, and response format
pai-hook-system 1.0.0 Event-driven automation and security validation
pai-voice-system 1.0.1 Voice notifications with ElevenLabs TTS and prosody enhancement
pai-observability-server 1.0.0 Real-time agent monitoring dashboard with live charts

Skills (Action-Oriented Capabilities)

Pack Version Description
pai-agents-skill 1.1.1 Dynamic agent composition with personality mapping and parallel orchestration
pai-algorithm-skill 0.5.0 The Algorithm implementation - ISC management, effort classification ⚠️ Early Alpha
pai-art-skill 1.1.0 Visual content generation with multi-reference image support
pai-browser-skill 1.2.0 Browser automation with Playwright for testing and verification
pai-prompting-skill 1.0.0 Meta-prompting system with templates, standards, and dynamic generation
pai-upgrades-skill 1.0.0 Track and manage PAI system upgrade opportunities

Note

The standalone History System pack has been retired. History/context-tracking is now integrated into pai-core-install as the MEMORY System.

Submit your own pack →


📦 Available Bundles

Bundles are curated collections of packs designed to work together. Instead of installing packs one-by-one, install a bundle to get a complete, tested experience.

Bundle Description Packs Tier
PAI Bundle The official PAI bundle - complete personal AI infrastructure extracted from Daniel Miessler's production system 5 Complete

Why Bundles?

  • Curated combinations - Tested packs that work well together
  • Proper installation order - Dependencies handled correctly
  • Emergent capabilities - The whole is greater than the sum of parts
  • Complete experience - Everything needed for a specific goal
  • Interactive wizard - Guided setup with conflict detection

The PAI Bundle is the flagship bundle. Installing all its packs recreates the PAI v1.0 "mirrored system" experience - but through modular, maintainable packs instead of a monolithic copy.

Quick install:

# Clone the repo and run the interactive wizard
git clone https://github.com/danielmiessler/PAI.git
cd PAI/Bundles/Official && bun run install.ts

Learn more about bundles →


🚀 Quick Start

Note

FOR AI AGENTS: The entire PAI system is designed to be used by AI. Evaluate the system, then ask your principal which Bundles or Packs they'd like to install—give them options based on their needs. You should be able to read any Bundle or Pack file and guide your principal on whether they want to install it.

Option 1: Install the Complete PAI Bundle (Recommended)

The fastest way to get started is with the interactive bundle wizard:

# Clone the repo
git clone https://github.com/danielmiessler/PAI.git
cd PAI/Bundles/Official

# Run the interactive wizard
bun run install.ts

The wizard will:

  • Ask for your preferences (AI name, install location, timezone)
  • Detect any existing installations and offer to merge or replace
  • Create the required directory structure
  • Configure environment variables
  • Guide you through installing each pack in order

Option 2: AI-Assisted Pack Installation

Install individual packs by giving them to your AI:

  1. Browse packs - Find a pack you want in Packs/
  2. Give it to your AI - Provide the entire pack markdown file
  3. Ask your AI to install it:
Install this pack into my system. Use PAI_DIR="~/.config/pai"
and DA="MyAI". Set up the hooks, save the code, and verify it works.

Your AI will:

  • Check for required dependencies
  • Save code to appropriate directories
  • Set up routing/hooks (if applicable)
  • Validate the installation
  • Run a test to ensure it works

Option 3: Manual Installation

Each pack includes detailed manual installation instructions. Open the pack file and follow the "Installation → Manual" section.

Option 4: Browse and Cherry-Pick

Packs are self-contained markdown files. You can:

  • Read the code directly in the pack
  • Copy specific functions or workflows
  • Adapt the approach to your own system
  • Use it as reference documentation

No forced structure. No mandatory setup. Take what's useful, leave the rest.


📂 Understanding PAI_DIR

The PAI_DIR environment variable is the single source of truth for where your PAI installation lives.

What is PAI_DIR?

PAI_DIR points to the directory where your personal AI infrastructure is installed - this is where skills, hooks, history, and configuration files live.

Two Different Things

Concept Path Purpose
PAI Repository Where you cloned git clone https://github.com/danielmiessler/PAI.git Source code, packs, templates - read-only reference
PAI Installation (PAI_DIR) ~/.claude (default) or your custom location Your active installation - skills, hooks, history, config

The repository is like a cookbook. Your installation is your actual kitchen.

Default Behavior

If PAI_DIR is not set, PAI tools and packs default to ~/.claude:

  • This is the standard Claude Code configuration directory
  • Works seamlessly with Claude Code out of the box
  • Recommended for most users

When to Use a Custom PAI_DIR

Set a custom PAI_DIR if you:

  • Use a different AI coding assistant (Cursor, Windsurf, OpenCode)
  • Want to keep PAI separate from Claude Code's config
  • Are testing or developing packs
  • Have multiple PAI installations

Setting PAI_DIR

In your shell profile (~/.zshrc or ~/.bashrc):

export PAI_DIR="$HOME/.claude"  # Default - Claude Code location
# OR
export PAI_DIR="$HOME/.config/pai"  # Custom location

How Tools Resolve PAI_DIR

PAI tools use this resolution order:

  1. process.env.PAI_DIR - Explicit setting (highest priority)
  2. process.env.PAI_HOME - Legacy/alternate variable
  3. ~/.claude - Default fallback

This means: if you set PAI_DIR, it takes precedence. If not, it defaults to Claude Code's standard location.


🔐 Authentication Setup

All API keys live in ONE place: $PAI_DIR/.env

This is a core principle of PAI: no keys stored anywhere else in the system. Every pack, every tool, every workflow reads from this single file.

Setup

# 1. Copy the example file to your PAI directory
cp .env.example $PAI_DIR/.env

# 2. Edit and add your API keys
nano $PAI_DIR/.env

# 3. Restart Claude Code to load the new environment

What Goes in .env

Core variables:

  • DA - Your AI assistant's name
  • TIME_ZONE - Your timezone

Pack-specific keys: Each pack documents its required API keys in its installation section. Add them to .env as you install packs.

Security Rules

  1. NEVER commit .env files to git - The .gitignore already excludes them
  2. NEVER store API keys in pack files, configs, or code - Always use environment variables
  3. ALL authentication flows through $PAI_DIR/.env - One file, one location, no exceptions

See .env.example for the complete template with documentation.


📖 How PAI Packs Work

PAI offers two types of packs, each with its own structure and purpose:

Pack Type 1: Skills

Skills are action-oriented capabilities that your AI can invoke - things like generating visual content, conducting research, or processing data.

Examples: Art (visual content generation), Research (multi-source investigation), OSINT (intelligence gathering)

Structure:

  1. 🤖 Assistant Install Prompt - Step-by-step instructions for AI to autonomously install
  2. Pack Metadata - Version, dependencies, API keys, platform support
  3. The Problem - What's broken/missing?
  4. The Solution - How this skill fixes it
  5. Quick Start - Get running in 60 seconds
  6. Pack Contents - Workflows, tools, context files (complete source code)
  7. Examples - Real usage scenarios
  8. Installation - AI-assisted + manual steps
  9. Testing - Smoke tests and validation
  10. Troubleshooting - Common issues and fixes
  11. Credits - Attribution for ideas, influences, collaborators
  12. Resources - Additional reading, related projects, external docs

Pack Type 2: Features

Features are architectural patterns and systems - infrastructure pieces like custom history systems, skill routing, agent orchestration, or prompting frameworks.

Examples: History System (automatic context-tracking), Skill System (routing and management), Agent Factory (custom agent creation), Prompting System (meta-prompting and templates)

Structure:

  1. 🤖 Assistant Install Prompt - Step-by-step instructions for AI to autonomously install
  2. Pack Metadata - Version, dependencies, platform support
  3. The Problem - What architectural challenge exists?
  4. The Solution - The design pattern and approach
  5. Implementation - Complete code, configuration files, integration guides
  6. Examples - Real-world usage patterns
  7. Installation - AI-assisted + manual steps
  8. Testing - Validation procedures
  9. Troubleshooting - Common integration issues
  10. Credits - Attribution for architectural ideas, influences
  11. Resources - Additional reading, similar systems, theoretical background

Universal Elements

All packs include:

pack:
  name: PackName
  version: 1.0.0
  category: visual-content | infrastructure | research | automation
  type: skill | feature
  author: Contributor Name
  license: MIT
  requires:
    - Other-Pack >= 1.0.0 (optional dependencies)
  platforms: [macos, linux, windows]
  dependencies:
    tools: [bun, ImageMagick]
    api_keys: [REPLICATE_API_TOKEN]

🤖 Assistant Install Prompt - Every pack starts with instructions for AI assistants to autonomously install it. Your AI reads the pack, understands what it does, verifies dependencies, sets up the code, and validates it works - all without manual intervention.

Why Single Files?

Portability - One file contains everything. Email it, share it, version control it.

AI-Friendly - Your AI can read the entire context at once. No navigation, no missing pieces.

No Dependencies - Packs are self-contained. They may call external tools, but the pack itself is complete.

Easy Review - See exactly what you're installing. No hidden files, no surprises.

Version Control - Simple to track changes, fork, and merge improvements.


🛠️ For Pack Developers

Creating a PAI Pack

1. Get the pack template:

curl -O https://raw.githubusercontent.com/danielmiessler/PAI/main/Tools/PAIPackTemplate.md

2. Fill in each section:

  • Assistant Install Prompt - Instructions for AI to install autonomously
  • Problem statement - What's broken or missing?
  • Solution - How your pack fixes it
  • Implementation/Contents - All code (embedded in markdown code blocks)
  • Examples - Real usage scenarios
  • Installation steps - Both AI-assisted and manual
  • Testing procedures - Smoke tests and validation
  • Credits - Attribution for ideas and influences
  • Resources - Additional reading and related projects

3. Validate it:

Test with your own AI:

Here's my pack. Install it into a fresh system and verify it works.

4. Submit a PR:

git checkout -b add-pack-name
cp MyPack.md Packs/
git add Packs/MyPack.md
git commit -m "Add MyPack - one-line description"
git push origin add-pack-name

Open a PR with:

  • Pack description
  • What problem it solves
  • Testing you've done
  • Screenshots/examples (if applicable)

Pack Quality Standards

Must have:

  • ✅ Clear problem statement
  • ✅ Complete working code (tested)
  • ✅ Real examples (not placeholders)
  • ✅ Both AI and manual installation instructions
  • ✅ Troubleshooting section
  • ✅ No hardcoded personal data

Nice to have:

  • Screenshots of output
  • Video demo
  • Multiple examples for different use cases
  • Integration with other packs

🏗️ Platform Compatibility

PAI packs are designed to be platform-agnostic:

Platform Status Notes
Claude Code ✅ Full support Native integration, all features work
OpenCode ✅ Compatible Skills/hooks may need adaptation
Custom systems ✅ Compatible Extract code, adapt to your structure
Gemini Code / Codex 🔄 Testing Should work with minor tweaks
Manual use ✅ Always works Packs are documentation + code

The code itself is platform-independent (TypeScript, Python, Bash). Integration points (skills, hooks) may vary by platform.


💡 Why Packs?

Text is the interface. Everything your AI needs to implement a capability should be in one readable file.

Composability over monoliths. Mix and match packs. Build your own stack.

AI-first design. Optimized for AI agents to read, understand, and implement - not just humans.

Open contribution. Anyone can submit a pack. The best ideas win.

No vendor lock-in. Packs describe how to solve a problem, not just "here's the code for our platform."


🤝 Contributing

Submit a Pack

We welcome packs that solve real problems:

  1. Fork the repository
  2. Create your pack - Follow PAIPackTemplate.md
  3. Test it thoroughly - Install in a fresh system with AI assistance
  4. Submit a PR - Include examples and testing evidence

Pack Review Process

Submitted packs are reviewed for:

  • Completeness - All required sections present
  • Code quality - Works as described, no obvious bugs
  • Security - No hardcoded secrets, follows best practices
  • Usefulness - Solves a real problem for users

Review timeline: Most packs reviewed within 7 days.

Pack Maintenance

Authors maintain their packs. When you submit a pack, you're committing to:

  • Respond to issues about your pack
  • Fix bugs that are reported
  • Consider feature requests
  • Update for breaking changes in dependencies

If a pack becomes unmaintained, the community can fork and maintain a new version.


📚 Documentation

Document Description
PACKS.md Complete pack system documentation
Bundles/ Bundle system documentation and available bundles
SECURITY.md Security policies and best practices

🎯 Roadmap

Planned capabilities for PAI:

Feature Description
Local Model Support Run PAI with local models (Ollama, llama.cpp, etc.) for privacy and cost control
Granular Model Routing Route different tasks to different models based on complexity and requirements
Remote Access Access your PAI from anywhere—mobile, web, other devices
Outbound Phone Calling Voice capabilities for outbound calls and phone-based interactions
External Notifications Robust notification system for Email, Discord, Telegram, Slack, and more

🌐 Community

GitHub Discussions: Join the conversation

UL Community Discord: PAI is discussed in the Unsupervised Learning community along with other AI projects

Twitter/X: @danielmiessler

Blog: danielmiessler.com

Recognition

Top pack contributors (packs submitted/maintained):

  • (List will be populated as packs are submitted)

Special thanks:

  • All early PAI users who provided feedback
  • The Claude Code team for building an incredible platform

❓ FAQ

Isn't Claude Code and other agentic systems already pretty good? What makes this an upgrade over them?

PAI isn't a replacement for Claude Code—it's what you build on top of it. Claude Code (and systems like Cursor, Windsurf, OpenCode) gives you an AI that can read files, write code, and execute commands. But they're generic. They don't know your goals, your preferred workflows, your history, or your specific context.

PAI provides the scaffolding to make that generic AI yours:

  • Persistent memory — Your AI remembers past sessions, decisions, and learnings
  • Custom skills — Specialized capabilities for the things you do most (research, content creation, security analysis, etc.)
  • Your context — Goals, contacts, preferences, definitions—all available to your AI without re-explaining
  • Intelligent routing — Say "research this" and the right workflow triggers automatically
  • Self-improvement — The system can modify itself based on what it learns

Think of it this way: Claude Code is the engine. PAI is everything else that makes it your car—the custom seat position, the saved radio stations, the GPS with your home address, the toolbox in the trunk.

Do I need to install everything?

No—and that's the point. The mistake of PAI v1 (and many other agentic systems) was trying to install everything all at once in an all-or-nothing fashion. That creates fragile systems where one broken piece takes down the whole thing.

PAI v2 is modular by design:

  • Packs are independent — Install one, install ten, install none. Each pack is self-contained.
  • Start small — Begin with the Hook System, add History when you want persistence, add Skills when you need routing
  • No dependencies on the whole — Each pack declares its dependencies explicitly. You install exactly what you need.
  • Incremental adoption — Use PAI alongside your existing setup. Migrate at your own pace.

The best way to start: pick ONE pack that solves a problem you have today. Install it. Use it. Then decide if you want more.

What's the difference between PAI and Anthropic's plugin system?

Anthropic's plugin system (Skills, slash commands, MCP servers) provides discrete functionality—individual tools your AI can use. It's powerful, and you're free to use plugins as part of PAI as well.

The difference is scope and integration:

Anthropic's plugins = Individual pieces of functionality that don't understand overall context—they don't know how they work with other pieces of functionality, and most importantly, they don't integrate with your actual system and your actual goals.

PAI = A complete system where everything understands the context—your goals, your workflows, how pieces work together, and what you're actually trying to accomplish.

PAI is:

  • An implemented, full-setup system — Not just tools, but a complete personal AI infrastructure
  • Dynamically adaptive — Adjusts to your existing environment and workflows
  • Context-aware — Understands what you're trying to accomplish in your life and work
  • Customized to you — Picks and chooses functionality from different sources
  • Self-managing — Your AI installs, configures, and maintains the system itself

The plugin system offers building blocks. PAI offers a blueprint for a mansion—plus the AI architect to build it.

Is PAI only for Claude Code?

No. PAI packs are designed to be platform-agnostic. While the examples use Claude Code (because that's what the author uses), the packs work with:

  • Claude Code — Full native support
  • OpenCode — Compatible with minor adaptations
  • Cursor / Windsurf — Works with configuration adjustments
  • Gemini Code / GPT-Codex — Should work with tweaks (community testing welcome)
  • Custom systems — Extract the code and concepts, adapt to your setup

The code is TypeScript, Python, and Bash. The concepts are universal. The integration points vary by platform, but the core value transfers.

Do I need to install everything?

No. That was the mistake of PAI v1.x—trying to install everything at once.

PAI v2.0 is modular by design:

  • Start with one pack — History System is a good first choice
  • Add more as needed — Each pack is independent
  • Use the PAI Bundle if you want the full experience (but even that installs one pack at a time)
  • Cherry-pick — Read a pack, extract the ideas, adapt them yourself

There's no "all or nothing." Take what's useful, leave the rest.

How do I contribute a pack?

  1. Solve a real problem — Packs should come from actual use, not theoretical ideas
  2. Use the template — Download PAIPackTemplate.md
  3. Test it — Have your AI install it in a fresh environment
  4. Submit a PR — Include examples and evidence it works

See Contributing for full details.

How is this different from fabric?

Fabric is a collection of AI prompts (patterns) for specific tasks—extract wisdom, analyze arguments, summarize content. It's focused on what to ask AI.

PAI is infrastructure for how your AI operates—memory, skills, routing, context, self-improvement. They're complementary:

  • Fabric = A library of expert prompts
  • PAI = The system that knows when to use which prompt, remembers your preferences, and learns from results

Many PAI users integrate Fabric patterns into their skills. They work great together.

What if I break something?

The modular design makes recovery easy:

  • Packs are isolated — Breaking one doesn't affect others
  • History is preserved — Your AI's memory survives mistakes
  • Git-backed — Version control everything, roll back when needed
  • AI can fix it — Your AI helped build it, it can help repair it

Start small, experiment, iterate. The system is designed for safe exploration.


📜 License

MIT License - see LICENSE for details.

TL;DR: Do whatever you want with this. Build on it, sell it, modify it. Just don't blame us if something breaks. Attribution appreciated but not required.


🎁 Support PAI

PAI is free and open-source forever.

If you find it valuable:

  • Star the repo - Helps others discover it
  • 💜 Sponsor on GitHub - Help fund development
  • 📢 Share your packs - The more packs, the better PAI gets
  • 💬 Engage in discussions - Help answer questions, share ideas
  • 🐛 Report issues - Make PAI better for everyone
  • ✍️ Write about it - Blog posts, videos, tutorials

Premium support coming soon for organizations.


📚 Related Reading


The Journey: PAI v1.x → v2.0

PAI v1.x attempted to mirror my entire personal AI system (Kai) as an installable template. The idea was simple: "Here's everything I built - clone it and customize."

The problem: It didn't work. The system was a Jenga tower of interconnected dependencies. Change one piece, and three others broke. Users couldn't easily adopt parts without understanding the whole. Updates were a nightmare because everything was coupled.

PAI v2.0 takes a fundamentally different approach: modular packs.

Instead of "here's my whole system," it's "here are battle-tested capabilities you can install independently." Each pack is:

  • Self-contained - Works without understanding the rest of the system
  • Independently installable - Add what you need, skip what you don't
  • Platform-agnostic - Works with Claude Code, OpenCode, or custom systems
  • AI-installable - Your AI can read the pack and set it up for you

The packs are extracted from Kai—real capabilities that have been running in production. They're not theoretical examples. They're the actual tools and systems I use daily, packaged for others to adopt.


Deep Dive: How PAI Packs Work

PAI Packs are modular upgrade packages for AI agent systems. Think of them like learning kung-fu in The Matrix—each pack is a complete, tested capability that you can download into your system.

Each pack provides everything your AI needs to implement a specific capability:

  • The problem being solved
  • The solution and how it works
  • All code (tools, CLIs, scripts)
  • Workflows (step-by-step processes)
  • Context files (guidelines, aesthetics, specifications)
  • Examples and usage patterns
  • Installation instructions (for both AI and manual)
  • Testing procedures
  • Troubleshooting guides

The key insight: Give your AI the complete context it needs, and it can integrate the pack into your system, whether that's Claude Code, OpenCode, Gemini Code, GPT-Codex, or a homebrew setup.


📜 Update History

v2.1.1 (2026-01-09) — MEMORY System Migration

History System Retired

  • Removed standalone pai-history-system pack
  • History/context-tracking functionality is now part of pai-core-install as the MEMORY System

Why This Change?

  • The MEMORY System in pai-core-install is more comprehensive:
    • Three-tier architecture (CAPTURE → SYNTHESIS → APPLICATION)
    • Phase-based learnings organized by algorithm phase (OBSERVE, THINK, PLAN, BUILD, EXECUTE, VERIFY)
    • Real-time signals tracking (ratings, failures, loopbacks, patterns)
    • Per-task work directories with full traces
  • Having history as a separate pack created confusion and redundancy
  • Core installation now provides complete memory/history functionality out of the box

Migration Note If you previously installed pai-history-system, your data is preserved. The new MEMORY System in pai-core-install uses the same $PAI_DIR/MEMORY/ directory structure.

v2.1.0 (2025-12-31) — Directory-Based Pack Structure

Major Pack Format Change

  • All 8 packs migrated from single markdown files to directory-based structure
  • New pack format: README.md, INSTALL.md, VERIFY.md, and src/ directory
  • Source code now lives in real files (.ts, .yaml, .hbs) instead of embedded in markdown

Why This Matters

  • Solves token limit issues (single files exceeded 28k tokens vs 25k limit)
  • Real code files can be linted, tested, and validated
  • AI agents copy actual files instead of extracting from markdown blocks
  • Eliminates "helpful simplification" where AI would reduce code complexity

Updated Documentation

  • Packs/README.md updated with v2.0 structure documentation
  • Bundles/README.md updated with new pack format description
  • Bundles/Official/README.md bumped to v2.0.0 with directory references

What Changed Per Pack Each pack directory now contains:

pack-name/
├── README.md      # Overview, architecture, what it solves
├── INSTALL.md     # Step-by-step installation instructions
├── VERIFY.md      # Mandatory verification checklist
└── src/           # Actual source code files
v2.0.1 (2025-12-30) — Pack Expansion & Polish

New Packs Released

  • Kai Prompting Skill (v1.0.0) - Meta-prompting system with templates, standards, and dynamic prompt generation
  • Kai Agents Skill (v1.0.0) - Dynamic agent composition with personality mapping and parallel orchestration

Pack Updates

  • Kai Voice System - New pack icon with refined design (cache-busted for immediate updates)
  • Kai Art Pack (v1.1.0) - Multi-reference image support for complex visual compositions

Documentation & Quality

  • Standardized authentication to single $PAI_DIR/.env location across all packs
  • Enhanced wizard clarity for installation flows (addressing #259, #260, #261)
  • Safer verification patterns for security hooks
  • Consistency pass across all pack documentation
  • Updated pack manifests with accurate dependencies

Infrastructure

  • Reorganized Tools directory with AI usage guide
  • Added Tools README with icons and descriptions
  • Moved templates and diagnostic tools to centralized location

What's New Since v2.0.0?

v2.0.0 launched the Packs system. v2.0.1 adds:

  • 8 feature packs now available with improved documentation
  • Better installation experience with clearer wizards
  • Unified authentication pattern (no more scattered .env files)
  • Professional pack icons for visual consistency
v2.0.0 (2025-12-28) — PAI Packs System Launch

Major Architecture Shift

  • Transitioned from "mirrored system" approach to modular PAI Packs
  • Packs are self-contained, AI-installable capability bundles
  • Platform-agnostic design: works with Claude Code, OpenCode, Gemini Code, GPT-Codex, or custom systems

First Pack Released

  • PAI History System (v1.0.0) - Automatic context-tracking for entire AI infrastructure
  • Complete implementation: 4 hooks, 3 library files, settings.json configuration

New Documentation

  • Tools/PAIPackTemplate.md - Full pack template specification
  • PACKS.md - Complete pack system documentation
  • Updated README with 14 Founding Principles and full pack installation guide

Why the Change?

  • v1.x tried to mirror the entire Kai system - too fragile, too many interdependencies
  • v2.0 extracts battle-tested features as independent, installable modules
  • Each pack is like learning kung-fu in The Matrix - a complete capability download
v0.9.1 (2025-12-01) — Patch Release

Fixes

  • PAI_DIR now auto-configures in settings.json during setup
  • Platform-agnostic paths work across macOS, Linux, Windows
  • Fixed timezone configuration in hooks
v0.9.0 (2025-11-28) — Observability & Identity

Observability Dashboard

  • Real-time agent monitoring with live charts
  • Bun + Vue architecture for performance
  • Multiple themes (Tokyo Night, Nord, Catppuccin, etc.)
  • Security obfuscation for sensitive data

Genericized Agent Identity

  • All agent references now use process.env.DA || 'main'
  • No more hardcoded names — your DA name flows through the entire system
  • Observability dashboard shows your configured identity

Platform-Agnostic Configuration

  • Clear separation: settings.json for identity/paths, .env for API keys
  • DA (Digital Assistant name) — your AI's identity
  • PAI_DIR — root directory for all configuration
  • TIME_ZONE — configurable timezone for timestamps

Skill System Improvements

  • Canonical TitleCase file naming throughout
  • Standardized skill-workflow-notification script for dashboard detection
  • All paths use ${PAI_DIR}/ for location-agnostic installation
v0.8.0 (2025-11-25) — Research & Documentation

Research Skill

  • Comprehensive research skill with 10 specialized workflows
  • Multi-source research with parallel agent execution
  • Fabric pattern integration (242+ AI patterns)

Infrastructure

  • Path standardization using ${PAI_DIR}/ throughout
  • PAI_CONTRACT.md defining core guarantees
  • Self-test validation system for health checks
  • Protection system for PAI-specific files
v0.7.0 (2025-11-20) — Protection & Clarity

PAI Path Resolution System (#112)

  • Centralized pai-paths.ts library — single source of truth
  • Smart detection with fallback to ~/.claude
  • Updated 7 hooks to use centralized paths

PAI vs Kai Clarity (#113)

  • PAI_CONTRACT.md — official contract defining boundaries
  • Self-test system (bun ${PAI_DIR}/hooks/self-test.ts)
  • Clear README section distinguishing PAI from Kai

Protection System

  • .pai-protected.json manifest of protected files
  • validate-protected.ts script for pre-commit validation
  • Pre-commit hook template for automated checks
v0.6.5 (2025-11-18) — BrightData Integration

Four-Tier Progressive Web Scraping

  • Tier 1: WebFetch (free, built-in)
  • Tier 2: cURL with headers (free, more reliable)
  • Tier 3: Playwright (free, JavaScript rendering)
  • Tier 4: Bright Data MCP (paid, anti-bot bypass)
v0.6.0 (2025-11-15) — Major Architecture Update

Repository Restructure

  • Moved all configuration to .claude/ directory
  • Skills-as-containers architecture
  • Three-tier progressive disclosure

Skills System

  • Art skill with visual content generation
  • Story-explanation skill for narrative summaries
  • Create-skill and create-cli meta-skills

Hook System

  • Comprehensive event capture system
  • Session summary and tool output capture
  • Tab title updates

Voice Integration

  • Voice server with ElevenLabs TTS
  • Session start notifications
v0.5.0 and Earlier

v0.5.0 — Foundation

  • CORE skill as central context loader
  • Constitution defining system principles
  • CLI-First Architecture pattern
  • Initial skills: Fabric, FFUF, Alex Hormozi pitch

Pre-v0.5.0 — Early Development

  • Initial repository setup
  • Basic settings.json structure
  • Agent personality definitions
  • Foundational hook experiments

🙏 Credits

Anthropic and the Claude Code team — First and foremost. You are moving AI further and faster than anyone right now. Claude Code is the foundation that makes all of this possible.

IndyDevDan — For great videos on meta-prompting and custom agents that have inspired parts of PAI.

Contributors

fayerman-source — Google Cloud TTS provider integration and Linux audio support for the voice system.


💜 Support This Project

Sponsor

I spend hundreds of hours a year on open source. If you'd like to help support this project, you can sponsor me here. 🙏🏼


Built with ❤️ by Daniel Miessler and the PAI community

Augment yourself.