@intent-systems/nexus 2026.1.5-3

package/skills/onboarding/docs/skill-deep-dives/aix.md

@@ -0,0 +1,498 @@
+# Skill Deep-Dive: aix
+
+**Skill**: `aix`
+**Category**: Code/Productivity
+**Setup Difficulty**: 🟢 Easy
+**Time Estimate**: ~3 minutes
+**Platform**: macOS, Linux
+
+---
+
+## What It Enables
+
+| Capability | Description | Example |
+|------------|-------------|---------|
+| AI session history | Access all your AI conversations across tools | `aix sessions` |
+| Cross-tool search | Search conversations from Cursor, Claude Code, Codex, etc. | `aix search "how to fix async error"` |
+| Model tracking | See which AI models you've used (GPT-4, Claude 3.5, etc.) | `aix stats` |
+| Session replay | View full conversation history | `aix show <session-id>` |
+| Semantic search | Find conversations by meaning, not keywords | `aix search "authentication bug"` |
+| Code block extraction | Extract all code blocks from sessions | SQL queries on `code_blocks` table |
+| Durability | Export sessions to git-tracked `~/nexus/home/sessions/` | Automatic on sync |
+| Analytics | Analyze your AI usage patterns | `aix db query` with custom SQL |
+
+---
+
+## Dependencies
+
+### Hard Dependencies (Required)
+- [ ] At least one AI tool — Cursor, Claude Code CLI, Codex, Claude Desktop, or OpenCode
+- [ ] `brew` or `go` — For installing aix
+
+### Soft Dependencies (Recommended)
+- [ ] `GEMINI_API_KEY` — Required for semantic search (optional feature)
+- [ ] `1password` skill — For storing Gemini API key securely
+- [ ] `git` — For tracking exported sessions in `~/nexus/home/sessions/`
+
+### This Skill Enables
+- [ ] Session continuity — Resume conversations across tools
+- [ ] Learning from history — Agents can reference your past AI conversations
+- [ ] Usage analytics — Understand your AI interaction patterns
+
+---
+
+## Installation
+
+### Prerequisites Check
+
+```bash
+# Check if you have any supported AI tools
+ls ~/.cursor/sessions/ 2>/dev/null && echo "✅ Cursor found"
+ls ~/.claude/projects/ 2>/dev/null && echo "✅ Claude Code CLI found"
+ls ~/.codex/sessions/ 2>/dev/null && echo "✅ Codex found"
+ls ~/Library/Application\ Support/Claude/ 2>/dev/null && echo "✅ Claude Desktop found"
+ls ~/.opencode/ 2>/dev/null && echo "✅ OpenCode found"
+
+# Check for brew or go
+which brew && echo "✅ Homebrew available"
+which go && echo "✅ Go available"
+```
+
+### Installation Steps
+
+```bash
+# Option 1: Install via Homebrew (recommended)
+brew install Napageneral/tap/aix
+
+# Option 2: Install via Go
+go install github.com/Napageneral/aix/cmd/aix@latest
+
+# Verify installation
+aix --version
+```
+
+### Verification
+
+```bash
+# Check aix is accessible
+aix --version
+
+# Check if any sources are detected
+aix sync --all --dry-run
+# Should show which sources were found
+```
+
+---
+
+## Configuration
+
+### Step 1: Initialize aix
+
+```bash
+# Create config and database
+aix init
+
+# This creates:
+# - ~/.aix/config.yaml (configuration)
+# - ~/.aix/aix.db (SQLite database for sessions)
+```
+
+### Step 2: Sync Sessions
+
+```bash
+# Sync from all available sources
+aix sync --all
+
+# Or sync from specific source
+aix sync --source cursor
+aix sync --source claude-code
+aix sync --source codex
+aix sync --source claude
+aix sync --source opencode
+
+# Check what was synced
+aix sessions
+aix stats
+```
+
+### Step 3: Optional - Enable Semantic Search
+
+```bash
+# Set Gemini API key (if not already set from eve skill)
+export GEMINI_API_KEY="your-key-here"
+
+# Or load from 1Password
+export GEMINI_API_KEY=$(op read "op://Personal/Gemini API Key/credential")
+
+# Generate embeddings (may take a while for large history)
+aix embed
+
+# Now you can use semantic search
+aix search "authentication problems"
+```
+
+### Verification
+
+```bash
+# List all sessions
+aix sessions
+
+# Show statistics
+aix stats
+
+# View a specific session (use partial ID)
+aix show <first-few-chars-of-session-id>
+
+# Test semantic search (if embeddings generated)
+aix search "bug fix"
+```
+
+---
+
+## User Actions Required
+
+No manual actions required! Everything is automated.
+
+---
+
+## Common Failure Points
+
+### Failure: "No AI tools found"
+
+**Symptom**: `aix sync --all` returns "No sources found" or syncs 0 sessions
+
+**Cause**: None of the supported AI tools are installed or have been used yet
+
+**Recovery**:
+```bash
+# Check which tools are available
+ls ~/.cursor/sessions/ 2>/dev/null
+ls ~/.claude/projects/ 2>/dev/null
+ls ~/.codex/sessions/ 2>/dev/null
+
+# If you're using Cursor but no sessions found:
+# 1. Open Cursor
+# 2. Start a new chat with AI
+# 3. Try syncing again
+aix sync --source cursor
+```
+
+**Prevention**: Ensure you've actually used one of the supported AI tools before syncing
+
+---
+
+### Failure: Embeddings generation is slow
+
+**Symptom**: `aix embed` takes 10+ minutes
+
+**Cause**: Large session history (normal), or Gemini API rate limiting
+
+**Recovery**:
+```bash
+# Check progress
+aix db query "SELECT COUNT(*) as total,
+  SUM(CASE WHEN embedding IS NOT NULL THEN 1 ELSE 0 END) as embedded
+  FROM messages"
+
+# Let it finish - it only needs to run once
+# Subsequent embeds only process new messages
+```
+
+**Prevention**: Run `aix embed` overnight if you have 1000+ sessions
+
+---
+
+### Failure: "GEMINI_API_KEY not set"
+
+**Symptom**: `aix search` or `aix embed` fails with API key error
+
+**Cause**: Environment variable not set (only needed for semantic search)
+
+**Recovery**:
+```bash
+# Set API key
+export GEMINI_API_KEY="your-key-here"
+
+# Or load from 1Password (if eve/1password already setup)
+export GEMINI_API_KEY=$(op read "op://Personal/Gemini API Key/credential")
+
+# Add to shell profile for persistence
+echo 'export GEMINI_API_KEY="op://Personal/Gemini API Key/credential"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+**Prevention**: Setup Gemini API key during eve or aix installation
+
+---
+
+### Failure: Permission denied reading AI tool databases
+
+**Symptom**: Sync fails with "permission denied" errors
+
+**Cause**: AI tool databases locked or insufficient permissions
+
+**Recovery**:
+```bash
+# Make sure AI tool is closed
+# Close Cursor, Claude Desktop, etc.
+
+# Try syncing again
+aix sync --all
+
+# If still failing, check file permissions
+ls -la ~/.cursor/sessions/
+ls -la ~/.claude/projects/
+```
+
+**Prevention**: Close AI tools before syncing, or sync while they're idle
+
+---
+
+## Automation Opportunities
+
+| Step | Automatable? | Tool | Notes |
+|------|--------------|------|-------|
+| Install aix | ✅ Yes | bash | `brew install Napageneral/tap/aix` |
+| Initialize | ✅ Yes | bash | `aix init` |
+| Sync sessions | ✅ Yes | bash | `aix sync --all` |
+| Generate embeddings | ✅ Yes | bash | `aix embed` |
+| Schedule periodic sync | ✅ Yes | cron | `aix sync --all` daily |
+| Query sessions | ✅ Yes | bash | `aix db query` |
+
+### Full Automation Script
+
+```bash
+#!/bin/bash
+# Complete aix setup automation
+
+set -e
+
+echo "Installing aix..."
+brew install Napageneral/tap/aix
+
+echo "Initializing aix..."
+aix init
+
+echo "Syncing sessions from all sources..."
+aix sync --all
+
+echo "✅ aix setup complete!"
+echo ""
+echo "Statistics:"
+aix stats
+
+echo ""
+echo "Optional: Enable semantic search"
+echo "1. Set GEMINI_API_KEY environment variable"
+echo "2. Run: aix embed"
+echo "3. Use: aix search 'your query'"
+```
+
+### Scheduled Sync (Daily)
+
+```bash
+# Add to cron or use nexus cron skill
+# Sync AI sessions daily at 2am
+0 2 * * * /opt/homebrew/bin/aix sync --all
+```
+
+---
+
+## Wow Moments
+
+| Moment | What Happens | When to Demo |
+|--------|--------------|--------------|
+| Your AI history | Show total sessions, messages, code blocks | Right after first sync |
+| Model usage breakdown | Show which AI models user has used most | After stats command |
+| Cross-tool search | Search for a topic across Cursor AND Claude Code | When user has multiple tools |
+| Code block extraction | Show all SQL queries you've asked AI about | When user asks "what did I ask AI about X" |
+| Semantic search | Find conversations by meaning, not keywords | After embeddings generated |
+
+### Demo Script
+
+```
+Agent: "Let me show you what aix has discovered about your AI usage."
+
+aix stats
+
+Agent: "You've had [N] conversations across [M] tools. Let me show your recent sessions:"
+
+aix sessions | head -20
+
+Agent: "I can search your entire AI history. For example, let me find conversations about authentication:"
+
+aix search "authentication implementation"
+
+Agent: "And I can show you the full conversation:"
+
+aix show <session-id>
+
+Agent: "This means I can learn from your past AI conversations to better help you. For example, if you previously asked Claude Code about your project structure, I can reference that context."
+```
+
+---
+
+## Integration with Other Skills
+
+| Skill | Integration | Notes |
+|-------|-------------|-------|
+| **1password** | Stores Gemini API key | For semantic search feature |
+| **cron** | Schedule periodic syncs | Keep session database fresh |
+| **qmd** | Sessions can be indexed | Semantic search across AI history |
+| **git** | Track exported sessions | `~/nexus/home/sessions/` is git-tracked |
+| **eve** | Share Gemini API key | Both use same key for embeddings |
+
+---
+
+## Testing Checklist
+
+- [ ] Fresh install: `brew install Napageneral/tap/aix`
+- [ ] Version check: `aix --version`
+- [ ] Init works: `aix init`
+- [ ] Sync detects sources: `aix sync --all --dry-run`
+- [ ] Sync imports sessions: `aix sync --all`
+- [ ] Sessions list works: `aix sessions`
+- [ ] Stats show data: `aix stats`
+- [ ] Show session works: `aix show <partial-id>`
+- [ ] SQL queries work: `aix db query "SELECT COUNT(*) FROM sessions"`
+- [ ] Embeddings generate (if Gemini key set): `aix embed`
+- [ ] Search works (if embeddings exist): `aix search "test"`
+
+---
+
+## Notes for Onboarding Agent
+
+- **Universal appeal**: Useful for ALL Cursor/Claude Code users, not just hardcore coders
+- **Zero setup friction**: No permissions, no auth, just works
+- **Recommend early**: Setup right after 1password, before eve/gog (easier)
+- **Emphasize durability**: Sessions exported to git-tracked folder = never lose AI conversations
+- **When NOT to recommend**:
+  - User has never used Cursor, Claude Code, Codex, Claude Desktop, or OpenCode
+  - User doesn't care about AI conversation history
+- **Value proposition**: "Never lose an AI conversation again - search your entire history"
+- **Time estimate**: 3 minutes total (install + init + sync)
+- **No manual steps**: Everything is automated - great for onboarding flow
+- **Semantic search is optional**: Basic functionality works without Gemini API key
+
+---
+
+## Supported AI Tools
+
+| Tool | Path | What's Synced |
+|------|------|---------------|
+| **Cursor** | `~/.cursor/sessions/` | Full conversations, code blocks, file references |
+| **Claude Code CLI** | `~/.claude/projects/` | Full conversations, tool use, code edits |
+| **Codex** | `~/.codex/sessions/` | Full conversations (Anthropic Codex CLI) |
+| **Claude Desktop** | `~/Library/Application Support/Claude/` | Metadata only (full messages not accessible) |
+| **OpenCode** | `~/.opencode/` | Full conversations |
+
+---
+
+## Data Flow & Storage
+
+### Where Data Lives
+
+```
+AI Tool → Native DB → aix export → ~/nexus/home/sessions/ (JSON, git-tracked)
+                   ↓
+             aix.db (SQLite, analysis)
+             ~/.aix/aix.db
+```
+
+### Key Directories
+
+- `~/.aix/config.yaml` — Configuration
+- `~/.aix/aix.db` — SQLite database for querying/analysis
+- `~/nexus/home/sessions/` — Exported JSON sessions (durable, git-tracked)
+
+### Database Schema (aix.db)
+
+```sql
+-- Core tables
+sessions      -- Session metadata (id, source, model, timestamps)
+messages      -- Individual messages (role, content, timestamp)
+code_blocks   -- Extracted code blocks with language
+capabilities  -- Tracked capabilities/features used
+files         -- File references from sessions
+errors        -- Linter errors mentioned in sessions
+embeddings    -- Vector embeddings for semantic search
+```
+
+---
+
+## SQL Query Examples
+
+```sql
+-- Total sessions per source
+SELECT source, COUNT(*) as sessions
+FROM sessions
+GROUP BY source;
+
+-- Model usage (which AI models you use most)
+SELECT model, COUNT(*) as count
+FROM sessions
+WHERE model IS NOT NULL
+GROUP BY model
+ORDER BY count DESC;
+
+-- Recent activity (last 14 days)
+SELECT date(created_at/1000, 'unixepoch') as day,
+       source,
+       COUNT(*) as sessions
+FROM sessions
+WHERE created_at > (strftime('%s', 'now') - 1209600) * 1000
+GROUP BY day, source
+ORDER BY day DESC;
+
+-- Find sessions with specific file references
+SELECT s.id, s.title, f.path
+FROM sessions s
+JOIN files f ON s.id = f.session_id
+WHERE f.path LIKE '%auth%';
+
+-- Code blocks by language
+SELECT language, COUNT(*) as blocks
+FROM code_blocks
+GROUP BY language
+ORDER BY blocks DESC;
+
+-- Sessions with most messages
+SELECT id, title, message_count
+FROM sessions
+ORDER BY message_count DESC
+LIMIT 10;
+```
+
+---
+
+## Performance Considerations
+
+- **Initial sync**: May take 1-5 minutes for large histories (1000+ sessions)
+- **Incremental sync**: Fast (only processes new sessions)
+- **Embeddings**: Slow for first run (5-30 minutes), fast for incremental
+- **Database size**: ~1MB per 100 sessions (lightweight)
+- **Memory usage**: Low (~50MB typical)
+
+---
+
+## Future Enhancements
+
+Potential features (not yet implemented):
+
+- Cross-session context: "Show all conversations about project X"
+- Session resumption: "Continue session from Cursor in Claude Code"
+- Pattern detection: "You often ask about async/await - here's a guide"
+- Collaboration: Share anonymized sessions with team
+- Export formats: Markdown, HTML, PDF
+
+---
+
+## Changelog
+
+| Date | Change |
+|------|--------|
+| 2026-01-12 | Initial deep-dive created |
+
+---
+
+*Template version: 1.0*