How danielmiessler/personal_ai_infrastructure works
Project type and purpose
• This is an open-source, personal AI orchestration platform (PAI). It lives in a user’s shell (~/.claude/) and surfaces both CLI commands and microservices for TTS and observability. It uses “Skills” (domain containers), “Workflows” (task definitions), “Agents” (parallel workers), “Hooks” (lifecycle interceptors), and “MCPs/Direct Code” (external API or self-contained integrations).
File structure
• Top-level remaps everything under .claude/ to mirror ~/.claude/.
• .claude/agents/ – agent role definitions (.md)
• .claude/hooks/ – TypeScript hooks (pre-commit, context loaders, observability)
• .claude/skills/ – skill containers with SKILL.md, workflows/, plus subdirectories for frontend (Vue) and backend (Node) in the agent-observability skill
• .claude/voice-server/ – Bun-based TypeScript microservice for text-to-speech
• Root contains GitHub metadata (README, .github, LICENSE).
README insights
• Four core primitives: Skills, Workflows, Agents, MCPs/Direct Code
• Architecture flow:
User Intent → Skill (container) → Workflow (task) → Implementation (code or MCP)
Agents orchestrate parallel invocations; hooks capture events and load context; observability microservice visualizes execution; voice-server provides TTS.
Main components & interactions
a. Components:
1. PAI CLI (shell entry point)
2. .claude/ directory (configuration, hooks, skills, agents)
3. Skills + Workflows loader
4. Agents Manager (spawns researcher/engineer/designer agents)
5. Implementation layer
• Direct Code (TypeScript scripts, Python helpers)
• MCPs (Anthropic Claude, OpenAI, Gemini, Perplexity, browser tools, cloud services)
6. Hooks subsystem (context-loading, event capture, documentation updates)
7. Observability Service
• Backend (Node server, database)
• Frontend (Vue client UI)
8. Voice-Server microservice (Bun TS server + TTS providers)
b. Relationships & data flow:
1. User issues CLI command or Claude Code trigger → CLI reads PAI_DIR → loads Skills/Workflows.
2. Skill selects Workflow → Agents Manager spins up parallel Agents.
3. Each Agent invokes Implementation (code or MCP API calls) → returns results.
4. Hooks intercept events/results → write to Observability backend.
6. Voice-Server listens on configured port → receives text notifications → calls TTS providers → streams audio back to user.
c. Architectural patterns & principles:
• Skills-as-Containers: each skill self-contained with metadata, workflows, assets
• Progressive disclosure: minimal context on “Always-On,” detailed context loaded on demand
• Natural language routing: user intent → skill/workflow auto-selection
• Parallel agent orchestration for throughput
• Hooks system for modular lifecycle extensions (observability, context loading, docs updates)
• Microservices for observability & TTS decoupled from CLI/core logic
d. Key technologies/frameworks:
• Shell/Bash scripts for CLI and setup
• Bun + TypeScript for voice-server and hooks
• Node.js/TypeScript for observability server
• Vue 3 for observability frontend (agent-observability skill)
• Svelte for Fabric skill web UI
• Markdown-based workflows & skill descriptors
• External APIs: Anthropic Claude, OpenAI, Gemini, Perplexity, MCP servers (Chrome DevTools, Apify, BrightData)
Elements
• CLI → Skills loader → Agents Manager
• Agents → Direct Code/APIs (MCPs)
• Hooks capturing events → Observability backend → frontend
• CLI or Hooks → Voice-Server
• CLI & Config (e.g., gray)
• Skills & Workflows (blue)
• Agents (green)
• Implementation (purple)
• Microservices (orange)
• External APIs (red)
• Directional arrowheads for data flow and dependencies.
Detailed capture of essential elements
• Hooks subsystem as a sidecar that connects to both the Agents Manager and the Observability Service.
• PAI_DIR environment variable is annotated as the config switch that mounts .claude/ in user’s home.