claude-code-pack 1.0.0 → 1.2.0

package/README.md

@@ -2,19 +2,36 @@
 
 Portable Claude Code setup — installs your plugins, skills, MCP servers, and settings on any machine with a single command.
 
-## Quick Start
+## Installation
+
+### From npm
 
 ```bash
-npx claude-pack install
+npx claude-code-pack install
 ```
 
 Or install globally:
 
 ```bash
-npm install -g claude-pack
+npm install -g claude-code-pack
+claude-pack install
+```
+
+### From GitHub
+
+```bash
+git clone git@github.com:lvtan71/claude-pack.git
+cd claude-pack
+npm link
 claude-pack install
 ```
 
+Or run directly without installing:
+
+```bash
+npx github:lvtan71/claude-pack install
+```
+
 ## What It Does
 
 `claude-pack` reads `claude-pack.config.json` and sets up your Claude Code environment:
@@ -28,43 +45,63 @@ claude-pack install
 
 Everything is fetched fresh from GitHub, so you always get the latest version.
 
-## Configuration
+## What's Included
 
-Edit `claude-pack.config.json` to customize your setup:
+### Plugins
 
-```json
-{
-  "plugins": [
-    {
-      "name": "claude-mem",
-      "marketplace": "thedotmack",
-      "repo": "thedotmack/claude-mem",
-      "enabled": true
-    }
-  ],
-  "marketplaces": [
-    { "name": "thedotmack", "repo": "thedotmack/claude-mem" }
-  ],
-  "skills": [
-    { "name": "my-skill", "source": "bundled" },
-    { "name": "remote-skill", "source": "github", "repo": "user/repo" }
-  ],
-  "mcpServers": {
-    "my-server": {
-      "command": "npx",
-      "args": ["-y", "@some/mcp-server"]
-    }
-  },
-  "settings": {
-    "model": "opus"
-  }
-}
-```
+| Plugin | Source | Description |
+|--------|--------|-------------|
+| **claude-mem** | [thedotmack/claude-mem](https://github.com/thedotmack/claude-mem) | Persistent cross-session memory, smart code exploration (AST-based), phased implementation plans, and timeline reports |
+| **understand-anything** | [Lum1104/Understand-Anything](https://github.com/Lum1104/Understand-Anything) | Codebase analysis, interactive knowledge graphs, architecture visualization, onboarding guides, and diff analysis |
+
+### Marketplaces
 
-### Skill Sources
+| Marketplace | Source | Description |
+|-------------|--------|-------------|
+| **thedotmack** | [thedotmack/claude-mem](https://github.com/thedotmack/claude-mem) | Plugin marketplace for claude-mem and related tools |
+| **understand-anything** | [Lum1104/Understand-Anything](https://github.com/Lum1104/Understand-Anything) | Codebase understanding, onboarding, and architecture analysis tools |
 
-- `"source": "bundled"` — copies from the `skills/` directory in this package
-- `"source": "github", "repo": "user/repo"` — clones from GitHub
+### Skills (Bundled)
+
+| Skill | Description |
+|-------|-------------|
+| **cloud-devops** | Cloud infrastructure and DevOps workflows — AWS, Azure, GCP, Kubernetes, Terraform, CI/CD, monitoring |
+| **fastapi** | FastAPI best practices, Pydantic models, dependency injection, streaming, and latest patterns |
+| **senior-ml-engineer** | MLOps pipelines, model deployment, drift monitoring, RAG systems, LLM integration, cost optimization |
+| **technical-writer** | Documentation, API references, guides, tutorials, and technical content creation |
+
+### MCP Servers
+
+| Server | Type | Source | Description |
+|--------|------|--------|-------------|
+| **linear** | HTTP | [mcp.linear.app](https://mcp.linear.app/mcp) | Linear project management — issues, projects, comments, milestones |
+| **context7** | HTTP | [mcp.context7.com](https://mcp.context7.com/mcp) | Up-to-date library documentation and code examples |
+| **fetch** | stdio | `mcp-server-fetch` (uvx) | Fetch web content for processing |
+| **filesystem** | stdio | `@modelcontextprotocol/server-filesystem` (npx) | File system access (defaults to `$HOME`, configurable at install) |
+| **sequential-thinking** | stdio | `@modelcontextprotocol/server-sequential-thinking` (npx) | Step-by-step reasoning and problem decomposition |
+| **time** | stdio | `mcp-server-time` (uvx) | Current time and timezone operations |
+
+> `$HOME` in MCP server args is automatically resolved to the user's home directory at install time.
+> The **filesystem** server prompts you during install to confirm or customize the path. Works on Linux/WSL, macOS, and Windows.
+
+### Settings
+
+| Setting | Value |
+|---------|-------|
+| **Model (Claude Code)** | `opus` |
+| **Model (Codex)** | `gpt-5.4` (reasoning effort: `xhigh`) |
+| **Statusline** | Custom bash script with context window, 5h/7d rate limit bars, and color-coded usage indicators |
+
+### Codex Integration
+
+The installer also generates a `~/.codex/config.toml` that **reuses the same MCP servers and skills** as Claude Code — no duplicate configuration needed.
+
+| What | How it's shared |
+|------|----------------|
+| **MCP servers** | Generated into `config.toml` from the same `mcpServers` in `claude-pack.config.json` |
+| **Skills** | Codex `[[skills.config]]` points to `~/.claude/skills/` (the same directory Claude Code uses) |
+
+This means when you add a new MCP server or skill to the pack, both Claude Code and Codex pick it up.
 
 ## Commands
 
@@ -78,32 +115,66 @@ claude-pack install --force         # Overwrite existing installations
 claude-pack install --skip-plugins  # Skip plugin installation
 claude-pack install --skip-skills   # Skip skill installation
 claude-pack install --skip-settings # Skip settings merge
+claude-pack install --skip-codex    # Skip Codex config generation
 claude-pack install --dry-run       # Preview without changes
 ```
 
-## Adding New Components
+## Contributing
 
-### Add a plugin
+### Setup
+
+```bash
+git clone git@github.com:lvtan71/claude-pack.git
+cd claude-pack
+npm link    # makes `claude-pack` command available locally
+```
 
-1. Add to `claude-pack.config.json` under `plugins` and `marketplaces`
-2. Run `claude-pack install`
+### Adding a Plugin
 
-### Add a skill from GitHub
+1. Edit `claude-pack.config.json` — add entries to both `plugins` and `marketplaces`:
 
 ```json
+// In "plugins" array:
+{
+  "name": "my-plugin",
+  "marketplace": "marketplace-name",
+  "repo": "github-user/repo-name",
+  "enabled": true
+}
+
+// In "marketplaces" array:
 {
-  "name": "my-skill",
-  "source": "github",
-  "repo": "username/my-skill-repo"
+  "name": "marketplace-name",
+  "repo": "github-user/repo-name"
 }
 ```
 
-### Add a bundled skill
+2. Update the **Plugins** and **Marketplaces** tables in this README.
 
-1. Create `skills/my-skill/SKILL.md`
-2. Add to config: `{ "name": "my-skill", "source": "bundled" }`
+### Adding a Skill
 
-### Add an MCP server
+**Option A — Bundled skill** (skill files live in this repo):
+
+1. Create `skills/my-skill/SKILL.md` (and optional `references/` directory).
+2. Add to `claude-pack.config.json`:
+
+```json
+{ "name": "my-skill", "source": "bundled" }
+```
+
+**Option B — GitHub-hosted skill** (cloned at install time):
+
+1. Add to `claude-pack.config.json`:
+
+```json
+{ "name": "my-skill", "source": "github", "repo": "github-user/my-skill-repo" }
+```
+
+2. Update the **Skills** table in this README.
+
+### Adding an MCP Server
+
+1. Add to the `mcpServers` object in `claude-pack.config.json`:
 
 ```json
 "mcpServers": {
@@ -114,7 +185,46 @@ claude-pack install --dry-run       # Preview without changes
 }
 ```
 
+2. Update the **MCP Servers** section in this README.
+
+### Publishing a New Version
+
+1. Make your changes and commit.
+2. Bump the version:
+
+```bash
+npm version patch   # 1.0.0 → 1.0.1 (bug fixes, small updates)
+npm version minor   # 1.0.0 → 1.1.0 (new plugins/skills added)
+npm version major   # 1.0.0 → 2.0.0 (breaking config changes)
+```
+
+3. Push with tags:
+
+```bash
+git push origin main --tags
+```
+
+4. Publish to npm:
+
+```bash
+npm publish
+```
+
+> `npm version` automatically creates a git commit and tag (e.g., `v1.1.0`).
+> Make sure all changes are committed before running it.
+
+### Pull Request Guidelines
+
+- One plugin/skill/MCP server per PR when possible.
+- Update the README tables to reflect your additions.
+- Test with `claude-pack install --dry-run` before submitting.
+- Test a full install with `claude-pack install --force` on a clean environment if possible.
+
 ## Requirements
 
 - Node.js >= 18
 - git
+
+## License
+
+MIT

package/bin/claude-pack.mjs

@@ -11,6 +11,7 @@ const flags = {
   skipPlugins: args.includes('--skip-plugins'),
   skipSkills: args.includes('--skip-skills'),
   skipSettings: args.includes('--skip-settings'),
+  skipCodex: args.includes('--skip-codex'),
 };
 
 switch (command) {
@@ -44,5 +45,6 @@ Flags:
   --skip-plugins    Skip plugin installation
   --skip-skills     Skip skill installation
   --skip-settings   Skip settings merge
+  --skip-codex      Skip Codex config generation
 `);
 }

package/claude-pack.config.json

@@ -5,6 +5,12 @@
       "marketplace": "thedotmack",
       "repo": "thedotmack/claude-mem",
       "enabled": true
+    },
+    {
+      "name": "understand-anything",
+      "marketplace": "understand-anything",
+      "repo": "Lum1104/Understand-Anything",
+      "enabled": true
     }
   ],
   "marketplaces": [
@@ -18,12 +24,60 @@
     }
   ],
   "skills": [
-    { "name": "cloud-devops", "source": "bundled" },
-    { "name": "fastapi", "source": "bundled" },
-    { "name": "senior-ml-engineer", "source": "bundled" },
-    { "name": "technical-writer", "source": "bundled" }
+    {
+      "name": "cloud-devops",
+      "source": "bundled"
+    },
+    {
+      "name": "fastapi",
+      "source": "bundled"
+    },
+    {
+      "name": "senior-ml-engineer",
+      "source": "bundled"
+    },
+    {
+      "name": "technical-writer",
+      "source": "bundled"
+    }
   ],
-  "mcpServers": {},
+  "mcpServers": {
+    "linear": {
+      "type": "http",
+      "url": "https://mcp.linear.app/mcp"
+    },
+    "context7": {
+      "type": "http",
+      "url": "https://mcp.context7.com/mcp"
+    },
+    "fetch": {
+      "command": "uvx",
+      "args": [
+        "mcp-server-fetch"
+      ]
+    },
+    "filesystem": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-filesystem",
+        "$HOME"
+      ]
+    },
+    "sequential-thinking": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-sequential-thinking"
+      ]
+    },
+    "time": {
+      "command": "uvx",
+      "args": [
+        "mcp-server-time"
+      ]
+    }
+  },
   "settings": {
     "model": "opus",
     "statusLine": {
@@ -33,5 +87,12 @@
   },
   "assets": {
     "statusline": "assets/statusline-command.sh"
+  },
+  "codex": {
+    "enabled": true,
+    "model": "gpt-5.4",
+    "model_reasoning_effort": "xhigh",
+    "configPath": "$HOME/.codex/config.toml",
+    "skillsPath": "$HOME/.claude/skills"
   }
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-pack",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Portable Claude Code setup — installs plugins, skills, MCP servers, and statusline on any machine",
   "type": "module",
   "bin": {
@@ -23,7 +23,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/tanle/claude-pack.git"
+    "url": "git+https://github.com/lvtan71/claude-pack.git"
   },
   "engines": {
     "node": ">=18"

package/src/install.mjs

@@ -1,8 +1,9 @@
 import { execSync } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, writeFileSync, cpSync } from 'node:fs';
 import { join, dirname, resolve } from 'node:path';
-import { homedir } from 'node:os';
+import { homedir, platform } from 'node:os';
 import { fileURLToPath } from 'node:url';
+import { createInterface } from 'node:readline';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PACK_ROOT = resolve(__dirname, '..');
@@ -37,6 +38,37 @@ function writeJSON(path, data) {
   writeFileSync(path, JSON.stringify(data, null, 2) + '\n');
 }
 
+function prompt(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+function getDefaultHome() {
+  return homedir();
+}
+
+function resolveHomeInConfig(obj) {
+  if (typeof obj === 'string') {
+    return obj.replace(/\$HOME/g, homedir());
+  }
+  if (Array.isArray(obj)) {
+    return obj.map(resolveHomeInConfig);
+  }
+  if (obj && typeof obj === 'object') {
+    const resolved = {};
+    for (const [k, v] of Object.entries(obj)) {
+      resolved[k] = resolveHomeInConfig(v);
+    }
+    return resolved;
+  }
+  return obj;
+}
+
 function loadConfig() {
   const configPath = join(PACK_ROOT, 'claude-pack.config.json');
   return JSON.parse(readFileSync(configPath, 'utf8'));
@@ -59,7 +91,7 @@ function gitClone(repo, dest) {
   return 'cloned';
 }
 
-function getPluginVersion(marketplaceDir, pluginName) {
+function getPluginVersion(marketplaceDir) {
   // Try to read version from plugin's package.json or manifest
   const candidates = [
     join(marketplaceDir, 'plugin', 'package.json'),
@@ -82,7 +114,7 @@ function getGitCommitSha(dir) {
   }
 }
 
-function findPluginInstallPath(marketplaceDir, pluginName) {
+function findPluginInstallPath(marketplaceDir) {
   // Look for a plugin/ subdirectory or the root
   const pluginSubdir = join(marketplaceDir, 'plugin');
   if (existsSync(pluginSubdir)) return pluginSubdir;
@@ -288,7 +320,7 @@ function installSkills(config, flags) {
 
 // ─── Settings Merge ────────────────────────────────────────────────────
 
-function installSettings(config, flags) {
+async function installSettings(config, flags) {
   console.log('\n⚙  Settings');
 
   const settings = readJSON(SETTINGS_PATH);
@@ -329,23 +361,173 @@ function installSettings(config, flags) {
   }
 
   // Merge MCP servers
+  let resolvedFsPath = null;
   if (config.mcpServers && Object.keys(config.mcpServers).length > 0) {
+    console.log('\n🔌 MCP Servers');
     if (!settings.mcpServers) settings.mcpServers = {};
+
+    // Resolve filesystem server path interactively
+    const home = getDefaultHome();
+    const os = platform();
+    const osLabel = os === 'win32' ? 'Windows' : os === 'darwin' ? 'macOS' : 'Linux/WSL';
+
     for (const [name, serverConfig] of Object.entries(config.mcpServers)) {
+      if (name === 'filesystem' && !flags.dryRun) {
+        console.log(`\n  Detected OS: ${osLabel}`);
+        console.log(`  Default filesystem path: ${home}`);
+        const answer = await prompt(`  Use "${home}" as filesystem root? [Y/n/custom path] `);
+
+        if (answer === '' || answer.toLowerCase() === 'y' || answer.toLowerCase() === 'yes') {
+          resolvedFsPath = home;
+          const resolved = JSON.parse(JSON.stringify(serverConfig));
+          resolved.args = resolved.args.map((a) => a === '$HOME' ? home : a);
+          settings.mcpServers[name] = resolved;
+          log('✓', `MCP server "${name}" configured (${home})`);
+        } else if (answer.toLowerCase() === 'n' || answer.toLowerCase() === 'no') {
+          log('⊘', `MCP server "${name}" skipped — configure manually in ~/.claude/settings.json:`);
+          console.log(`      "mcpServers": {`);
+          console.log(`        "filesystem": {`);
+          console.log(`          "command": "npx",`);
+          console.log(`          "args": ["-y", "@modelcontextprotocol/server-filesystem", "/your/path"]`);
+          console.log(`        }`);
+          console.log(`      }`);
+        } else {
+          // User provided a custom path
+          const customPath = answer.replace(/^~/, home);
+          resolvedFsPath = customPath;
+          const resolved = JSON.parse(JSON.stringify(serverConfig));
+          resolved.args = resolved.args.map((a) => a === '$HOME' ? customPath : a);
+          settings.mcpServers[name] = resolved;
+          log('✓', `MCP server "${name}" configured (${customPath})`);
+        }
+        continue;
+      }
+
+      const resolved = resolveHomeInConfig(serverConfig);
       if (flags.dryRun) {
         log('○', `Would configure MCP server "${name}"`);
       } else {
-        settings.mcpServers[name] = serverConfig;
+        settings.mcpServers[name] = resolved;
         log('✓', `MCP server "${name}" configured`);
       }
     }
-  } else {
-    log('●', 'No MCP servers to configure (they come from plugins)');
   }
 
   if (!flags.dryRun) {
     writeJSON(SETTINGS_PATH, settings);
   }
+
+  return resolvedFsPath;
+}
+
+// ─── Codex Config Generation ───────────────────────────────────────────
+
+function tomlValue(val) {
+  if (typeof val === 'string') return `"${val}"`;
+  if (typeof val === 'boolean') return val ? 'true' : 'false';
+  if (typeof val === 'number') return String(val);
+  if (Array.isArray(val)) {
+    const items = val.map(tomlValue);
+    // Use multiline for long arrays
+    if (items.join(', ').length > 60) {
+      return '[\n  ' + items.join(',\n  ') + '\n]';
+    }
+    return '[' + items.join(', ') + ']';
+  }
+  return `"${val}"`;
+}
+
+function generateCodexToml(config, resolvedFsPath) {
+  const codex = config.codex;
+  const home = homedir();
+  const lines = [];
+
+  lines.push(`model = "${codex.model}"`);
+  if (codex.model_reasoning_effort) {
+    lines.push(`model_reasoning_effort = "${codex.model_reasoning_effort}"`);
+  }
+  lines.push('');
+
+  // Generate MCP server sections from the shared config
+  for (const [name, serverConfig] of Object.entries(config.mcpServers || {})) {
+    lines.push(`[mcp_servers.${name}]`);
+    lines.push('enabled = true');
+
+    if (serverConfig.type === 'http' || serverConfig.url) {
+      lines.push(`url = "${serverConfig.url}"`);
+    } else if (serverConfig.command) {
+      let command = serverConfig.command;
+      const args = serverConfig.args || [];
+
+      // For npx commands, resolve to full node/npx path for Codex compatibility
+      let resolvedArgs = args.map((a) => {
+        if (a === '$HOME') return resolvedFsPath || home;
+        return a;
+      });
+
+      lines.push(`command = "${command}"`);
+      if (resolvedArgs.length > 0) {
+        lines.push(`args = ${tomlValue(resolvedArgs)}`);
+      }
+    }
+
+    // Environment variables
+    if (serverConfig.env && Object.keys(serverConfig.env).length > 0) {
+      lines.push('');
+      lines.push(`[mcp_servers.${name}.env]`);
+      for (const [k, v] of Object.entries(serverConfig.env)) {
+        lines.push(`${k} = "${v}"`);
+      }
+    }
+
+    lines.push('');
+  }
+
+  // Skills — point to the shared ~/.claude/skills directory
+  const skillsPath = (codex.skillsPath || '$HOME/.claude/skills').replace(/\$HOME/g, home);
+  lines.push('[[skills.config]]');
+  lines.push(`path = "${skillsPath}"`);
+  lines.push('enabled = true');
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+async function installCodex(config, flags, resolvedFsPath) {
+  if (!config.codex?.enabled) return;
+
+  console.log('\n🤖 Codex');
+
+  const home = homedir();
+  const configPath = (config.codex.configPath || '$HOME/.codex/config.toml').replace(/\$HOME/g, home);
+  const configDir = dirname(configPath);
+
+  if (flags.dryRun) {
+    log('○', `Would generate Codex config at ${configPath}`);
+    log('○', `Model: ${config.codex.model}`);
+    log('○', `Skills path: ~/.claude/skills (shared with Claude Code)`);
+    const mcpCount = Object.keys(config.mcpServers || {}).length;
+    log('○', `MCP servers: ${mcpCount} (same as Claude Code)`);
+    return;
+  }
+
+  const toml = generateCodexToml(config, resolvedFsPath);
+  ensureDir(configDir);
+
+  const exists = existsSync(configPath);
+  if (exists && !flags.force) {
+    const answer = await prompt(`  Codex config exists at ${configPath}. Overwrite? [y/N] `);
+    if (answer.toLowerCase() !== 'y' && answer.toLowerCase() !== 'yes') {
+      log('⊘', 'Codex config skipped (use --force to overwrite)');
+      return;
+    }
+  }
+
+  writeFileSync(configPath, toml);
+  log('✓', `Codex config written to ${configPath}`);
+  log('✓', `Model: ${config.codex.model}`);
+  log('✓', `Skills: ~/.claude/skills (shared with Claude Code)`);
+  log('✓', `MCP servers: ${Object.keys(config.mcpServers || {}).length} configured`);
 }
 
 // ─── Main Install ──────────────────────────────────────────────────────
@@ -379,13 +561,19 @@ export async function install(flags = {}) {
 
   if (!flags.skipPlugins) installPlugins(config, flags);
   if (!flags.skipSkills) installSkills(config, flags);
-  if (!flags.skipSettings) installSettings(config, flags);
+  let resolvedFsPath = null;
+  if (!flags.skipSettings) {
+    resolvedFsPath = await installSettings(config, flags);
+  }
+  if (!flags.skipCodex) {
+    await installCodex(config, flags, resolvedFsPath);
+  }
 
   console.log('\n────────────────────────────────────────────');
   if (flags.dryRun) {
     console.log('  Dry run complete. Run without --dry-run to apply.');
   } else {
-    console.log('  ✓ All done! Restart Claude Code to pick up changes.');
+    console.log('  ✓ All done! Restart Claude Code / Codex to pick up changes.');
   }
   console.log('');
 }