second-advisor 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kenryu42
+
+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,334 @@
+# Second Advisor
+
+[![CI](https://github.com/kenryu42/second-advisor/actions/workflows/ci.yml/badge.svg)](https://github.com/kenryu42/second-advisor/actions/workflows/ci.yml)
+[![Version](https://img.shields.io/github/v/tag/kenryu42/second-advisor?label=version&color=blue)](https://github.com/kenryu42/second-advisor)
+[![Codex](https://img.shields.io/badge/Codex-white)](#supported-advisors)
+[![Claude Code](https://img.shields.io/badge/Claude%20Code-D27656)](#supported-advisors)
+[![OpenCode](https://img.shields.io/badge/OpenCode-black)](#supported-advisors)
+[![Grok](https://img.shields.io/badge/Grok-111111)](#supported-advisors)
+[![Pi](https://img.shields.io/badge/Pi%20Coding-22262E)](#supported-advisors)
+[![Droid](https://img.shields.io/badge/Droid-3DDC84)](#supported-advisors)
+[![Amp](https://img.shields.io/badge/Amp-615CED)](#supported-advisors)
+[![Kimi Code](https://img.shields.io/badge/Kimi%20Code-5587FF)](#supported-advisors)
+[![License: MIT](https://img.shields.io/badge/License-MIT-red.svg)](LICENSE)
+
+`second-advisor` is a small CLI that sends a prompt to another coding CLI for a second opinion. It is intended for review-oriented workflows where your primary agent or editor can ask a configured advisor to inspect substantial work before a final response.
+
+The CLI stores one configured advisor, model or mode, and thinking/effort setting, then builds the correct non-interactive command for that advisor.
+
+## Features
+
+- Interactive initialization with installed advisor detection.
+- Prompt forwarding to supported coding CLIs.
+- Short command alias: `sa`.
+- Debug output for the raw command that will be executed.
+- Doctor command for checking config and advisor executables.
+- Model/mode listing for advisors that expose model discovery.
+- Setup command that appends second-advisor workflow instructions to `AGENTS.md` and/or `CLAUDE.md`.
+
+## Requirements
+
+- Bun
+- At least one supported coding CLI installed on `PATH`
+
+The command entrypoint is `src/index.ts` with `#!/usr/bin/env bun`, so Bun must be available on `PATH` even when using a linked command.
+
+Supported advisors:
+
+| Advisor | Executable | Notes |
+| --- | --- | --- |
+| Claude | `claude` | Uses built-in aliases: `haiku`, `sonnet`, `opus`. |
+| Codex | `codex` | Lists bundled models with `codex debug models --bundled`. |
+| opencode | `opencode` | Lists models with `opencode models`. |
+| Grok | `grok` | Lists models with `grok models`. |
+| Pi | `pi` | Lists models with `pi --list-models`. |
+| Droid | `droid` | Extracts models from `droid exec --help`. |
+| Amp | `amp` | Uses modes: `rush`, `smart`, `deep`. |
+| Kimi | `kimi` | Lists models with `kimi provider list --json`; no thinking setting. |
+
+## Installation
+
+Install dependencies:
+
+```sh
+bun install
+```
+
+Run locally:
+
+```sh
+bun run src/index.ts
+```
+
+For local command usage, link the package so the `bin` entries are available:
+
+```sh
+bun link
+```
+
+Depending on your Bun setup, you may also need Bun's global bin directory on `PATH`.
+
+After linking, both commands point to the same CLI:
+
+```sh
+second-advisor --help
+sa --help
+```
+
+## Quick Start
+
+Initialize the advisor config:
+
+```sh
+second-advisor init
+```
+
+Send a prompt:
+
+```sh
+second-advisor "review this implementation for correctness and missed edge cases"
+```
+
+Use the short alias:
+
+```sh
+sa "say hi"
+```
+
+Print the raw advisor command before running it:
+
+```sh
+second-advisor "say hi" --debug
+```
+
+Example debug output:
+
+```sh
+amp --mode rush --effort low --execute 'say hi'
+```
+
+## Commands
+
+### `second-advisor`
+
+With no arguments, opens the interactive menu. If no config exists, the menu offers initialization. If a config exists, the menu shows current setup and lets you change advisor, model/mode, thinking/effort, list models, or run doctor.
+
+```sh
+second-advisor
+```
+
+### `second-advisor init`
+
+Creates or replaces the config at:
+
+```text
+~/.config/second-advisor/config.json
+```
+
+The initializer detects supported CLIs on `PATH`, asks which advisor to use, then prompts for a model/mode and thinking/effort setting when applicable.
+
+### `second-advisor "<prompt>"`
+
+Runs the configured advisor with the given prompt. The prompt is formed by joining all non-command arguments with spaces.
+
+```sh
+second-advisor "what risks do you see in this change?"
+```
+
+If no config exists, the command exits with an error and asks you to run `second-advisor init`.
+
+The first argument is reserved when it is one of the command names: `init`, `doctor`, `models`, `setup`, or `status`. For example, `second-advisor init` runs initialization instead of sending `init` as a prompt.
+
+### `second-advisor "<prompt>" --debug`
+
+Prints the exact advisor command before executing it.
+
+```sh
+second-advisor "review this diff" --debug
+```
+
+The debug line is written to stderr so advisor stdout remains usable.
+
+### `second-advisor status`
+
+Shows the current config, config file path, and whether the configured advisor executable is present on `PATH`.
+
+```sh
+second-advisor status
+```
+
+### `second-advisor doctor`
+
+Checks installed advisor CLI versions, loads the config, confirms the configured executable exists, and verifies Amp mode validity.
+
+```sh
+second-advisor doctor
+```
+
+### `second-advisor models [advisor]`
+
+Lists models or modes for an advisor.
+
+```sh
+second-advisor models
+second-advisor models amp
+second-advisor models codex
+```
+
+If no advisor is passed, the command uses the configured advisor. Claude and Amp are listed from built-in aliases/modes. Other supported advisors use their model-list commands when available.
+
+During interactive setup, advisors with model-list commands fall back to manual model entry if model discovery does not return choices.
+
+### `second-advisor setup`
+
+Looks for `AGENTS.md` and `CLAUDE.md` in the current working directory and appends the Second Advisor Review instructions to each file found.
+
+```sh
+second-advisor setup
+```
+
+Behavior:
+
+- Updates both files if both exist.
+- Skips a file if it already contains `## Second Advisor Review`.
+- Exits with code `1` if neither `AGENTS.md` nor `CLAUDE.md` exists in the current directory.
+- Does not search parent directories.
+
+The appended block tells agents to ask for a second opinion after substantial work and to use:
+
+```sh
+second-advisor "<review prompt>"
+```
+
+## Configuration
+
+Config is stored at:
+
+```text
+~/.config/second-advisor/config.json
+```
+
+Example Amp config:
+
+```json
+{
+  "advisor": "amp",
+  "model": "rush",
+  "thinking": "low"
+}
+```
+
+Example Kimi config:
+
+```json
+{
+  "advisor": "kimi",
+  "model": "kimi-k2"
+}
+```
+
+Validation rules:
+
+- `advisor` must be one of the supported advisors.
+- Most advisors require `model` and `thinking`.
+- Kimi requires `model` and does not support `thinking`.
+- Claude models must be one of `haiku`, `sonnet`, or `opus`.
+- Claude thinking must be one of `low`, `medium`, `high`, `xhigh`, or `max`.
+- Codex thinking must be one of `low`, `medium`, `high`, or `xhigh`.
+- Pi thinking must be one of `off`, `minimal`, `low`, `medium`, `high`, or `xhigh`.
+- Amp modes must be one of `rush`, `smart`, or `deep`.
+- Amp `rush` supports only `none`, `minimal`, `low`, and `medium` effort.
+
+## Exit Codes
+
+- Prompt execution forwards the configured advisor command's exit code.
+- Prompt execution exits with code `1` when no config exists.
+- `setup` exits with code `1` when neither `AGENTS.md` nor `CLAUDE.md` exists in the current working directory.
+- Unhandled config parse errors are printed by the CLI and exit with code `1`.
+
+## Advisor Command Mapping
+
+`second-advisor` runs advisors non-interactively:
+
+| Advisor | Command shape |
+| --- | --- |
+| Claude | `claude --model <model> --effort <thinking> -p <prompt>` |
+| Codex | `codex exec -m <model> --config model_reasoning_effort=<thinking> <prompt>` |
+| opencode | `opencode run -m <model> --variant <thinking> <prompt>` |
+| Grok | `grok -m <model> --reasoning-effort <thinking> -p <prompt>` |
+| Pi | `pi --model <model> --thinking <thinking> -p <prompt>` |
+| Droid | `droid exec -m <model> --reasoning-effort <thinking> <prompt>` |
+| Amp | `amp --mode <mode> --effort <thinking> --execute <prompt>` |
+| Kimi | `kimi -m <model> -p <prompt>` |
+
+Use `--debug` to inspect the exact command for your current config.
+
+## Development
+
+Install dependencies:
+
+```sh
+bun install
+```
+
+Run the CLI during development:
+
+```sh
+bun run src/index.ts
+```
+
+Or use the project script:
+
+```sh
+bun run sa
+```
+
+Run the full verification suite:
+
+```sh
+bun run check
+```
+
+`bun run check` runs typecheck, Biome lint, Knip, copy-paste detection, and tests.
+
+Useful scripts:
+
+```sh
+bun run test
+bun run test:watch
+bun run typecheck
+bun run lint
+bun run publish:dry-run
+```
+
+## Troubleshooting
+
+### `second-advisor is not initialized`
+
+Run:
+
+```sh
+second-advisor init
+```
+
+### Advisor executable is missing
+
+Make sure the configured advisor CLI is installed and available on `PATH`, then run:
+
+```sh
+second-advisor doctor
+```
+
+If `second-advisor init` reports that no supported coding CLI was found, install one of the supported advisor CLIs or fix your `PATH`.
+
+### Model listing fails
+
+Some advisors depend on their own CLI model-list command. Confirm that advisor is authenticated and that its model-list command works directly.
+
+### Setup cannot find instruction files
+
+`second-advisor setup` only checks the current working directory. Run it from the directory that contains `AGENTS.md` or `CLAUDE.md`.
+
+## License
+
+MIT. See `LICENSE`.

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "second-advisor",
+  "version": "0.1.0",
+  "description": "Ask another coding CLI for a second opinion.",
+  "type": "module",
+  "bin": {
+    "second-advisor": "src/index.ts",
+    "sa": "src/index.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "keywords": [
+    "ai",
+    "agent",
+    "cli",
+    "code-review",
+    "codex"
+  ],
+  "author": {
+    "name": "J Liew",
+    "email": "jliew@420024lab.com"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kenryu42/second-advisor.git"
+  },
+  "bugs": {
+    "url": "https://github.com/kenryu42/second-advisor/issues"
+  },
+  "homepage": "https://github.com/kenryu42/second-advisor#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "scripts": {
+    "sa": "bun run src/index.ts",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "coverage": "bun test --coverage",
+    "lint": "biome check .",
+    "lint:ci": "biome ci .",
+    "lint:staged": "biome check --write --",
+    "format": "biome check --write .",
+    "typecheck": "tsc --noEmit",
+    "prepare": "lefthook install",
+    "hooks:install": "lefthook install",
+    "knip": "knip",
+    "cpd": "cpd src tests --reporters ai --exit-code 1 --no-tips",
+    "check": "bun run typecheck && bun run lint && bun run knip && bun run cpd && AGENT=1 bun test",
+    "check:ci": "bun run typecheck && bun run lint:ci && bun run knip && bun run cpd && AGENT=1 bun test --coverage --coverage-reporter=lcov",
+    "publish:dry-run": "bun scripts/publish.ts --dry-run",
+    "changelog": "bun scripts/changelog.ts"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "latest",
+    "@types/bun": "latest",
+    "cpd": "latest",
+    "knip": "latest",
+    "lefthook": "latest",
+    "typescript": "latest"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.6.0",
+    "commander": "^15.0.0"
+  }
+}

package/src/advisors.ts

@@ -0,0 +1,205 @@
+export const advisorChoices = [
+  "claude",
+  "codex",
+  "opencode",
+  "grok",
+  "pi",
+  "droid",
+  "amp",
+  "kimi",
+] as const;
+
+export const ampModes = ["rush", "smart", "deep"] as const;
+export const ampThinking = [
+  "none",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max",
+] as const;
+export const ampThinkingByMode = {
+  deep: ampThinking,
+  rush: ["none", "minimal", "low", "medium"],
+  smart: ampThinking,
+} as const;
+export const claudeModels = ["haiku", "sonnet", "opus"] as const;
+export const claudeThinking = [
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max",
+] as const;
+export const codexThinking = ["low", "medium", "high", "xhigh"] as const;
+export const piThinking = [
+  "off",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+] as const;
+
+export type Advisor = (typeof advisorChoices)[number];
+export type CommandSpec = { command: string; args: string[] };
+type ConfigBase<T extends Advisor> = { advisor: T; model: string };
+type ConfigWithThinking<T extends Advisor, U extends string> = ConfigBase<T> & {
+  thinking: U;
+};
+
+export type Config =
+  | (ConfigWithThinking<"claude", (typeof claudeThinking)[number]> & {
+      model: (typeof claudeModels)[number];
+    })
+  | ConfigWithThinking<"codex", (typeof codexThinking)[number]>
+  | ConfigWithThinking<"opencode", string>
+  | ConfigWithThinking<"grok", string>
+  | ConfigWithThinking<"pi", (typeof piThinking)[number]>
+  | ConfigWithThinking<"droid", string>
+  | {
+      advisor: "amp";
+      model: (typeof ampModes)[number];
+      thinking: (typeof ampThinking)[number];
+    }
+  | ConfigBase<"kimi">;
+
+export function getModelListCommand(advisor: Advisor): CommandSpec | null {
+  if (advisor === "codex")
+    return { command: "codex", args: ["debug", "models", "--bundled"] };
+  if (advisor === "opencode") return { command: "opencode", args: ["models"] };
+  if (advisor === "grok") return { command: "grok", args: ["models"] };
+  if (advisor === "pi") return { command: "pi", args: ["--list-models"] };
+  if (advisor === "droid")
+    return { command: "droid", args: ["exec", "--help"] };
+  if (advisor === "kimi")
+    return { command: "kimi", args: ["provider", "list", "--json"] };
+  return null;
+}
+
+export function buildAdvisorCommand(
+  config: Config,
+  prompt: string,
+): CommandSpec {
+  if (config.advisor === "claude") {
+    return {
+      command: "claude",
+      args: [
+        "--model",
+        config.model,
+        "--effort",
+        config.thinking,
+        "-p",
+        prompt,
+      ],
+    };
+  }
+
+  if (config.advisor === "codex") {
+    return {
+      command: "codex",
+      args: [
+        "exec",
+        "-m",
+        config.model,
+        "--config",
+        `model_reasoning_effort=${config.thinking}`,
+        prompt,
+      ],
+    };
+  }
+
+  if (config.advisor === "opencode") {
+    return {
+      command: "opencode",
+      args: ["run", "-m", config.model, "--variant", config.thinking, prompt],
+    };
+  }
+
+  if (config.advisor === "grok") {
+    return {
+      command: "grok",
+      args: [
+        "-m",
+        config.model,
+        "--reasoning-effort",
+        config.thinking,
+        "-p",
+        prompt,
+      ],
+    };
+  }
+
+  if (config.advisor === "pi") {
+    return {
+      command: "pi",
+      args: [
+        "--model",
+        config.model,
+        "--thinking",
+        config.thinking,
+        "-p",
+        prompt,
+      ],
+    };
+  }
+
+  if (config.advisor === "droid") {
+    return {
+      command: "droid",
+      args: [
+        "exec",
+        "-m",
+        config.model,
+        "--reasoning-effort",
+        config.thinking,
+        prompt,
+      ],
+    };
+  }
+
+  if (config.advisor === "amp") {
+    return {
+      command: "amp",
+      args: [
+        "--mode",
+        config.model,
+        "--effort",
+        config.thinking,
+        "--execute",
+        prompt,
+      ],
+    };
+  }
+
+  return { command: "kimi", args: ["-m", config.model, "-p", prompt] };
+}
+
+export function summarizeConfig(config: Config) {
+  if (config.advisor === "amp") {
+    return `advisor amp, mode ${config.model}, thinking ${config.thinking}`;
+  }
+  if (config.advisor === "kimi") return `advisor kimi, model ${config.model}`;
+  return `advisor ${config.advisor}, model ${config.model}, thinking ${config.thinking}`;
+}
+
+export function getThinkingOptions(
+  advisor: Exclude<Advisor, "kimi">,
+  model?: string,
+) {
+  if (advisor === "claude") return [...claudeThinking];
+  if (advisor === "codex") return [...codexThinking];
+  if (advisor === "pi") return [...piThinking];
+  if (advisor === "amp") {
+    if (model && model in ampThinkingByMode) {
+      return [...ampThinkingByMode[model as keyof typeof ampThinkingByMode]];
+    }
+    return [...ampThinking];
+  }
+  return ["low", "medium", "high", "xhigh"];
+}
+
+export function isAdvisor(value: unknown): value is Advisor {
+  return typeof value === "string" && advisorChoices.includes(value as Advisor);
+}