@minhpnq1807/contextos 0.5.21 → 0.5.24

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.5.24
+
+- **Interactive agent selection:** Replaces the comma-separated text input in `ctx setup` with an interactive multi-select prompt — use ↑/↓ to navigate, Space to toggle agents on/off, and Enter to confirm.
+
+## 0.5.23
+
+- **Fix Windows install paths:** Replaces all `process.env.HOME || process.cwd()` fallbacks with `os.homedir()` across `ctx.js`, `claude-hooks.js`, `antigravity-hooks.js`, `claude-mcp.js`, `antigravity-mcp.js`, and `ruler-sync.js`. On Windows, `HOME` is not set, causing `.codex/`, `.claude/`, and `.gemini/` directories (with full `node_modules` and source code) to be created inside the project tree instead of the user's home directory.
+- **Fix ephemeral MCP server path:** `ctx sync --rules` now resolves the MCP server path from stable install roots (`~/.codex/marketplaces/contextos/`, `~/.ctx/contextos/agents/`) instead of `rootDir`, which may point to a temporary npm extraction directory (e.g. `/tmp/contextos/`) that disappears after cleanup.
+
+## 0.5.22
+
+- Adds `.gitignore` management to `ctx install`: writes inner `.gitignore` (excludes `node_modules/`, `bin/`, `lib/`, `mcp/`) inside installed agent directories and ensures the project root `.gitignore` excludes `.codex/marketplaces/contextos/`, `.claude/settings.json`, and `.gemini/`.
+- Splits the `npm install -g && ctx setup` one-liner into two separate commands in README and LAUNCH docs to avoid shell PATH resolution failures.
+
 ## 0.5.21
 
 - Makes prompt hooks fall back to direct scoring when the `ctx-mcp` bridge socket is missing, stale, or unavailable, avoiding empty `hook context` output.

package/LAUNCH.md

@@ -37,7 +37,8 @@ It supports Codex, Claude Code, and Antigravity. It is local-first and uses loca
 
 Install:
 
-npm install -g @minhpnq1807/contextos && ctx setup
+npm install -g @minhpnq1807/contextos
+ctx setup
 
 Repo: https://github.com/khovan123/contextOS
 ```
@@ -51,7 +52,8 @@ Codex can read AGENTS.md and still ignore the rule that matters.
 
 ContextOS ranks rules per prompt, injects the important ones before work starts, then reports followed / ignored / unknown after the task.
 
-npm install -g @minhpnq1807/contextos && ctx setup
+npm install -g @minhpnq1807/contextos
+ctx setup
 
 https://github.com/khovan123/contextOS
 ```

package/README.md

@@ -49,10 +49,11 @@ Rule outcomes: 8 followed, 0 ignored, 0 unknown
 Runtime telemetry: code-review-graph, code-review-graph.query_graph_tool
 ```
 
-## Install In One Line
+## Quick Install
 
 ```bash
-npm install -g @minhpnq1807/contextos && ctx setup
+npm install -g @minhpnq1807/contextos
+ctx setup
 ```
 
 No postinstall surprise: `npm install` only installs the CLI. Setup runs only when you call `ctx setup`.

package/bin/ctx.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import readline from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
@@ -24,10 +25,12 @@ import { installClaudeMcp } from "../plugins/ctx/lib/claude-mcp.js";
 import { installAntigravityHooks } from "../plugins/ctx/lib/antigravity-hooks.js";
 import { installAntigravityMcp } from "../plugins/ctx/lib/antigravity-mcp.js";
 import { syncRules } from "../plugins/ctx/lib/ruler-sync.js";
+import { writeInnerGitignore, ensureRootGitignore } from "../plugins/ctx/lib/gitignore.js";
 import { syncSkills } from "../plugins/ctx/lib/skillshare-sync.js";
 import { scanSkills, warmSkillEmbeddings } from "../plugins/ctx/lib/skill-discoverer.js";
 import { parsePassthroughArgs, runPassthrough } from "../plugins/ctx/lib/passthrough.js";
 import { parseAgentList, parseSetupArgs, setupSummaryLines } from "../plugins/ctx/lib/setup-wizard.js";
+import { multiSelect } from "../plugins/ctx/lib/multi-select.js";
 import { syncWorkflows, warmWorkflowEmbeddings } from "../plugins/ctx/lib/workflow-discoverer.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -162,7 +165,7 @@ function packageVersion() {
 }
 
 function codexHome() {
-  return process.env.CODEX_HOME || path.join(process.env.HOME || process.cwd(), ".codex");
+  return process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
 }
 
 function copyInstall() {
@@ -194,6 +197,9 @@ async function install({ copy = false, inject = true, agent = "codex" } = {}) {
       const hooksPath = installClaudeHooks({ installRoot, injectPromptContext: inject });
       progress.step(40, "installing mcp");
       const mcpConfigPath = installClaudeMcp({ installRoot });
+      progress.step(50, "configuring gitignore");
+      writeInnerGitignore(installRoot);
+      ensureRootGitignore(process.cwd());
       progress.step(55, "warming embeddings");
       const warmResult = await warmInstallEmbeddings();
       progress.done("claude installed");
@@ -218,6 +224,9 @@ async function install({ copy = false, inject = true, agent = "codex" } = {}) {
       const hooksPath = installAntigravityHooks({ installRoot, injectPromptContext: inject });
       progress.step(40, "installing mcp");
       const mcpConfigPaths = installAntigravityMcp({ installRoot });
+      progress.step(50, "configuring gitignore");
+      writeInnerGitignore(installRoot);
+      ensureRootGitignore(process.cwd());
       progress.step(55, "warming embeddings");
       const warmResult = await warmInstallEmbeddings();
       progress.done("agy installed");
@@ -256,6 +265,10 @@ async function install({ copy = false, inject = true, agent = "codex" } = {}) {
     progress.step(60, "installing hooks");
     const hooksPath = installGlobalHooks({ codexHome: codexHome(), marketplaceRoot, injectPromptContext: inject });
 
+    progress.step(65, "configuring gitignore");
+    writeInnerGitignore(marketplaceRoot);
+    ensureRootGitignore(process.cwd());
+
     progress.step(70, "warming embeddings");
     const warmResult = await warmInstallEmbeddings();
     progress.done("codex installed");
@@ -481,23 +494,40 @@ async function setup({ args = [], cwd = process.cwd() } = {}) {
 
   if (interactive) {
     const rl = readline.createInterface({ input, output });
-    try {
-      const proceed = await askSetupYesNo(rl, "Install to this directory?", true);
-      if (!proceed) {
-        console.log("Setup cancelled.");
-        return;
+    const proceed = await askSetupYesNo(rl, "Install to this directory?", true);
+    if (!proceed) {
+      rl.close();
+      console.log("Setup cancelled.");
+      return;
+    }
+    if (!options.agentsProvided) {
+      rl.close();
+      const selected = await multiSelect({
+        message: "Select agents to install:",
+        options: [
+          { label: "Codex",              value: "codex",  selected: options.agents.includes("codex") },
+          { label: "Claude",             value: "claude", selected: options.agents.includes("claude") },
+          { label: "Antigravity (agy)",  value: "agy",    selected: options.agents.includes("agy") }
+        ]
+      });
+      options.agents = selected;
+      const rl2 = readline.createInterface({ input, output });
+      try {
+        options.inject = await askSetupYesNo(rl2, "Enable prompt context injection?", options.inject);
+        options.syncRules = await askSetupYesNo(rl2, "Sync project rules and MCP servers through Ruler?", options.syncRules);
+        options.syncSkills = await askSetupYesNo(rl2, "Sync skills through skillshare?", options.syncSkills);
+      } finally {
+        rl2.close();
       }
-      if (!options.agentsProvided) {
-        const agents = await askSetupQuestion(rl, "Install for agents? comma-separated", options.agents.join(","));
-        options.agents = parseAgentList(agents);
-      } else {
+    } else {
+      try {
         console.log(`◇ Install for agents:\n│  ${options.agents.join(", ")}`);
+        options.inject = await askSetupYesNo(rl, "Enable prompt context injection?", options.inject);
+        options.syncRules = await askSetupYesNo(rl, "Sync project rules and MCP servers through Ruler?", options.syncRules);
+        options.syncSkills = await askSetupYesNo(rl, "Sync skills through skillshare?", options.syncSkills);
+      } finally {
+        rl.close();
       }
-      options.inject = await askSetupYesNo(rl, "Enable prompt context injection?", options.inject);
-      options.syncRules = await askSetupYesNo(rl, "Sync project rules and MCP servers through Ruler?", options.syncRules);
-      options.syncSkills = await askSetupYesNo(rl, "Sync skills through skillshare?", options.syncSkills);
-    } finally {
-      rl.close();
     }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhpnq1807/contextos",
-  "version": "0.5.21",
+  "version": "0.5.24",
   "description": "Task-aware AGENTS.md context injection and compliance reporting for Codex, Claude Code, and Antigravity.",
   "type": "module",
   "bin": {

package/plugins/ctx/lib/antigravity-hooks.js

@@ -1,4 +1,5 @@
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 
 function shellQuote(value) {
@@ -19,7 +20,7 @@ function commandFor(installRoot, scriptName, { injectPromptContext = true } = {}
 
 export function antigravityHooksPath() {
   return process.env.ANTIGRAVITY_HOOKS_PATH
-    || path.join(process.env.HOME || process.cwd(), ".gemini", "config", "hooks.json");
+    || path.join(os.homedir(), ".gemini", "config", "hooks.json");
 }
 
 export function buildAntigravityHooksConfig(existingConfig, { installRoot, injectPromptContext = true } = {}) {

package/plugins/ctx/lib/antigravity-mcp.js

@@ -1,4 +1,5 @@
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 
 function readJsonFile(filePath, fallback) {
@@ -12,7 +13,7 @@ export function antigravityMcpConfigPaths() {
   if (process.env.ANTIGRAVITY_MCP_CONFIG_PATH) {
     return [process.env.ANTIGRAVITY_MCP_CONFIG_PATH];
   }
-  const home = process.env.HOME || process.cwd();
+  const home = os.homedir();
   return [
     path.join(home, ".gemini", "antigravity", "mcp_config.json"),
     path.join(home, ".gemini", "antigravity-cli", "mcp_config.json"),

package/plugins/ctx/lib/claude-hooks.js

@@ -1,4 +1,5 @@
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 
 import { buildGlobalHooksConfig } from "./global-hooks.js";
@@ -11,7 +12,7 @@ function readJsonFile(filePath, fallback) {
 }
 
 export function claudeHome() {
-  return process.env.CLAUDE_HOME || path.join(process.env.HOME || process.cwd(), ".claude");
+  return process.env.CLAUDE_HOME || path.join(os.homedir(), ".claude");
 }
 
 export function installClaudeHooks({ claudeHome: home = claudeHome(), installRoot, injectPromptContext = true } = {}) {

package/plugins/ctx/lib/claude-mcp.js

@@ -1,4 +1,5 @@
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 
 function readJsonFile(filePath, fallback) {
@@ -9,7 +10,7 @@ function readJsonFile(filePath, fallback) {
 }
 
 export function claudeConfigPath() {
-  return process.env.CLAUDE_CONFIG_PATH || path.join(process.env.HOME || process.cwd(), ".claude.json");
+  return process.env.CLAUDE_CONFIG_PATH || path.join(os.homedir(), ".claude.json");
 }
 
 export function buildClaudeMcpConfig(existingConfig, { installRoot } = {}) {

package/plugins/ctx/lib/gitignore.js

@@ -0,0 +1,69 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Entries to exclude inside the installed contextos directory.
+ * Keeps node_modules, bin, lib, and mcp out of version control.
+ */
+const INNER_GITIGNORE_ENTRIES = [
+  "node_modules/",
+  "bin/",
+  "lib/",
+  "mcp/",
+];
+
+/**
+ * Entries that ctx install should add to the project root .gitignore.
+ *
+ * .codex/marketplaces/contextos/ — Codex agent install dir
+ * .claude/settings.json          — Claude hooks written by ctx install
+ * .gemini/                       — Antigravity hooks/config
+ */
+const ROOT_GITIGNORE_ENTRIES = [
+  ".codex/marketplaces/contextos/",
+  ".claude/settings.json",
+  ".gemini/",
+];
+
+/**
+ * Write a .gitignore inside `dir` that excludes build/runtime artefacts.
+ * Creates the directory if it does not exist yet.
+ */
+export function writeInnerGitignore(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+  const gitignorePath = path.join(dir, ".gitignore");
+  const content = INNER_GITIGNORE_ENTRIES.join("\n") + "\n";
+  fs.writeFileSync(gitignorePath, content, "utf8");
+  return gitignorePath;
+}
+
+/**
+ * Ensure the project root .gitignore exists and contains the entries
+ * needed to keep ctx install artefacts out of version control.
+ *
+ * Only appends entries that are not already present.
+ * Creates the file if it does not exist.
+ */
+export function ensureRootGitignore(projectRoot) {
+  const gitignorePath = path.join(projectRoot, ".gitignore");
+  let existing = "";
+  if (fs.existsSync(gitignorePath)) {
+    existing = fs.readFileSync(gitignorePath, "utf8");
+  }
+
+  const lines = existing.split("\n");
+  const missing = ROOT_GITIGNORE_ENTRIES.filter(
+    (entry) => !lines.some((line) => line.trim() === entry)
+  );
+
+  if (missing.length === 0) return gitignorePath;
+
+  const block = [
+    "",
+    "# ContextOS install artefacts",
+    ...missing,
+  ].join("\n") + "\n";
+
+  fs.writeFileSync(gitignorePath, existing.trimEnd() + "\n" + block, "utf8");
+  return gitignorePath;
+}

package/plugins/ctx/lib/multi-select.js

@@ -0,0 +1,142 @@
+/**
+ * Interactive multi-select prompt using raw stdin.
+ *
+ * Usage:
+ *   const selected = await multiSelect({
+ *     message: "Select agents:",
+ *     options: [
+ *       { label: "Codex",   value: "codex", selected: true },
+ *       { label: "Claude",  value: "claude", selected: true },
+ *       { label: "Antigravity (agy)", value: "agy", selected: true }
+ *     ]
+ *   });
+ */
+
+const KEYS = {
+  UP: ["\x1B[A", "\x1Bk"],       // Arrow Up, Alt+k
+  DOWN: ["\x1B[B", "\x1Bj"],     // Arrow Down, Alt+j
+  SPACE: [" "],
+  ENTER: ["\r", "\n"],
+  CTRL_C: ["\x03"],
+  // j/k vim-style (single char)
+  J: ["j"],
+  K: ["k"]
+};
+
+const DIM = "\x1B[2m";
+const RESET = "\x1B[0m";
+const CYAN = "\x1B[36m";
+const GREEN = "\x1B[32m";
+const BOLD = "\x1B[1m";
+const HIDE_CURSOR = "\x1B[?25l";
+const SHOW_CURSOR = "\x1B[?25h";
+
+function matchKey(data, keySet) {
+  return keySet.some((k) => data === k);
+}
+
+/**
+ * @param {{ message: string, options: Array<{label: string, value: string, selected?: boolean}> }} config
+ * @returns {Promise<string[]>} selected values
+ */
+export function multiSelect({ message, options }) {
+  return new Promise((resolve, reject) => {
+    if (!process.stdin.isTTY) {
+      // Non-interactive: return all pre-selected
+      resolve(options.filter((o) => o.selected).map((o) => o.value));
+      return;
+    }
+
+    let cursor = 0;
+    const selections = options.map((o) => o.selected !== false);
+
+    function render() {
+      // Move cursor up to overwrite previous render (except first time)
+      const lines = [];
+      lines.push(`${CYAN}◇${RESET} ${message}`);
+      lines.push(`${DIM}  Use ↑/↓ to navigate, Space to toggle, Enter to confirm${RESET}`);
+      for (let i = 0; i < options.length; i++) {
+        const isCursor = i === cursor;
+        const isSelected = selections[i];
+        const checkbox = isSelected ? `${GREEN}◉${RESET}` : `${DIM}○${RESET}`;
+        const label = isCursor ? `${BOLD}${CYAN}${options[i].label}${RESET}` : options[i].label;
+        const pointer = isCursor ? `${CYAN}❯${RESET}` : " ";
+        lines.push(`  ${pointer} ${checkbox} ${label}`);
+      }
+      return lines;
+    }
+
+    let prevLineCount = 0;
+
+    function draw() {
+      const lines = render();
+      // Clear previous output
+      if (prevLineCount > 0) {
+        process.stdout.write(`\x1B[${prevLineCount}A`); // move up
+        for (let i = 0; i < prevLineCount; i++) {
+          process.stdout.write("\x1B[2K");  // clear line
+          if (i < prevLineCount - 1) process.stdout.write("\x1B[1B"); // move down
+        }
+        process.stdout.write(`\x1B[${prevLineCount - 1}A`); // back to top
+      }
+      process.stdout.write(lines.join("\n") + "\n");
+      prevLineCount = lines.length;
+    }
+
+    process.stdout.write(HIDE_CURSOR);
+
+    const wasRaw = process.stdin.isRaw;
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    process.stdin.setEncoding("utf8");
+
+    function cleanup() {
+      process.stdin.setRawMode(wasRaw || false);
+      process.stdin.pause();
+      process.stdin.removeListener("data", onData);
+      process.stdout.write(SHOW_CURSOR);
+    }
+
+    function onData(data) {
+      if (matchKey(data, KEYS.CTRL_C)) {
+        cleanup();
+        process.exit(0);
+      }
+
+      if (matchKey(data, KEYS.UP) || matchKey(data, KEYS.K)) {
+        cursor = (cursor - 1 + options.length) % options.length;
+        draw();
+      } else if (matchKey(data, KEYS.DOWN) || matchKey(data, KEYS.J)) {
+        cursor = (cursor + 1) % options.length;
+        draw();
+      } else if (matchKey(data, KEYS.SPACE)) {
+        selections[cursor] = !selections[cursor];
+        draw();
+      } else if (matchKey(data, KEYS.ENTER)) {
+        cleanup();
+        const selected = options
+          .filter((_, i) => selections[i])
+          .map((o) => o.value);
+        // Print final summary
+        const summary = selected.length > 0
+          ? selected.join(", ")
+          : "(none)";
+        // Overwrite prompt area with final state
+        if (prevLineCount > 0) {
+          process.stdout.write(`\x1B[${prevLineCount}A`);
+          for (let i = 0; i < prevLineCount; i++) {
+            process.stdout.write("\x1B[2K");
+            if (i < prevLineCount - 1) process.stdout.write("\x1B[1B");
+          }
+          process.stdout.write(`\x1B[${prevLineCount - 1}A`);
+        }
+        process.stdout.write(`${CYAN}◇${RESET} ${message}\n`);
+        process.stdout.write(`${DIM}│${RESET}  ${GREEN}${summary}${RESET}\n`);
+        resolve(selected);
+      }
+    }
+
+    process.stdin.on("data", onData);
+    draw();
+  });
+}

package/plugins/ctx/lib/ruler-sync.js

@@ -5,9 +5,12 @@ import readline from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 import { execFileSync } from "node:child_process";
 
+import { defaultDataRoot } from "./workspace-data.js";
+
 const DEFAULT_AGENTS = ["codex", "claude", "antigravity"];
 const CTX_MCP_NAME = "ctx-mcp";
 const CONTEXTOS_PROXY_MARKER = "/contextos/plugins/ctx/mcp/proxy.js";
+const MCP_SERVER_RELATIVE = path.join("plugins", "ctx", "mcp", "server.js");
 const AGENT_ALIASES = new Map([
   ["agy", "antigravity"],
   ["antigravity", "antigravity"],
@@ -54,11 +57,11 @@ function displayAgentName(agent) {
 }
 
 function codexConfigPath() {
-  return path.join(process.env.CODEX_HOME || path.join(process.env.HOME || process.cwd(), ".codex"), "config.toml");
+  return path.join(process.env.CODEX_HOME || path.join(os.homedir(), ".codex"), "config.toml");
 }
 
 function claudeUserConfigPath() {
-  return process.env.CLAUDE_CONFIG_PATH || path.join(process.env.HOME || process.cwd(), ".claude.json");
+  return process.env.CLAUDE_CONFIG_PATH || path.join(os.homedir(), ".claude.json");
 }
 
 export function rulerTomlPath(cwd = process.cwd()) {
@@ -273,7 +276,7 @@ function readRulerMcpServer({ tomlPath, name } = {}) {
 }
 
 function antigravityMcpConfigPaths() {
-  const home = process.env.HOME || process.cwd();
+  const home = os.homedir();
   return [
     path.join(home, ".gemini", "antigravity", "mcp_config.json"),
     path.join(home, ".gemini", "antigravity-cli", "mcp_config.json"),
@@ -456,7 +459,7 @@ export function verifySync({ cwd = process.cwd(), agents = DEFAULT_AGENTS } = {}
   const checks = [];
   const definitions = {
     codex: [path.join(cwd, ".codex", "config.toml")],
-    claude: [path.join(cwd, ".mcp.json"), path.join(cwd, ".claude", "settings.json"), path.join(process.env.HOME || "", ".claude.json")],
+    claude: [path.join(cwd, ".mcp.json"), path.join(cwd, ".claude", "settings.json"), path.join(os.homedir(), ".claude.json")],
     antigravity: [
       path.join(cwd, ".gemini", "settings.json"),
       path.join(cwd, ".gemini", "mcp.json"),
@@ -473,6 +476,21 @@ export function verifySync({ cwd = process.cwd(), agents = DEFAULT_AGENTS } = {}
   return checks;
 }
 
+function resolveStableMcpServerPath(rootDir) {
+  const codexRoot = path.join(process.env.CODEX_HOME || path.join(os.homedir(), ".codex"), "marketplaces", "contextos");
+  const dataRoot = defaultDataRoot();
+  const candidates = [
+    path.join(codexRoot, MCP_SERVER_RELATIVE),
+    path.join(dataRoot, "agents", "claude", "contextos", MCP_SERVER_RELATIVE),
+    path.join(dataRoot, "agents", "agy", "contextos", MCP_SERVER_RELATIVE),
+    path.join(rootDir, MCP_SERVER_RELATIVE)
+  ];
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  return path.join(rootDir, MCP_SERVER_RELATIVE);
+}
+
 export async function syncRules({
   cwd = process.cwd(),
   rootDir,
@@ -495,7 +513,7 @@ export async function syncRules({
   const init = ensureRulerInit({ cwd, run, dryRun: options.dryRun });
   logger(statusLine("Checking .ruler/ruler.toml...", init.created ? "✓ created" : "✓ found"));
 
-  const mcpServerPath = path.join(rootDir, "plugins", "ctx", "mcp", "server.js");
+  const mcpServerPath = resolveStableMcpServerPath(rootDir);
   const injected = injectCtxMcp({
     tomlPath: init.tomlPath,
     mcpServerPath,