agentpick 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 herliansyah
+
+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,130 @@
+# 🎯 agentpick
+
+Detect installed AI coding-agent CLIs on your machine and pick one to launch.
+
+## Usage
+
+```sh
+npx agentpick
+npx agentpick "fix the failing test"   # args are passed through to the chosen agent
+```
+
+- 0 agents detected: prints supported list and custom config instructions
+- 1 agent detected: launches it immediately without menu prompt
+- 2+ agents detected: interactive terminal picker
+
+## Configuration
+
+Add or override agents in `~/.config/agentpick/config.json`:
+
+```json
+{
+  "agents": [
+    { "id": "my-agent", "label": "My Agent", "bin": "my-agent", "args": [] }
+  ]
+}
+```
+
+<!-- cli-end -->
+
+---
+
+## 🌟 Features
+
+- ⚡ **Zero Setup**: Run instantly via `npx agentpick` without pre-installing.
+- 🔍 **Auto-Detection**: Probes your system's `PATH` for installed AI agent CLI binaries.
+- 🚀 **Smart Launching**:
+  - Automatically launches the agent if only one is installed.
+  - Opens a clean interactive terminal menu if multiple agents are detected.
+  - Helpful suggestions if no agents are found.
+- 💬 **Argument Passthrough**: Any trailing arguments or prompts are passed directly to the chosen agent (e.g. `npx agentpick "explain this function"`).
+- 🛠️ **Extensible Registry**: Add custom binaries, proprietary agents, or default CLI arguments via a simple JSON config file.
+
+---
+
+## 📦 Supported Agents (Bundled Registry)
+
+`agentpick` checks for these CLI tools out of the box:
+
+| Agent | Binary (`bin`) |
+| --- | --- |
+| **Claude Code** | `claude` |
+| **Codex CLI** | `codex` |
+| **opencode** | `opencode` |
+| **omp** | `omp` |
+| **pi** | `pi` |
+| **Prime Agent** | `prime-agent` |
+| **Aider** | `aider` |
+| **Gemini CLI** | `gemini` |
+| **Continue** | `cn` |
+| **Goose** | `goose` |
+| **Cursor Agent** | `cursor-agent` |
+| **GitHub Copilot CLI** | `copilot` |
+| **Amazon Q Developer** | `q` |
+| **Sourcegraph Cody** | `cody` |
+| **Hermes** | `hermes` |
+| **Antigravity** | `agy` |
+| **Poolside** | `pool` |
+| **Forge** | `forge` |
+| **CodeWhale** | `codewhale` |
+| **Command Code** | `cmdc` |
+| **Freebuff** | `freebuff` |
+| **Reasonix** | `reasonix` |
+| **Kilo** | `kilo` |
+| **Crush** | `crush` |
+| **Droid** | `droid` |
+
+---
+
+## 🇮🇩 Bahasa Indonesia
+
+### Tentang agentpick
+
+**agentpick** adalah CLI launcher ringan untuk mendeteksi *AI coding-agent* yang sudah terinstall di komputer Anda dan memilih salah satunya untuk dijalankan.
+
+Jika Anda menggunakan beberapa coding assistant sekaligus (misalnya Claude Code untuk arsitektur, Aider untuk refactor cepat, atau Cursor Agent di terminal), `agentpick` memudahkan Anda berganti agent tanpa harus mengingat nama binary masing-masing.
+
+### Cara Penggunaan
+
+Cukup jalankan via `npx`:
+
+```sh
+# Buka menu pemilihan agent interaktif
+npx agentpick
+
+# Jalankan agent terpilih dengan prompt langsung
+npx agentpick "perbaiki unit test yang gagal"
+```
+
+### Logika Deteksi
+
+- **0 Agent Terdeteksi**: Menampilkan daftar agent yang didukung serta panduan konfigurasi agent kustom.
+- **1 Agent Terdeteksi**: Langsung meluncurkan agent tersebut tanpa menampilkan menu.
+- **2+ Agent Terdeteksi**: Menampilkan menu pemilihan (*interactive picker*) terminal.
+
+### Menambahkan Agent Kustom
+
+Jika agent yang Anda pakai belum ada di daftar bawaan, Anda dapat menambahkannya di `~/.config/agentpick/config.json`:
+
+```json
+{
+  "agents": [
+    { "id": "nama-agent", "label": "Nama Agent", "bin": "nama-binary", "args": [] }
+  ]
+}
+```
+
+---
+
+## Development & Test
+
+Run the test suite:
+
+```sh
+node test/detect.test.js
+```
+
+## License
+
+MIT
+

package/bin/cli.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { detectAgents, CONFIG_PATH } from '../lib/detect.js';
+import { REGISTRY } from '../lib/registry.js';
+import { MENU_ACTIONS } from '../lib/menuActions.js';
+import { selectWithSeparators, isCancel } from '../lib/picker.js';
+
+const passthroughArgs = process.argv.slice(2);
+
+async function main() {
+  const detected = detectAgents();
+
+  if (detected.length === 0) {
+    console.error('No AI coding-agent CLI detected on PATH.\n');
+    console.error('Supported agents:');
+    for (const agent of REGISTRY) console.error(`  - ${agent.label} (${agent.bin})`);
+    console.error(`\nInstall one of the above, or add a custom agent to ${CONFIG_PATH}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const chosen = detected.length === 1 ? detected[0] : await pick(detected);
+  if (!chosen) return; // user cancelled
+
+  run(chosen);
+}
+
+async function pick(detected, initialValue) {
+  console.clear();
+  const id = await selectWithSeparators({
+    message: '🤖 Pick an agent to launch',
+    initialValue,
+    options: [
+      ...detected.map((agent) => ({ value: agent.id, label: agent.label })),
+      { value: '__sep__', label: '──────────', separator: true, disabled: true },
+      ...MENU_ACTIONS.map((action) => ({ value: action.id, label: action.label })),
+    ],
+  });
+  if (isCancel(id)) return null;
+
+  const action = MENU_ACTIONS.find((a) => a.id === id);
+  if (action) {
+    const result = await action.run();
+    if (result.type === 'again') return pick(detected, id); // stay on this action after going back
+    return null; // exit
+  }
+  return detected.find((agent) => agent.id === id);
+}
+
+function run(agent) {
+  const child = spawn(agent.path, [...agent.args, ...passthroughArgs], { stdio: 'inherit' });
+  child.on('exit', (code) => {
+    process.exitCode = code ?? 1;
+  });
+}
+
+main();

package/lib/detect.js

@@ -0,0 +1,35 @@
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { REGISTRY } from './registry.js';
+import { probe } from './probe.js';
+
+const CONFIG_PATH = join(homedir(), '.config', 'agentpick', 'config.json');
+
+// User Registry Override: entries from ~/.config/agentpick/config.json, merged over the bundled Registry by id.
+function loadUserAgents() {
+  try {
+    const raw = readFileSync(CONFIG_PATH, 'utf8');
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed.agents) ? parsed.agents : [];
+  } catch {
+    return []; // no config, bad JSON, or missing agents field: fall back to bundled registry only
+  }
+}
+
+function mergeRegistry() {
+  const byId = new Map(REGISTRY.map((a) => [a.id, a]));
+  for (const override of loadUserAgents()) {
+    if (override && override.id) byId.set(override.id, { args: [], ...override });
+  }
+  return [...byId.values()];
+}
+
+// Detect: probe every Registry entry (bundled + user overrides), return the ones found on PATH.
+export function detectAgents() {
+  return mergeRegistry()
+    .map((agent) => ({ ...agent, path: probe(agent.bin) }))
+    .filter((agent) => agent.path);
+}
+
+export { CONFIG_PATH };

package/lib/menuActions.js

@@ -0,0 +1,25 @@
+import pc from 'picocolors';
+import { showReadmeModal } from './modal.js';
+
+// Menu Action: a non-agent entry in the picker. run() executes the action and returns
+// a result telling pick()'s loop what to do next:
+//   { type: 'again' } -> redraw the menu, cursor back on this action
+//   { type: 'exit' }  -> stop picking, no agent chosen
+export const MENU_ACTIONS = [
+  {
+    id: '__help__',
+    label: 'Help',
+    async run() {
+      await showReadmeModal();
+      return { type: 'again' };
+    },
+  },
+  {
+    id: '__exit__',
+    label: 'Exit',
+    async run() {
+      console.log(pc.dim('Exited.'));
+      return { type: 'exit' };
+    },
+  },
+];

package/lib/modal.js

@@ -0,0 +1,102 @@
+import { readFileSync } from 'node:fs';
+import pc from 'picocolors';
+
+// Word-wrap a plain string to `width` columns, splitting on spaces.
+function wrap(text, width) {
+  const words = text.split(' ');
+  const lines = [];
+  let line = '';
+  for (const word of words) {
+    if (line && (line + ' ' + word).length > width) {
+      lines.push(line);
+      line = word;
+    } else {
+      line = line ? line + ' ' + word : word;
+    }
+  }
+  if (line) lines.push(line);
+  return lines;
+}
+
+// Minimal Markdown -> styled terminal lines. Handles #/##/### headings,
+// fenced code blocks, and bullet lists — enough for a README, not a full parser.
+// ponytail: covers only the Markdown subset agentpick's own README uses; upgrade to a real
+// Markdown-to-ANSI renderer (e.g. marked-terminal) if richer docs need rendering later.
+function renderMarkdown(md, width) {
+  const out = [];
+  let inCode = false;
+  for (const raw of md.split('\n')) {
+    if (raw.startsWith('```')) {
+      inCode = !inCode;
+      continue;
+    }
+    if (inCode) {
+      out.push(pc.white(raw.slice(0, width)));
+      continue;
+    }
+    const heading = raw.match(/^(#{1,3})\s+(.*)/);
+    if (heading) {
+      const text = heading[1].length === 1 ? pc.bold(pc.cyan(heading[2])) : pc.bold(pc.magenta(heading[2]));
+      out.push('', text);
+      continue;
+    }
+    if (raw.trim().startsWith('- ')) {
+      for (const line of wrap(raw.trim().slice(2), width - 2)) out.push(pc.green('•') + ' ' + line);
+      continue;
+    }
+    if (raw.trim() === '') {
+      out.push('');
+      continue;
+    }
+    for (const line of wrap(raw, width)) out.push(line);
+  }
+  return out;
+}
+
+function waitForKey(message) {
+  return new Promise((resolve) => {
+    process.stdout.write(pc.dim(message));
+    const { stdin } = process;
+    const wasRaw = stdin.isRaw;
+    if (stdin.isTTY) stdin.setRawMode(true);
+    stdin.resume();
+    stdin.once('data', () => {
+      if (stdin.isTTY) stdin.setRawMode(wasRaw);
+      stdin.pause();
+      resolve();
+    });
+  });
+}
+
+// Show README.md as a full-screen modal: clear screen, draw a bordered box, wait for a
+// keypress, then clear again so the caller can redraw whatever comes next.
+export async function showReadmeModal() {
+  const width = Math.min((process.stdout.columns || 80) - 4, 100);
+  let text = readFileSync(new URL('../README.md', import.meta.url), 'utf8').trim();
+  const cut = text.indexOf('<!-- cli-end -->');
+  if (cut !== -1) text = text.slice(0, cut).trim();
+  const lines = renderMarkdown(text, width);
+
+  // Body lines are `│ ` + content(width) + ` │`, so the full box width is `width + 4`.
+  // Build the title bar to that same total width so its corners line up with the sides.
+  const boxWidth = width + 4;
+  const title = ' agentpick help ';
+  const dashes = '─'.repeat(Math.max(0, boxWidth - 2 - title.length - 1));
+  const top = pc.cyan('╭─') + pc.bold(title) + pc.cyan(dashes + '╮');
+  const bottom = pc.cyan('╰' + '─'.repeat(boxWidth - 2) + '╯');
+
+  console.clear();
+  console.log(top);
+  for (const line of lines) {
+    const pad = ' '.repeat(Math.max(0, width - stripLen(line)));
+    console.log(pc.cyan('│ ') + line + pad + pc.cyan(' │'));
+  }
+  console.log(bottom);
+  await waitForKey('\n  Press any key to go back…');
+  console.clear();
+}
+
+// Length of a string ignoring ANSI escape codes (picocolors output), for padding.
+function stripLen(s) {
+  return s.replace(/\x1b\[[0-9;]*m/g, '').length;
+}

package/lib/picker.js

@@ -0,0 +1,35 @@
+import { SelectPrompt, isCancel } from '@clack/core';
+import pc from 'picocolors';
+
+const RADIO_ACTIVE = '●';
+const RADIO_INACTIVE = '○';
+const BAR = '│';
+
+// Thin wrapper around @clack/core's SelectPrompt with our own row renderer, so a
+// `separator: true` option renders as plain dim text with no radio bullet — unlike
+// @clack/prompts' built-in select(), which always draws a bullet even when disabled.
+export async function selectWithSeparators({ message, options, initialValue }) {
+  const prompt = new SelectPrompt({
+    options,
+    initialValue,
+    render() {
+      const lines = [pc.cyan('┌  ') + pc.bold(message), pc.cyan(BAR)];
+      for (let i = 0; i < this.options.length; i++) {
+        const opt = this.options[i];
+        const label = opt.label ?? String(opt.value);
+        if (opt.separator) {
+          lines.push(pc.cyan(BAR) + '  ' + pc.dim(label));
+        } else if (i === this.cursor) {
+          lines.push(pc.cyan(BAR) + '  ' + pc.green(RADIO_ACTIVE) + ' ' + label);
+        } else {
+          lines.push(pc.cyan(BAR) + '  ' + pc.dim(RADIO_INACTIVE) + ' ' + pc.dim(label));
+        }
+      }
+      lines.push(pc.cyan('└'));
+      return lines.join('\n');
+    },
+  });
+  return prompt.prompt();
+}
+
+export { isCancel };

package/lib/probe.js

@@ -0,0 +1,24 @@
+import { accessSync, constants } from 'node:fs';
+import { delimiter, join } from 'node:path';
+
+const isWindows = process.platform === 'win32';
+// ponytail: fixed common Windows executable extensions; upgrade to reading %PATHEXT% if a bin needs one not listed here.
+const WIN_EXTS = ['.exe', '.cmd', '.bat', ''];
+
+// Probe: check whether `bin` resolves to an executable file on PATH. Returns the resolved path or null.
+export function probe(bin) {
+  const dirs = (process.env.PATH || '').split(delimiter).filter(Boolean);
+  const exts = isWindows ? WIN_EXTS : [''];
+  for (const dir of dirs) {
+    for (const ext of exts) {
+      const candidate = join(dir, bin + ext);
+      try {
+        accessSync(candidate, constants.X_OK);
+        return candidate;
+      } catch {
+        // not here, keep looking
+      }
+    }
+  }
+  return null;
+}

package/lib/registry.js

@@ -0,0 +1,30 @@
+// Bundled Registry: known AI coding-agent CLIs.
+// id: unique key, label: display name, bin: binary to probe on PATH, args: default invoke args.
+export const REGISTRY = [
+  { id: 'claude', label: 'Claude Code', bin: 'claude', args: [] },
+  { id: 'codex', label: 'Codex CLI', bin: 'codex', args: [] },
+  { id: 'opencode', label: 'opencode', bin: 'opencode', args: [] },
+  { id: 'omp', label: 'omp', bin: 'omp', args: [] },
+  { id: 'pi', label: 'pi', bin: 'pi', args: [] },
+  { id: 'prime-agent', label: 'Prime Agent', bin: 'prime-agent', args: [] },
+  { id: 'aider', label: 'Aider', bin: 'aider', args: [] },
+  { id: 'gemini', label: 'Gemini CLI', bin: 'gemini', args: [] },
+  { id: 'continue', label: 'Continue', bin: 'cn', args: [] },
+  { id: 'goose', label: 'Goose', bin: 'goose', args: [] },
+  { id: 'cursor-agent', label: 'Cursor Agent', bin: 'cursor-agent', args: [] },
+  { id: 'copilot', label: 'GitHub Copilot CLI', bin: 'copilot', args: [] },
+  { id: 'q', label: 'Amazon Q Developer', bin: 'q', args: [] },
+  { id: 'cody', label: 'Sourcegraph Cody', bin: 'cody', args: [] },
+  { id: 'hermes', label: 'Hermes', bin: 'hermes', args: [] },
+  { id: 'antigravity', label: 'Antigravity', bin: 'agy', args: [] },
+  { id: 'poolside', label: 'Poolside', bin: 'pool', args: [] },
+  { id: 'forge', label: 'Forge', bin: 'forge', args: [] },
+  { id: 'codewhale', label: 'CodeWhale', bin: 'codewhale', args: [] },
+  { id: 'command-code', label: 'Command Code', bin: 'cmdc', args: [] },
+  { id: 'freebuff', label: 'Freebuff', bin: 'freebuff', args: [] },
+  { id: 'reasonix', label: 'Reasonix', bin: 'reasonix', args: [] },
+  { id: 'kilo', label: 'Kilo', bin: 'kilo', args: [] },
+  { id: 'crush', label: 'Crush', bin: 'crush', args: [] },
+  { id: 'droid', label: 'Droid', bin: 'droid', args: [] },
+];
+

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "agentpick",
+  "version": "0.1.0",
+  "description": "Detect installed AI coding-agent CLIs and pick one to launch",
+  "type": "module",
+  "bin": {
+    "agentpick": "./bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "lib"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "author": "herliansyah <herliansyah@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/herliansyah/agentpick.git"
+  },
+  "bugs": {
+    "url": "https://github.com/herliansyah/agentpick/issues"
+  },
+  "homepage": "https://github.com/herliansyah/agentpick#readme",
+  "dependencies": {
+    "@clack/prompts": "^1.7.0",
+    "picocolors": "^1.1.1"
+  }
+}