claude-jump 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 achilledavid
+
+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,87 @@
+# claude-cc
+
+Jump to any project (interactive menu, ranked by how often/recently you use it) and launch [Claude Code](https://claude.com/claude-code) in one command — instead of `cd`-ing there by hand every time.
+
+Built on [`zoxide`](https://github.com/ajeetdsouza/zoxide) (recent/frequent directory tracking) and [`fzf`](https://github.com/junegunn/fzf) (fuzzy interactive menu).
+
+## Install
+
+### Via npm / pnpm / bun (recommended)
+
+```sh
+npm i -g claude-jump
+# or
+pnpm add -g claude-jump
+# or
+bun add -g claude-jump
+```
+
+This installs the `cc`, `cc-scan` and `cc-setup` commands globally, and runs a setup step that installs `fzf` and `zoxide` if missing (via Homebrew / apt / dnf / pacman) and adds the `zoxide` shell hook to your rc file (zsh or bash).
+
+pnpm and bun block install scripts by default for security, so the setup step may not run automatically. If `cc` doesn't work after install, run the setup manually:
+
+```sh
+cc-setup
+```
+
+Then restart your terminal, or run `source ~/.zshrc` (or `~/.bashrc`).
+
+### Via curl (no Node.js required)
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/achilledavid/claude-cc/main/install.sh | bash
+```
+
+This installs `fzf` and `zoxide` if missing, and adds a `cc` shell function to your rc file (zsh or bash). Unlike the npm install, `cc` here is a shell function, not a binary — it can `cd` you into the project directly and keep you there after you quit Claude Code.
+
+Want a different command name (e.g. if `cc` clashes with something on your system, like the C compiler)?
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/achilledavid/claude-cc/main/install.sh | CC_COMMAND=ccd bash
+```
+
+Then restart your terminal, or run `source ~/.zshrc` (or `~/.bashrc`).
+
+## Usage
+
+```sh
+cc              # interactive menu of your projects, launches Claude Code in the one you pick
+cc myproject    # jump straight to the best match for "myproject", no menu
+```
+
+The project list starts empty and fills up naturally as you `cd` around (that's what `zoxide` tracks). To seed it immediately with your existing projects:
+
+```sh
+cc-scan ~/Desktop ~/Documents   # finds every git repo under these paths and adds it to the list
+cc-scan                         # defaults to scanning the current directory
+```
+
+## Uninstall
+
+```sh
+npm uninstall -g claude-jump
+# or
+pnpm remove -g claude-jump
+# or
+bun remove -g claude-jump
+```
+
+This removes the `cc`, `cc-scan` and `cc-setup` commands and the `zoxide` hook block from your shell rc file. `fzf` and `zoxide` themselves are left installed since other tools may use them.
+
+If you installed via curl instead:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/achilledavid/claude-cc/main/uninstall.sh | bash
+```
+
+## How it works
+
+- `zoxide` maintains a frecency-ranked (frequency + recency) database of directories you visit.
+- `cc` opens that list through `fzf` for a fuzzy interactive pick, then launches `claude` in that directory.
+- `cc <name>` skips the menu and jumps to `zoxide`'s best match directly.
+- **npm install**: `cc` is a real binary (`bin/cc.js`), so quitting Claude Code leaves you back where you started — it doesn't persist a `cd` in your shell.
+- **curl install**: `cc` is a shell function sourced from `~/.claude-cc/cc.sh`, so it `cd`s your actual shell into the project and you stay there after quitting Claude Code.
+
+## License
+
+MIT

package/bin/cc-scan.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+'use strict';
+
+const { spawnSync } = require('child_process');
+const path = require('path');
+
+function main() {
+  const roots = process.argv.slice(2);
+  if (roots.length === 0) {
+    roots.push(process.cwd());
+  }
+
+  const find = spawnSync(
+    'find',
+    [...roots, '-maxdepth', '6', '-type', 'd', '-name', '.git', '-not', '-path', '*/node_modules/*'],
+    { encoding: 'utf8' }
+  );
+
+  const gitDirs = (find.stdout || '').split('\n').filter(Boolean);
+  let found = 0;
+  for (const gitDir of gitDirs) {
+    const result = spawnSync('zoxide', ['add', path.dirname(gitDir)]);
+    if (result.status === 0) {
+      found += 1;
+    }
+  }
+
+  console.log(`cc-scan: added ${found} project(s)`);
+}
+
+main();

package/bin/cc-setup.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+'use strict';
+
+process.env.CLAUDE_JUMP_FORCE_SETUP = '1';
+require('../lib/setup').run();

package/bin/cc.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+'use strict';
+
+const { spawnSync } = require('child_process');
+
+function commandExists(cmd) {
+  return spawnSync('which', [cmd]).status === 0;
+}
+
+function requireDeps(deps) {
+  const missing = deps.filter((d) => !commandExists(d));
+  if (missing.length > 0) {
+    console.error(`cc: missing ${missing.join(', ')}. Run: cc-setup`);
+    process.exit(1);
+  }
+}
+
+function pickDirectMatch(args) {
+  const result = spawnSync('zoxide', ['query', '--', ...args], { encoding: 'utf8' });
+  const dir = (result.stdout || '').trim();
+  if (!dir) {
+    console.error(`cc: no match for '${args.join(' ')}'`);
+    process.exit(1);
+  }
+  return dir;
+}
+
+function pickInteractive() {
+  const list = spawnSync('zoxide', ['query', '-l'], { encoding: 'utf8' }).stdout || '';
+  requireDeps(['fzf']);
+  const fzf = spawnSync('fzf', ['--height=50%', '--reverse', '--prompt=Project > '], {
+    input: list,
+    encoding: 'utf8',
+    stdio: ['pipe', 'pipe', 'inherit'],
+  });
+  return (fzf.stdout || '').trim();
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  requireDeps(['zoxide']);
+
+  const dir = args.length > 0 ? pickDirectMatch(args) : pickInteractive();
+  if (!dir) {
+    process.exit(0);
+  }
+
+  if (!commandExists('claude')) {
+    console.error("cc: 'claude' (Claude Code CLI) was not found in PATH.");
+    process.exit(1);
+  }
+
+  const result = spawnSync('claude', [], { cwd: dir, stdio: 'inherit' });
+  process.exit(result.status === null ? 1 : result.status);
+}
+
+main();

package/lib/setup.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+'use strict';
+
+const { spawnSync } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const MARK_START = '# >>> claude-jump >>>';
+const MARK_END = '# <<< claude-jump <<<';
+
+function commandExists(cmd) {
+  return spawnSync('which', [cmd]).status === 0;
+}
+
+function installDeps() {
+  const missing = ['fzf', 'zoxide'].filter((cmd) => !commandExists(cmd));
+  if (missing.length === 0) {
+    console.log('==> fzf and zoxide already installed');
+    return true;
+  }
+
+  console.log(`==> Installing missing dependencies: ${missing.join(', ')}`);
+  const managers = [
+    { cmd: 'brew', args: ['install', ...missing] },
+    { cmd: 'apt-get', args: ['install', '-y', ...missing], needsUpdate: true },
+    { cmd: 'dnf', args: ['install', '-y', ...missing] },
+    { cmd: 'pacman', args: ['-S', '--noconfirm', ...missing] },
+  ];
+
+  for (const mgr of managers) {
+    if (commandExists(mgr.cmd)) {
+      if (mgr.needsUpdate) {
+        spawnSync('sudo', ['apt-get', 'update'], { stdio: 'inherit' });
+      }
+      const useSudo = mgr.cmd !== 'brew';
+      const result = spawnSync(useSudo ? 'sudo' : mgr.cmd, useSudo ? [mgr.cmd, ...mgr.args] : mgr.args, {
+        stdio: 'inherit',
+      });
+      return result.status === 0;
+    }
+  }
+
+  console.log('!! Could not detect a supported package manager (brew/apt/dnf/pacman).');
+  console.log('   Please install manually, then re-run: cc-setup');
+  console.log('   fzf:    https://github.com/junegunn/fzf#installation');
+  console.log('   zoxide: https://github.com/ajeetdsouza/zoxide#installation');
+  return false;
+}
+
+function detectShellName() {
+  return path.basename(process.env.SHELL || 'bash');
+}
+
+function detectRcFile() {
+  const home = os.homedir();
+  switch (detectShellName()) {
+    case 'zsh':
+      return path.join(home, '.zshrc');
+    case 'bash':
+      return path.join(home, '.bashrc');
+    default:
+      return path.join(home, '.profile');
+  }
+}
+
+function addShellHook() {
+  const shellName = detectShellName();
+  const rcFile = detectRcFile();
+
+  let contents = fs.existsSync(rcFile) ? fs.readFileSync(rcFile, 'utf8') : '';
+
+  const startIdx = contents.indexOf(MARK_START);
+  const endIdx = contents.indexOf(MARK_END);
+  if (startIdx !== -1 && endIdx !== -1) {
+    contents = contents.slice(0, startIdx) + contents.slice(endIdx + MARK_END.length);
+  }
+
+  const block = `\n${MARK_START}\neval "$(zoxide init ${shellName})"\n${MARK_END}\n`;
+  fs.writeFileSync(rcFile, contents.replace(/\s*$/, '') + '\n' + block);
+
+  return rcFile;
+}
+
+function run() {
+  if (process.platform !== 'darwin' && process.platform !== 'linux') {
+    console.log('!! claude-jump only supports macOS and Linux.');
+    return;
+  }
+
+  const isGlobal = process.env.npm_config_global === 'true';
+  const forced = process.env.CLAUDE_JUMP_FORCE_SETUP === '1';
+  if (!isGlobal && !forced) {
+    console.log('==> claude-jump: skipping shell setup (not a global install).');
+    console.log('    Install globally instead, or run `cc-setup` by hand:');
+    console.log('    npm i -g claude-jump   /   pnpm add -g claude-jump   /   bun add -g claude-jump');
+    return;
+  }
+
+  console.log('==> Setting up claude-jump');
+  installDeps();
+
+  if (!commandExists('claude')) {
+    console.log("!! Warning: 'claude' (Claude Code CLI) was not found in PATH.");
+    console.log("   claude-jump will still work, but 'cc' needs it to launch anything.");
+  }
+
+  const rcFile = addShellHook();
+
+  console.log('');
+  console.log(`==> Shell hook added to ${rcFile}`);
+  console.log('==> Restart your shell or run: source ' + rcFile);
+  console.log('==> Seed your recent projects:  cc-scan ~/Desktop ~/Documents');
+  console.log('==> Use it:');
+  console.log('      cc            interactive menu');
+  console.log('      cc <name>     jump directly');
+}
+
+module.exports = { run, addShellHook, installDeps, detectRcFile, detectShellName };
+
+if (require.main === module) {
+  run();
+}

package/lib/uninstall.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const { detectRcFile } = require('./setup');
+
+const MARK_START = '# >>> claude-jump >>>';
+const MARK_END = '# <<< claude-jump <<<';
+
+function run() {
+  const rcFile = detectRcFile();
+  if (!fs.existsSync(rcFile)) {
+    return;
+  }
+
+  const contents = fs.readFileSync(rcFile, 'utf8');
+  const startIdx = contents.indexOf(MARK_START);
+  const endIdx = contents.indexOf(MARK_END);
+  if (startIdx === -1 || endIdx === -1) {
+    return;
+  }
+
+  const updated = contents.slice(0, startIdx) + contents.slice(endIdx + MARK_END.length);
+  fs.writeFileSync(rcFile, updated);
+  console.log(`==> Removed claude-jump block from ${rcFile}`);
+  console.log('==> fzf and zoxide themselves were not uninstalled.');
+}
+
+module.exports = { run };
+
+if (require.main === module) {
+  run();
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "claude-jump",
+  "version": "1.0.0",
+  "description": "Jump to any project (interactive menu, ranked by frecency) and launch Claude Code in one command.",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "cli",
+    "zoxide",
+    "fzf",
+    "productivity"
+  ],
+  "homepage": "https://github.com/achilledavid/claude-cc#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/achilledavid/claude-cc.git"
+  },
+  "license": "MIT",
+  "author": "Achille David",
+  "bin": {
+    "cc": "bin/cc.js",
+    "cc-scan": "bin/cc-scan.js",
+    "cc-setup": "bin/cc-setup.js"
+  },
+  "files": [
+    "bin",
+    "lib"
+  ],
+  "scripts": {
+    "postinstall": "node lib/setup.js",
+    "preuninstall": "node lib/uninstall.js"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ]
+}