code-search-cli 0.2.0__tar.gz → 0.3.0__tar.gz

{code_search_cli-0.2.0 → code_search_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-search-cli
-Version: 0.2.0
+Version: 0.3.0
 Summary: Task-aware code search with compact, auditable evidence for coding agents
 Author: Code Search contributors
 License-Expression: Apache-2.0
@@ -9,7 +9,7 @@ Project-URL: Documentation, https://code-search.quguai.cc/
 Project-URL: Repository, https://github.com/quguai/code-search
 Project-URL: Issues, https://github.com/quguai/code-search/issues
 Project-URL: Changelog, https://github.com/quguai/code-search/releases
-Keywords: code-search,code-retrieval,coding-agents,cli,codex
+Keywords: code-search,code-retrieval,coding-agents,agent-skills,cli,codex
 Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
@@ -39,7 +39,7 @@ Dynamic: license-file
   <a href="https://pypi.org/project/code-search-cli/"><img alt="PyPI" src="https://img.shields.io/pypi/v/code-search-cli?style=flat-square" /></a>
   <a href="https://github.com/quguai/code-search/blob/main/LICENSE"><img alt="Apache-2.0 license" src="https://img.shields.io/github/license/quguai/code-search?style=flat-square" /></a>
   <img alt="Python 3.11+" src="https://img.shields.io/badge/Python-3.11%2B-3776AB?style=flat-square&amp;logo=python&amp;logoColor=white" />
-  <img alt="Codex skill included" src="https://img.shields.io/badge/Codex-skill_included-5B47D6?style=flat-square" />
+  <img alt="Agent Skill installers for seven agents" src="https://img.shields.io/badge/Agent_Skills-7_targets-5B47D6?style=flat-square" />
   <img alt="Experimental status" src="https://img.shields.io/badge/status-experimental-D97706?style=flat-square" />
 </p>
 
@@ -91,15 +91,19 @@ index inside it. It incrementally maintains a per-user SQLite index under the op
 directory, honors Git ignore rules for working trees, and uses `code-search clean` to remove the
 cached source snapshot and derived metadata.
 
-### Optional Codex integration
+### Optional agent integration
 
 ```bash
-code-search install
+code-search install                  # Codex remains the default
+code-search install --target cursor  # Or select one target explicitly
 ```
 
-This installs the bundled `code-search` skill into Codex. Restart Codex so it can discover the
-skill. The installer is idempotent and refuses to overwrite a locally modified skill unless
-`--force` is supplied.
+The bundled `code-search` Agent Skill can be installed for Codex, Claude Code, Cursor, Gemini CLI,
+OpenCode, GitHub Copilot, or Kiro. Installation is user-level and idempotent. It tracks hashes of
+the files it installed, so an untouched older release can upgrade safely while a locally modified
+skill is still protected unless `--force` is supplied. Add `--dry-run` to preview the operation.
+The CLI remains the primary interface; installing the skill adds neither an MCP server nor a runtime
+model.
 
 ### Why there is no model underneath
 
@@ -125,7 +129,10 @@ versioned comparison methods; they are not Code Search runtime dependencies.
   default path.
 - Compact exact-symbol windows across all indexed source formats when the whole task is an
   identifier or qualified name.
-- A bundled Codex skill that teaches the agent when to retrieve, expand, or fall back to exact `rg`.
+- A bundled Agent Skill, with user-level filesystem installers for Codex, Claude Code, Cursor,
+  Gemini CLI, OpenCode, GitHub Copilot, and Kiro, that teaches the agent when to retrieve, expand,
+  or fall back to exact `rg`. Their paths, dry-run behavior, idempotence, safe upgrades, and
+  file-protection behavior have automated coverage.
 
 ## Task evidence beyond ranked matches
 
@@ -185,13 +192,52 @@ code-search expand \
   --relation enclosing
 ```
 
-Manage the Codex skill:
+Manage the optional Agent Skill:
 
 ```bash
-code-search install
-code-search uninstall
+code-search install                                  # Codex
+code-search install --target claude-code
+code-search install --target cursor
+code-search install --target gemini
+code-search install --target opencode
+code-search install --target github-copilot
+code-search install --target kiro
+code-search install --target detected                # Best-effort convenience selector
+code-search install --target detected --dry-run      # Preview without writing
+code-search uninstall --target cursor
+code-search uninstall --target detected
 ```
 
+The installer writes only managed Skill files and its hash manifest inside the selected agent's
+user configuration:
+
+| `--target` | User-level destination |
+|---|---|
+| `codex` | `$CODEX_HOME/skills/code-search/` when set; otherwise `~/.agents/skills/code-search/` |
+| `claude-code` | `$CLAUDE_CONFIG_DIR/skills/code-search/` when set; otherwise `~/.claude/skills/code-search/` |
+| `cursor` | `~/.cursor/skills/code-search/` |
+| `gemini` | `$GEMINI_CLI_HOME/.gemini/skills/code-search/` when set; otherwise `~/.gemini/skills/code-search/` |
+| `opencode` | `$OPENCODE_CONFIG_DIR/skills/code-search/` when set; otherwise `${XDG_CONFIG_HOME:-~/.config}/opencode/skills/code-search/` |
+| `github-copilot` | `$COPILOT_HOME/skills/code-search/` when set; otherwise `~/.copilot/skills/code-search/` |
+| `kiro` | `~/.kiro/skills/code-search/` |
+
+Agent-specific environment overrides must be absolute paths; a relative `XDG_CONFIG_HOME` is ignored
+as required by the XDG base-directory specification. An existing legacy Codex installation under
+`~/.codex/skills/code-search/` is updated and removed in place instead of being silently migrated.
+
+`detected` is a best-effort convenience selector based on known commands, configuration directories,
+environment overrides, and an already-installed target. It does not launch a client or verify that
+the client can load the skill. Cursor detection deliberately relies on `~/.cursor` rather than the
+ambiguous `agent` executable name. Because some clients also scan another client's compatibility
+directories, prefer an explicit target and use one if the same skill appears more than once.
+
+Every selected destination is preflighted before writing or removing files. A small hidden manifest
+records hashes of the managed files; it is installer metadata, not another instruction loaded by the
+agent. This lets an untouched older installation upgrade without treating it as a user edit.
+Uninstall removes only managed files whose content is still recognized and leaves extra user files
+in place. Use `--force` only when you intentionally want to replace or remove a modified managed
+file. `--dry-run` performs the same checks and reports the planned action without changing files.
+
 Prewarm, inspect, or remove the per-repository index:
 
 ```bash
@@ -211,7 +257,7 @@ The repository publishes two recorded development comparisons. Both measure
 scores must not be merged into one leaderboard. The shared Java runner reproduces all six methods;
 the multilingual public runner currently reproduces BM25, Probe, and ripgrep, while the other three
 rows retain their recorded implementation identities and per-task output. The Code Search rows
-describe the source revisions recorded by each benchmark, not a new measurement of version 0.2.0.
+describe the source revisions recorded by each benchmark, not a new measurement of the current release.
 
 ### Shared Java comparison
 
@@ -329,7 +375,8 @@ validation remain future work.
   executable patch tests and repeated model runs.
 - **P1, retrieval quality:** close the long-query ranking gaps surfaced by the multilingual
   diagnostic, and add stronger AST/symbol parsers.
-- **P1, onboarding breadth:** add safe CLI/skill installers for more coding agents. Consider MCP only
+- **P1, onboarding validation:** expand beyond the seven current user-level Agent Skill destinations
+  only when another integration has a real discovery path and automated coverage. Consider MCP only
   if a resident index or structured tool discovery provides a measured benefit over CLI invocation.
 - **P2, distribution:** ship signed standalone binaries.
 
@@ -338,7 +385,7 @@ validation remain future work.
 This is a testable experimental MVP, not a production release. The public development benchmark
 measures retrieval, while the deterministic fixtures and tests cover output behavior and package
 quality. None of them proves held-out retrieval superiority or executable patch success. The
-implementation and bundled Codex skill are independently designed around the task-evidence workflow.
+implementation and bundled Agent Skill are independently designed around the task-evidence workflow.
 
 ## License
 

{code_search_cli-0.2.0 → code_search_cli-0.3.0}/README.md

@@ -15,7 +15,7 @@
   <a href="https://pypi.org/project/code-search-cli/"><img alt="PyPI" src="https://img.shields.io/pypi/v/code-search-cli?style=flat-square" /></a>
   <a href="https://github.com/quguai/code-search/blob/main/LICENSE"><img alt="Apache-2.0 license" src="https://img.shields.io/github/license/quguai/code-search?style=flat-square" /></a>
   <img alt="Python 3.11+" src="https://img.shields.io/badge/Python-3.11%2B-3776AB?style=flat-square&amp;logo=python&amp;logoColor=white" />
-  <img alt="Codex skill included" src="https://img.shields.io/badge/Codex-skill_included-5B47D6?style=flat-square" />
+  <img alt="Agent Skill installers for seven agents" src="https://img.shields.io/badge/Agent_Skills-7_targets-5B47D6?style=flat-square" />
   <img alt="Experimental status" src="https://img.shields.io/badge/status-experimental-D97706?style=flat-square" />
 </p>
 
@@ -67,15 +67,19 @@ index inside it. It incrementally maintains a per-user SQLite index under the op
 directory, honors Git ignore rules for working trees, and uses `code-search clean` to remove the
 cached source snapshot and derived metadata.
 
-### Optional Codex integration
+### Optional agent integration
 
 ```bash
-code-search install
+code-search install                  # Codex remains the default
+code-search install --target cursor  # Or select one target explicitly
 ```
 
-This installs the bundled `code-search` skill into Codex. Restart Codex so it can discover the
-skill. The installer is idempotent and refuses to overwrite a locally modified skill unless
-`--force` is supplied.
+The bundled `code-search` Agent Skill can be installed for Codex, Claude Code, Cursor, Gemini CLI,
+OpenCode, GitHub Copilot, or Kiro. Installation is user-level and idempotent. It tracks hashes of
+the files it installed, so an untouched older release can upgrade safely while a locally modified
+skill is still protected unless `--force` is supplied. Add `--dry-run` to preview the operation.
+The CLI remains the primary interface; installing the skill adds neither an MCP server nor a runtime
+model.
 
 ### Why there is no model underneath
 
@@ -101,7 +105,10 @@ versioned comparison methods; they are not Code Search runtime dependencies.
   default path.
 - Compact exact-symbol windows across all indexed source formats when the whole task is an
   identifier or qualified name.
-- A bundled Codex skill that teaches the agent when to retrieve, expand, or fall back to exact `rg`.
+- A bundled Agent Skill, with user-level filesystem installers for Codex, Claude Code, Cursor,
+  Gemini CLI, OpenCode, GitHub Copilot, and Kiro, that teaches the agent when to retrieve, expand,
+  or fall back to exact `rg`. Their paths, dry-run behavior, idempotence, safe upgrades, and
+  file-protection behavior have automated coverage.
 
 ## Task evidence beyond ranked matches
 
@@ -161,13 +168,52 @@ code-search expand \
   --relation enclosing
 ```
 
-Manage the Codex skill:
+Manage the optional Agent Skill:
 
 ```bash
-code-search install
-code-search uninstall
+code-search install                                  # Codex
+code-search install --target claude-code
+code-search install --target cursor
+code-search install --target gemini
+code-search install --target opencode
+code-search install --target github-copilot
+code-search install --target kiro
+code-search install --target detected                # Best-effort convenience selector
+code-search install --target detected --dry-run      # Preview without writing
+code-search uninstall --target cursor
+code-search uninstall --target detected
 ```
 
+The installer writes only managed Skill files and its hash manifest inside the selected agent's
+user configuration:
+
+| `--target` | User-level destination |
+|---|---|
+| `codex` | `$CODEX_HOME/skills/code-search/` when set; otherwise `~/.agents/skills/code-search/` |
+| `claude-code` | `$CLAUDE_CONFIG_DIR/skills/code-search/` when set; otherwise `~/.claude/skills/code-search/` |
+| `cursor` | `~/.cursor/skills/code-search/` |
+| `gemini` | `$GEMINI_CLI_HOME/.gemini/skills/code-search/` when set; otherwise `~/.gemini/skills/code-search/` |
+| `opencode` | `$OPENCODE_CONFIG_DIR/skills/code-search/` when set; otherwise `${XDG_CONFIG_HOME:-~/.config}/opencode/skills/code-search/` |
+| `github-copilot` | `$COPILOT_HOME/skills/code-search/` when set; otherwise `~/.copilot/skills/code-search/` |
+| `kiro` | `~/.kiro/skills/code-search/` |
+
+Agent-specific environment overrides must be absolute paths; a relative `XDG_CONFIG_HOME` is ignored
+as required by the XDG base-directory specification. An existing legacy Codex installation under
+`~/.codex/skills/code-search/` is updated and removed in place instead of being silently migrated.
+
+`detected` is a best-effort convenience selector based on known commands, configuration directories,
+environment overrides, and an already-installed target. It does not launch a client or verify that
+the client can load the skill. Cursor detection deliberately relies on `~/.cursor` rather than the
+ambiguous `agent` executable name. Because some clients also scan another client's compatibility
+directories, prefer an explicit target and use one if the same skill appears more than once.
+
+Every selected destination is preflighted before writing or removing files. A small hidden manifest
+records hashes of the managed files; it is installer metadata, not another instruction loaded by the
+agent. This lets an untouched older installation upgrade without treating it as a user edit.
+Uninstall removes only managed files whose content is still recognized and leaves extra user files
+in place. Use `--force` only when you intentionally want to replace or remove a modified managed
+file. `--dry-run` performs the same checks and reports the planned action without changing files.
+
 Prewarm, inspect, or remove the per-repository index:
 
 ```bash
@@ -187,7 +233,7 @@ The repository publishes two recorded development comparisons. Both measure
 scores must not be merged into one leaderboard. The shared Java runner reproduces all six methods;
 the multilingual public runner currently reproduces BM25, Probe, and ripgrep, while the other three
 rows retain their recorded implementation identities and per-task output. The Code Search rows
-describe the source revisions recorded by each benchmark, not a new measurement of version 0.2.0.
+describe the source revisions recorded by each benchmark, not a new measurement of the current release.
 
 ### Shared Java comparison
 
@@ -305,7 +351,8 @@ validation remain future work.
   executable patch tests and repeated model runs.
 - **P1, retrieval quality:** close the long-query ranking gaps surfaced by the multilingual
   diagnostic, and add stronger AST/symbol parsers.
-- **P1, onboarding breadth:** add safe CLI/skill installers for more coding agents. Consider MCP only
+- **P1, onboarding validation:** expand beyond the seven current user-level Agent Skill destinations
+  only when another integration has a real discovery path and automated coverage. Consider MCP only
   if a resident index or structured tool discovery provides a measured benefit over CLI invocation.
 - **P2, distribution:** ship signed standalone binaries.
 
@@ -314,7 +361,7 @@ validation remain future work.
 This is a testable experimental MVP, not a production release. The public development benchmark
 measures retrieval, while the deterministic fixtures and tests cover output behavior and package
 quality. None of them proves held-out retrieval superiority or executable patch success. The
-implementation and bundled Codex skill are independently designed around the task-evidence workflow.
+implementation and bundled Agent Skill are independently designed around the task-evidence workflow.
 
 ## License
 

{code_search_cli-0.2.0 → code_search_cli-0.3.0}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "code-search-cli"
-version = "0.2.0"
+version = "0.3.0"
 description = "Task-aware code search with compact, auditable evidence for coding agents"
 readme = "README.md"
 requires-python = ">=3.11"
 license = "Apache-2.0"
 authors = [{name = "Code Search contributors"}]
-keywords = ["code-search", "code-retrieval", "coding-agents", "cli", "codex"]
+keywords = ["code-search", "code-retrieval", "coding-agents", "agent-skills", "cli", "codex"]
 dependencies = []
 classifiers = [
     "Development Status :: 3 - Alpha",

{code_search_cli-0.2.0 → code_search_cli-0.3.0}/scripts/e2e_smoke.py

@@ -24,8 +24,13 @@ def main() -> int:
         root = Path(temporary)
         repository = root / "gson"
         environment = os.environ.copy()
+        environment["HOME"] = str(root / "home")
         environment["CODE_SEARCH_CACHE_HOME"] = str(root / "cache")
         environment["CODEX_HOME"] = str(root / "codex")
+        environment["CLAUDE_CONFIG_DIR"] = str(root / "claude")
+        environment["GEMINI_CLI_HOME"] = str(root / "gemini-home")
+        environment["OPENCODE_CONFIG_DIR"] = str(root / "opencode")
+        environment["COPILOT_HOME"] = str(root / "copilot")
 
         _checkout(repository)
         _configure_ignored_sentinel(repository)
@@ -36,10 +41,52 @@ def main() -> int:
         reported_version = _run((*CLI, "--version"), environment=environment)
         _require(reported_version == f"code-search {installed_version}", "CLI version mismatch")
 
+        agent_labels = {
+            "codex": "Codex",
+            "claude-code": "Claude Code",
+            "cursor": "Cursor",
+            "gemini": "Gemini CLI",
+            "opencode": "OpenCode",
+            "github-copilot": "GitHub Copilot",
+            "kiro": "Kiro",
+        }
+        for target, label in agent_labels.items():
+            dry_run = _run(
+                (*CLI, "install", "--target", target, "--dry-run"),
+                environment=environment,
+            )
+            _require(
+                f"{label} skill would be created" in dry_run,
+                f"{label} skill dry-run was not reported",
+            )
+        _require(
+            not list(root.glob("**/skills/code-search")),
+            "skill dry-run wrote files",
+        )
+
         first_install = _run((*CLI, "install"), environment=environment)
         second_install = _run((*CLI, "install"), environment=environment)
-        _require("created" in first_install, "first skill installation was not created")
-        _require("unchanged" in second_install, "second skill installation was not idempotent")
+        _require("Codex skill created" in first_install, "default Codex installation was not created")
+        _require(
+            "Codex skill unchanged" in second_install,
+            "default Codex installation was not idempotent",
+        )
+        for target, label in agent_labels.items():
+            output = _run((*CLI, "install", "--target", target), environment=environment)
+            expected_action = "unchanged" if target == "codex" else "created"
+            _require(
+                f"{label} skill {expected_action}" in output,
+                f"{label} skill installation failed",
+            )
+            repeated = _run((*CLI, "install", "--target", target), environment=environment)
+            _require(
+                f"{label} skill unchanged" in repeated,
+                f"{label} installation was not idempotent",
+            )
+
+        detected = _run((*CLI, "install", "--target", "detected"), environment=environment)
+        for label in agent_labels.values():
+            _require(f"{label} skill unchanged" in detected, f"detected installation missed {label}")
 
         first_index = _json_cli("index", "--repo", repository, "--format", "json", environment=environment)
         _require(first_index["source_files"] > 0, "public repository index is empty")

{code_search_cli-0.2.0 → code_search_cli-0.3.0}/src/code_retrieval/cli.py

@@ -9,7 +9,13 @@ from importlib.metadata import PackageNotFoundError, version
 
 from .engine import RetrievalEngine
 from .index_store import PersistentIndex
-from .installer import install_codex_skill, uninstall_codex_skill
+from .installer import (
+    AGENT_SELECTORS,
+    AgentName,
+    agent_display_name,
+    install_skills,
+    uninstall_skills,
+)
 from .models import Evidence
 from .repository import RETRIEVAL_SCOPES, RepositoryReader
 
@@ -51,11 +57,25 @@ def build_parser() -> argparse.ArgumentParser:
     clean = subparsers.add_parser("clean", help="remove the persistent index for a repository")
     _repository_args(clean)
 
-    install = subparsers.add_parser("install", help="install the bundled Codex skill")
+    install = subparsers.add_parser("install", help="install the bundled skill for a coding agent")
+    install.add_argument(
+        "--target",
+        choices=AGENT_SELECTORS,
+        default="codex",
+        help="agent destination; 'detected' uses best-effort local signals (default: codex)",
+    )
     install.add_argument("--force", action="store_true", help="replace a locally modified installed skill")
-
-    uninstall = subparsers.add_parser("uninstall", help="remove the bundled Codex skill")
+    install.add_argument("--dry-run", action="store_true", help="preview changes without writing files")
+
+    uninstall = subparsers.add_parser("uninstall", help="remove the bundled skill for a coding agent")
+    uninstall.add_argument(
+        "--target",
+        choices=AGENT_SELECTORS,
+        default="codex",
+        help="agent destination; 'detected' uses best-effort local signals (default: codex)",
+    )
     uninstall.add_argument("--force", action="store_true", help="remove a locally modified installed skill")
+    uninstall.add_argument("--dry-run", action="store_true", help="preview changes without removing files")
     return parser
 
 
@@ -63,11 +83,14 @@ def main(argv: list[str] | None = None) -> int:
     args = build_parser().parse_args(argv)
     try:
         if args.command in {"install", "uninstall"}:
-            operation = install_codex_skill if args.command == "install" else uninstall_codex_skill
-            path, action = operation(force=args.force)
-            print(f"Codex skill {action}: {path}")
-            if args.command == "install":
-                print("Restart Codex to load the skill.")
+            operation = install_skills if args.command == "install" else uninstall_skills
+            results = operation(target=args.target, force=args.force, dry_run=args.dry_run)
+            for result in results:
+                action = f"would be {result.action}" if args.dry_run else result.action
+                print(f"{agent_display_name(result.agent)} skill {action}: {result.path}")
+            if args.command == "install" and not args.dry_run:
+                for result in results:
+                    print(_skill_reload_hint(result.agent))
             return 0
 
         if args.command in {"index", "status", "clean"}:
@@ -128,6 +151,16 @@ def _non_empty(value: str) -> str:
     return value
 
 
+def _skill_reload_hint(agent: AgentName) -> str:
+    if agent == "codex":
+        return "Restart Codex if the skill does not appear automatically."
+    if agent == "gemini":
+        return "Run /skills reload in Gemini CLI if the skill does not appear automatically."
+    if agent == "kiro":
+        return "Kiro loads Agent Skills automatically; reopen the session if it is not listed."
+    return f"Restart {agent_display_name(agent)} if the skill does not appear automatically."
+
+
 def _evidence_json(evidence: list[Evidence]) -> str:
     from dataclasses import asdict