@cpretzinger/boss-claude 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Craig Pretzinger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,264 @@
+# Boss Claude
+
+**Gamified AI assistant with persistent memory across all your repositories.**
+
+Boss Claude turns every coding session into an RPG-style experience where Claude levels up, earns tokens, and maintains perfect memory across all your projects through GitHub Issues.
+
+## Features
+
+- 🎮 **Gamification**: Claude levels up with XP, builds a token bank, and tracks career stats
+- 💾 **Persistent Memory**: Every session auto-saves to GitHub Issues for perfect recall
+- 🌍 **Global CLI**: Works in ANY repository after `npm install -g`
+- 📊 **Career Stats**: Track total sessions, repos managed, token earnings
+- 🔍 **Semantic Search**: Recall past sessions with natural language queries
+- 🏆 **Progression System**: Level-based XP, token banking, achievement tracking
+
+## Installation
+
+```bash
+npm install -g @cpretzinger/boss-claude
+```
+
+## Setup
+
+### 1. Configure Credentials
+
+Edit `~/.boss-claude/.env` with your credentials:
+
+```bash
+# Redis URL (required) - For Boss identity and session storage
+REDIS_URL=redis://default:password@host:port
+
+# GitHub Token (required) - For memory storage in GitHub Issues
+# Create at: https://github.com/settings/tokens (needs 'repo' scope)
+GITHUB_TOKEN=ghp_your_token_here
+
+# GitHub Owner (optional) - Defaults to 'cpretzinger'
+GITHUB_OWNER=your-username
+
+# GitHub Memory Repository (optional) - Defaults to 'boss-claude-memory'
+GITHUB_MEMORY_REPO=boss-claude-memory
+```
+
+### 2. Create GitHub Memory Repository
+
+Create a repository to store your session memories:
+
+```bash
+gh repo create boss-claude-memory --private
+```
+
+### 3. Initialize Boss Claude
+
+```bash
+boss-claude init
+```
+
+## Usage
+
+Boss Claude automatically loads when Claude starts in ANY repository. You'll see:
+
+```
+🎮 BOSS CLAUDE AUTO-LOADED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+👤 BOSS STATUS
+   Level 5 • 250/500 XP (50%)
+   💰 Token Bank: 1,234,567 tokens
+   📊 Total Sessions: 42
+   🏢 Repos Managed: 8
+
+📁 CURRENT REPOSITORY
+   Name: my-awesome-project
+   Path: /Users/you/projects/my-awesome-project
+   Sessions: 12
+   Last Active: 2026-01-30T15:30:00.000Z
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+💡 Commands: boss-claude status | save | recall
+```
+
+### Commands
+
+#### Show Status
+```bash
+boss-claude status
+```
+
+Displays Boss level, XP, token bank, and repository stats.
+
+#### Save Session
+```bash
+boss-claude save "Implemented user authentication"
+boss-claude save "Fixed bug in API" --tags "bugfix,api"
+```
+
+Saves current session to GitHub Issues with:
+- Automatic summary if not provided
+- Optional tags for organization
+- XP and token rewards
+- Searchable history
+
+#### Recall Past Sessions
+```bash
+boss-claude recall "authentication"
+boss-claude recall "bug fix" --limit 10
+```
+
+Searches your GitHub Issues memory for past sessions.
+
+## How It Works
+
+### Session Flow
+
+1. **Auto-Load**: Boss Claude loads on every Claude conversation start
+2. **Session Tracking**: Monitors tokens used, messages, and repository context
+3. **Save to Memory**: Session data saved as GitHub Issue when you run `boss-claude save`
+4. **Rewards**: Earn XP (50 per session) and bank tokens used
+5. **Level Up**: Reach new levels (100 XP per level, exponential scaling)
+
+### Data Storage
+
+- **Redis**: Boss identity, session state, repository stats
+- **GitHub Issues**: Long-term memory storage, searchable with full history
+- **Local**: Configuration in `~/.boss-claude/.env`
+
+### Memory Structure
+
+Each saved session creates a GitHub Issue with:
+
+```markdown
+## Session Summary
+
+Implemented user authentication
+
+## Session Data
+
+```json
+{
+  "started_at": "2026-01-30T15:00:00.000Z",
+  "tokens_used": 12500,
+  "messages": [...],
+  "repo": {
+    "name": "my-project",
+    "path": "/Users/you/projects/my-project"
+  }
+}
+```
+
+Labels: `session`, `my-project`, `authentication`
+```
+
+## Architecture
+
+```
+~/.boss-claude/
+├── .env                    # Your credentials
+
+GitHub Repository (boss-claude-memory)
+└── Issues/                 # One issue per session
+    ├── #1: [repo-name] Session summary
+    ├── #2: [repo-name] Session summary
+    └── ...
+
+Redis Keys
+├── boss:identity           # Boss level, XP, token bank
+├── boss:repo:{name}        # Repository stats
+└── boss:session:{name}     # Active session data
+```
+
+## Gamification System
+
+### Levels
+- **Level 1**: Start
+- **Level 2**: 100 XP
+- **Level 3**: 200 XP
+- **Level 4**: 300 XP
+- ...and so on (100 XP per level)
+
+### Rewards
+- **XP**: 50 XP per session saved
+- **Token Bank**: All tokens used during session are banked
+- **Net Worth**: Token bank × $0.000003 per token
+
+### Stats Tracked
+- Total sessions across all repos
+- Repositories managed
+- Token bank size
+- Current level and XP progress
+- Per-repo session counts
+
+## CLI Reference
+
+```bash
+# Initialize Boss Claude in current repo
+boss-claude init
+
+# Show Boss status and stats
+boss-claude status
+
+# Save current session
+boss-claude save [summary] [--tags <tags>]
+
+# Search past sessions
+boss-claude recall <query> [--limit <number>]
+
+# Show help
+boss-claude --help
+```
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `REDIS_URL` | Yes | - | Redis connection string |
+| `GITHUB_TOKEN` | Yes | - | GitHub personal access token |
+| `GITHUB_OWNER` | No | `cpretzinger` | GitHub username |
+| `GITHUB_MEMORY_REPO` | No | `boss-claude-memory` | Repository name for memory storage |
+
+## Troubleshooting
+
+### "REDIS_URL not found"
+Edit `~/.boss-claude/.env` and add your Redis connection string.
+
+### "GITHUB_TOKEN not found"
+Create a GitHub token at https://github.com/settings/tokens with `repo` scope and add to `~/.boss-claude/.env`.
+
+### "Not in a git repository"
+Boss Claude requires a git repository to track sessions. Initialize one with `git init`.
+
+### Auto-load not working
+Check that `~/.claude/CLAUDE.md` contains the Boss Claude auto-load block. Reinstall with:
+```bash
+npm uninstall -g @cpretzinger/boss-claude
+npm install -g @cpretzinger/boss-claude
+```
+
+## Development
+
+```bash
+# Clone the repo
+git clone https://github.com/cpretzinger/boss-claude.git
+cd boss-claude
+
+# Install dependencies
+npm install
+
+# Link globally for testing
+npm link
+
+# Test in any repo
+boss-claude init
+```
+
+## License
+
+MIT
+
+## Author
+
+Craig Pretzinger ([@cpretzinger](https://github.com/cpretzinger))
+
+---
+
+**Built with**: Node.js, Redis, GitHub API, Commander.js, Chalk

package/bin/boss-claude.js

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { loadIdentity, updateIdentity } from '../lib/identity.js';
+import { loadSession, saveSession } from '../lib/session.js';
+import { searchMemory, saveMemory } from '../lib/memory.js';
+import { getStatus } from '../lib/init.js';
+
+const program = new Command();
+
+program
+  .name('boss-claude')
+  .description('Boss Claude - Gamified AI assistant with persistent memory')
+  .version('1.0.0');
+
+program
+  .command('init')
+  .description('Initialize Boss Claude in current repository')
+  .action(async () => {
+    try {
+      console.log(chalk.blue('🎮 Initializing Boss Claude...\n'));
+
+      const status = await getStatus();
+
+      console.log(chalk.green('✅ Boss Claude initialized successfully!\n'));
+      console.log(chalk.bold('Boss Identity:'));
+      console.log(`  Level: ${chalk.yellow(status.boss.level)}`);
+      console.log(`  XP: ${chalk.cyan(status.boss.xp)}/${status.boss.xp_to_next_level}`);
+      console.log(`  Token Bank: ${chalk.magenta(status.boss.token_bank.toLocaleString())} tokens`);
+      console.log(`  Total Sessions: ${chalk.blue(status.boss.total_sessions)}`);
+      console.log(`  Repositories Managed: ${chalk.green(status.boss.repos_managed)}\n`);
+
+      if (status.repo) {
+        console.log(chalk.bold('Current Repository:'));
+        console.log(`  Name: ${chalk.white(status.repo.name)}`);
+        console.log(`  Path: ${chalk.gray(status.repo.path)}`);
+        console.log(`  Sessions: ${chalk.blue(status.repo.session_count)}`);
+        console.log(`  Last Active: ${chalk.gray(status.repo.last_active || 'Never')}\n`);
+      } else {
+        console.log(chalk.yellow('⚠️  Not in a git repository\n'));
+      }
+
+    } catch (error) {
+      console.error(chalk.red('❌ Error initializing Boss Claude:'), error.message);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('status')
+  .description('Show Boss Claude status and stats')
+  .action(async () => {
+    try {
+      const status = await getStatus();
+
+      console.log(chalk.bold.blue('\n🎮 BOSS CLAUDE STATUS\n'));
+      console.log(chalk.bold('Boss Level & Progress:'));
+      console.log(`  Level: ${chalk.yellow.bold(status.boss.level)}`);
+      console.log(`  XP: ${chalk.cyan(status.boss.xp)}/${status.boss.xp_to_next_level} (${Math.floor((status.boss.xp / status.boss.xp_to_next_level) * 100)}%)`);
+      console.log(`  Token Bank: ${chalk.magenta.bold(status.boss.token_bank.toLocaleString())} tokens`);
+      console.log(`  Net Worth: ${chalk.green.bold('$' + (status.boss.token_bank * 0.000003).toFixed(2))}\n`);
+
+      console.log(chalk.bold('Career Stats:'));
+      console.log(`  Total Sessions: ${chalk.blue(status.boss.total_sessions)}`);
+      console.log(`  Repositories Managed: ${chalk.green(status.boss.repos_managed)}`);
+      console.log(`  Account Created: ${chalk.gray(status.boss.created_at)}\n`);
+
+      if (status.repo) {
+        console.log(chalk.bold('Current Repository:'));
+        console.log(`  Name: ${chalk.white.bold(status.repo.name)}`);
+        console.log(`  Path: ${chalk.gray(status.repo.path)}`);
+        console.log(`  Sessions: ${chalk.blue(status.repo.session_count)}`);
+        console.log(`  Last Active: ${chalk.gray(status.repo.last_active || 'Never')}\n`);
+      } else {
+        console.log(chalk.yellow('⚠️  Not currently in a git repository\n'));
+      }
+
+      console.log(chalk.dim('💡 Use "boss-claude save" to save your current session'));
+      console.log(chalk.dim('💡 Use "boss-claude recall" to search past sessions\n'));
+
+    } catch (error) {
+      console.error(chalk.red('❌ Error fetching status:'), error.message);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('save')
+  .description('Save current session to memory')
+  .argument('[summary]', 'Session summary (optional)')
+  .option('-t, --tags <tags>', 'Comma-separated tags')
+  .action(async (summary, options) => {
+    try {
+      console.log(chalk.blue('💾 Saving session...\n'));
+
+      const session = await saveSession(summary, options.tags);
+
+      console.log(chalk.green('✅ Session saved to GitHub Issues!\n'));
+      console.log(chalk.bold('Session Details:'));
+      console.log(`  Issue: ${chalk.cyan('#' + session.issue_number)}`);
+      console.log(`  Repository: ${chalk.white(session.repo_name)}`);
+      console.log(`  Summary: ${chalk.gray(session.summary)}`);
+      if (session.tags) {
+        console.log(`  Tags: ${chalk.yellow(session.tags.join(', '))}`);
+      }
+      console.log(`  URL: ${chalk.blue(session.url)}\n`);
+
+      console.log(chalk.bold('Rewards:'));
+      console.log(`  XP Earned: ${chalk.cyan('+' + session.xp_earned)}`);
+      console.log(`  Tokens Banked: ${chalk.magenta('+' + session.tokens_earned.toLocaleString())}\n`);
+
+    } catch (error) {
+      console.error(chalk.red('❌ Error saving session:'), error.message);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('recall')
+  .description('Search past sessions')
+  .argument('<query>', 'Search query')
+  .option('-l, --limit <number>', 'Number of results', '5')
+  .action(async (query, options) => {
+    try {
+      console.log(chalk.blue(`🔍 Searching for: "${query}"\n`));
+
+      const results = await searchMemory(query, parseInt(options.limit));
+
+      if (results.length === 0) {
+        console.log(chalk.yellow('No sessions found matching your query\n'));
+        return;
+      }
+
+      console.log(chalk.green(`Found ${results.length} session(s):\n`));
+
+      results.forEach((result, idx) => {
+        console.log(chalk.bold(`${idx + 1}. ${result.title}`));
+        console.log(`   ${chalk.gray(result.summary)}`);
+        console.log(`   ${chalk.blue(result.url)}`);
+        console.log(`   ${chalk.dim(result.created_at)}\n`);
+      });
+
+    } catch (error) {
+      console.error(chalk.red('❌ Error searching memory:'), error.message);
+      process.exit(1);
+    }
+  });
+
+program.parse();

package/lib/identity.js

@@ -0,0 +1,115 @@
+import Redis from 'ioredis';
+import dotenv from 'dotenv';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { existsSync } from 'fs';
+import os from 'os';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Load environment variables from ~/.boss-claude/.env
+const envPath = join(os.homedir(), '.boss-claude', '.env');
+if (existsSync(envPath)) {
+  dotenv.config({ path: envPath });
+}
+
+let redis = null;
+
+function getRedis() {
+  if (!redis) {
+    if (!process.env.REDIS_URL) {
+      throw new Error('REDIS_URL not found. Please run: boss-claude init');
+    }
+    redis = new Redis(process.env.REDIS_URL);
+  }
+  return redis;
+}
+
+const BOSS_KEY = 'boss:identity';
+
+export async function loadIdentity() {
+  const client = getRedis();
+  const data = await client.get(BOSS_KEY);
+
+  if (!data) {
+    // Create default Boss identity
+    const identity = {
+      level: 1,
+      xp: 0,
+      token_bank: 0,
+      total_sessions: 0,
+      repos_managed: 0,
+      created_at: new Date().toISOString()
+    };
+
+    await client.set(BOSS_KEY, JSON.stringify(identity));
+    return identity;
+  }
+
+  return JSON.parse(data);
+}
+
+export async function updateIdentity(updates) {
+  const client = getRedis();
+  const identity = await loadIdentity();
+
+  const updated = {
+    ...identity,
+    ...updates,
+    updated_at: new Date().toISOString()
+  };
+
+  await client.set(BOSS_KEY, JSON.stringify(updated));
+  return updated;
+}
+
+export async function addXP(amount) {
+  const identity = await loadIdentity();
+
+  let newXP = identity.xp + amount;
+  let newLevel = identity.level;
+
+  // Level up logic (100 XP per level, exponential)
+  const xpForNextLevel = newLevel * 100;
+
+  if (newXP >= xpForNextLevel) {
+    newLevel++;
+    newXP -= xpForNextLevel;
+  }
+
+  return updateIdentity({
+    level: newLevel,
+    xp: newXP
+  });
+}
+
+export async function addTokens(amount) {
+  const identity = await loadIdentity();
+
+  return updateIdentity({
+    token_bank: identity.token_bank + amount
+  });
+}
+
+export async function incrementSessions() {
+  const identity = await loadIdentity();
+
+  return updateIdentity({
+    total_sessions: identity.total_sessions + 1
+  });
+}
+
+export async function addRepo(repoName) {
+  const client = getRedis();
+  const repoKey = `boss:repo:${repoName}`;
+
+  const exists = await client.exists(repoKey);
+
+  if (!exists) {
+    const identity = await loadIdentity();
+    await updateIdentity({
+      repos_managed: identity.repos_managed + 1
+    });
+  }
+}

package/lib/init.js

@@ -0,0 +1,133 @@
+import { loadIdentity, addRepo } from './identity.js';
+import Redis from 'ioredis';
+import dotenv from 'dotenv';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { existsSync } from 'fs';
+import os from 'os';
+import { exec } from 'child_process';
+import { promisify } from 'util';
+
+const execAsync = promisify(exec);
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Load environment variables from ~/.boss-claude/.env
+const envPath = join(os.homedir(), '.boss-claude', '.env');
+if (existsSync(envPath)) {
+  dotenv.config({ path: envPath });
+}
+
+let redis = null;
+
+function getRedis() {
+  if (!redis) {
+    if (!process.env.REDIS_URL) {
+      throw new Error('REDIS_URL not found. Please run: boss-claude init');
+    }
+    redis = new Redis(process.env.REDIS_URL);
+  }
+  return redis;
+}
+
+async function getCurrentRepo() {
+  try {
+    const { stdout: repoPath } = await execAsync('git rev-parse --show-toplevel');
+    const { stdout: repoUrl } = await execAsync('git config --get remote.origin.url');
+
+    const repoName = repoUrl.trim().split('/').pop().replace('.git', '');
+
+    return {
+      name: repoName,
+      path: repoPath.trim(),
+      url: repoUrl.trim()
+    };
+  } catch (error) {
+    return null;
+  }
+}
+
+export async function getStatus() {
+  // Load Boss identity
+  const boss = await loadIdentity();
+
+  // Calculate XP to next level
+  const xp_to_next_level = boss.level * 100;
+
+  // Get current repo info
+  const repo = await getCurrentRepo();
+
+  let repoStats = null;
+
+  if (repo) {
+    // Register repo if new
+    await addRepo(repo.name);
+
+    // Get repo stats
+    const client = getRedis();
+    const repoKey = `boss:repo:${repo.name}`;
+    const repoData = await client.get(repoKey);
+
+    if (repoData) {
+      repoStats = JSON.parse(repoData);
+    } else {
+      // Initialize repo stats
+      repoStats = {
+        name: repo.name,
+        path: repo.path,
+        session_count: 0,
+        first_seen: new Date().toISOString(),
+        last_active: null
+      };
+      await client.set(repoKey, JSON.stringify(repoStats));
+    }
+  }
+
+  return {
+    boss: {
+      ...boss,
+      xp_to_next_level
+    },
+    repo: repo ? {
+      ...repo,
+      ...repoStats
+    } : null
+  };
+}
+
+export async function formatStatusForClaude() {
+  const status = await getStatus();
+
+  let output = `
+🎮 BOSS CLAUDE AUTO-LOADED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+👤 BOSS STATUS
+   Level ${status.boss.level} • ${status.boss.xp}/${status.boss.xp_to_next_level} XP (${Math.floor((status.boss.xp / status.boss.xp_to_next_level) * 100)}%)
+   💰 Token Bank: ${status.boss.token_bank.toLocaleString()} tokens
+   📊 Total Sessions: ${status.boss.total_sessions}
+   🏢 Repos Managed: ${status.boss.repos_managed}
+`;
+
+  if (status.repo) {
+    output += `
+📁 CURRENT REPOSITORY
+   Name: ${status.repo.name}
+   Path: ${status.repo.path}
+   Sessions: ${status.repo.session_count}
+   Last Active: ${status.repo.last_active || 'Never'}
+`;
+  } else {
+    output += `
+⚠️  Not currently in a git repository
+`;
+  }
+
+  output += `
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+💡 Commands: boss-claude status | save | recall
+`;
+
+  return output;
+}