cocoindex-code 0.2.37__tar.gz → 0.2.39__tar.gz

{cocoindex_code-0.2.37 → cocoindex_code-0.2.39}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cocoindex-code
-Version: 0.2.37
+Version: 0.2.39
 Summary: MCP server for indexing and querying codebases using CocoIndex
 Project-URL: Homepage, https://github.com/cocoindex-io/cocoindex-code
 Project-URL: Repository, https://github.com/cocoindex-io/cocoindex-code
@@ -107,6 +107,8 @@ Next, set up your [coding agent integration](#coding-agent-integration) — or j
 
 ## Coding Agent Integration
 
+This repository is a **single plugin marketplace** (`.claude-plugin/marketplace.json`) consumed by both **Claude Code** and **Grok** — same plugin id `cocoindex-code`, same `ccc` skill. Grok optionally activates the bundled hooks and MCP server with `--trust`; Claude Code users can install the same marketplace and rely on the skill alone or load hooks/MCP from the plugin as needed.
+
 ### Skill (Recommended)
 
 Install the `ccc` skill so your coding agent automatically uses semantic search when needed:
@@ -126,11 +128,59 @@ Works with [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and oth
 For Claude Code users, this repository is also a [plugin marketplace](https://code.claude.com/docs/en/plugin-marketplaces). Install the skill from inside Claude Code with:
 
 ```text
-/plugin marketplace add Roxabi/cocoindex-code
+/plugin marketplace add cocoindex-io/cocoindex-code
 /plugin install cocoindex-code@cocoindex-code
 ```
 
-This bundles the same `ccc` skill, with version pinning and `/plugin marketplace update` for updates.
+This bundles the same `ccc` skill, with version pinning and `/plugin marketplace update` for updates. The repository also ships `hooks/hooks.json` and `.mcp.json` for Grok (and Claude Code plugin installs that load those files); Claude users who want skill-only search can rely on the skill alone and add MCP manually in the [MCP Server](#mcp-server) section below instead of using the bundled `.mcp.json`.
+
+#### Grok plugin
+
+For [Grok](https://github.com/xai-org/grok) users, install via Grok's plugin system. The plugin bundles three components:
+
+| Component | Purpose |
+|-----------|---------|
+| **Skill** (`skills/ccc/`) | Agent runs `ccc search` / `ccc index` via the CLI (same as Claude Code above) |
+| **Hook** (`hooks/hooks.json`) | `SessionStart` → incremental `ccc index` when `.cocoindex_code/` exists |
+| **MCP** (`.mcp.json`) | `ccc mcp` stdio server — `search` tool with `refresh_index=true` by default |
+
+Grok does **not** import Claude's `enabledPlugins` or plugin cache; install separately even if you already use cocoindex in Claude Code.
+
+**Full install** (skill + hook + MCP):
+
+```bash
+grok plugin marketplace add cocoindex-io/cocoindex-code
+grok plugin install cocoindex-io/cocoindex-code --trust
+grok plugin enable cocoindex-code
+```
+
+Prefer the GitHub shorthand (`cocoindex-io/cocoindex-code`) for install — `grok plugin install cocoindex-code` can fail when no marketplace plugin matches that bare name.
+
+`--trust` is required so Grok activates the plugin's hooks and MCP server (skills load when the plugin is enabled).
+
+**Skill-only** (match Claude Code — no auto-index hook, no MCP tool):
+
+Install and enable as above, then disable the optional components:
+
+1. **Hooks** — open `/hooks`, select the `SessionStart` hook from `cocoindex-code`, press `Space` to disable.
+2. **MCP** — open `/mcps`, select `cocoindex-code`, press `Space` to disable; or persist in `~/.grok/config.toml`:
+
+```toml
+[mcp_servers.cocoindex-code]
+enabled = false
+```
+
+The agent still owns indexing via the `ccc` skill (`ccc index` / `ccc search --refresh` when stale), same as Claude Code.
+
+To avoid importing MCP servers from your Claude/Cursor user config (unrelated to this plugin):
+
+```toml
+[compat.claude]
+mcps = false
+
+[compat.cursor]
+mcps = false
+```
 
 ### MCP Server
 
@@ -178,6 +228,24 @@ Or use opencode.json:
 ```
 </details>
 
+<details>
+<summary>Kilo Code</summary>
+
+Add a local MCP server in `~/.config/kilo/kilo.jsonc`, `kilo.jsonc`, or `.kilo/kilo.jsonc`:
+
+```json
+{
+  "mcp": {
+    "cocoindex-code": {
+      "type": "local",
+      "command": ["ccc", "mcp"],
+      "enabled": true
+    }
+  }
+}
+```
+</details>
+
 Once configured, the agent automatically decides when semantic code search is helpful — finding code by description, exploring unfamiliar codebases, fuzzy/conceptual matches, or locating implementations without knowing exact names.
 
 > **Note:** The `cocoindex-code` command (without subcommand) still works as an MCP server for backward compatibility. It auto-creates settings from environment variables on first run.
@@ -215,7 +283,7 @@ ccc search "authentication logic"       # search!
 
 The background daemon starts automatically on first use.
 
-> **Tip:** `ccc index` auto-initializes if you haven't run `ccc init` yet, so you can skip straight to indexing.
+> **Tip:** You can skip `ccc init` and go straight to `ccc index` — it auto-initializes new projects with default settings. If global settings are missing too (first use on the machine), it walks you through the same model setup as `ccc init` when run interactively; non-interactive runs (scripts, hooks) still require a one-time `ccc init` first.
 
 ### CLI Reference
 
@@ -491,10 +559,15 @@ embedding:
 
 envs:                                                # extra environment variables for the daemon
   OPENAI_API_KEY: your-key                           # only needed if not already in your shell environment
+
+daemon:
+  idle_timeout_minutes: 180                          # optional: exit the daemon after this long without client activity (default 180, 0 = never)
 ```
 
 > **Note:** The daemon inherits your shell environment. If an API key (e.g. `OPENAI_API_KEY`) is already set as an environment variable, you don't need to duplicate it in `envs`. The `envs` field is only for values that aren't in your environment.
 
+> **Idle timeout:** the background daemon holds the embedding model in RAM, so it exits after `daemon.idle_timeout_minutes` without client activity and is restarted automatically on your next `ccc` command or MCP search. A live MCP session sends periodic heartbeats, so the daemon never idles out while your coding agent is connected. Set `0` to keep the daemon running forever.
+
 > **Custom location:** set `COCOINDEX_CODE_DIR` to place `global_settings.yml` somewhere other than `~/.cocoindex_code/` — useful if you want the file to live alongside your projects (e.g. on a synced folder).
 
 #### `indexing_params` / `query_params`
@@ -552,6 +625,14 @@ chunkers:
 
 > `.cocoindex_code/` is automatically added to `.gitignore` during init.
 
+After editing `include_patterns`, `exclude_patterns`, or `language_overrides`:
+
+- Run `ccc doctor` to preview which files match.
+- Run `ccc index` or `ccc search --refresh ...` to update the existing index.
+- You do not need to delete the index or restart the daemon for these file-matching changes.
+
+If you add or change custom `chunkers`, restart the daemon first so the chunker registry is reloaded, then run `ccc index`.
+
 Use `chunkers` when you want to control how a file type is split into chunks before indexing.
 
 `module: example_toml_chunker:toml_chunker` means:
@@ -750,6 +831,7 @@ embedding:
 | cpp | c++ | `.cpp`, `.cc`, `.cxx`, `.h`, `.hpp` |
 | csharp | csharp, cs | `.cs` |
 | css | | `.css`, `.scss` |
+| dart | | `.dart` |
 | dtd | | `.dtd` |
 | fortran | f, f90, f95, f03 | `.f`, `.f90`, `.f95`, `.f03` |
 | go | golang | `.go` |

{cocoindex_code-0.2.37 → cocoindex_code-0.2.39}/README.md

@@ -63,6 +63,8 @@ Next, set up your [coding agent integration](#coding-agent-integration) — or j
 
 ## Coding Agent Integration
 
+This repository is a **single plugin marketplace** (`.claude-plugin/marketplace.json`) consumed by both **Claude Code** and **Grok** — same plugin id `cocoindex-code`, same `ccc` skill. Grok optionally activates the bundled hooks and MCP server with `--trust`; Claude Code users can install the same marketplace and rely on the skill alone or load hooks/MCP from the plugin as needed.
+
 ### Skill (Recommended)
 
 Install the `ccc` skill so your coding agent automatically uses semantic search when needed:
@@ -82,11 +84,59 @@ Works with [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and oth
 For Claude Code users, this repository is also a [plugin marketplace](https://code.claude.com/docs/en/plugin-marketplaces). Install the skill from inside Claude Code with:
 
 ```text
-/plugin marketplace add Roxabi/cocoindex-code
+/plugin marketplace add cocoindex-io/cocoindex-code
 /plugin install cocoindex-code@cocoindex-code
 ```
 
-This bundles the same `ccc` skill, with version pinning and `/plugin marketplace update` for updates.
+This bundles the same `ccc` skill, with version pinning and `/plugin marketplace update` for updates. The repository also ships `hooks/hooks.json` and `.mcp.json` for Grok (and Claude Code plugin installs that load those files); Claude users who want skill-only search can rely on the skill alone and add MCP manually in the [MCP Server](#mcp-server) section below instead of using the bundled `.mcp.json`.
+
+#### Grok plugin
+
+For [Grok](https://github.com/xai-org/grok) users, install via Grok's plugin system. The plugin bundles three components:
+
+| Component | Purpose |
+|-----------|---------|
+| **Skill** (`skills/ccc/`) | Agent runs `ccc search` / `ccc index` via the CLI (same as Claude Code above) |
+| **Hook** (`hooks/hooks.json`) | `SessionStart` → incremental `ccc index` when `.cocoindex_code/` exists |
+| **MCP** (`.mcp.json`) | `ccc mcp` stdio server — `search` tool with `refresh_index=true` by default |
+
+Grok does **not** import Claude's `enabledPlugins` or plugin cache; install separately even if you already use cocoindex in Claude Code.
+
+**Full install** (skill + hook + MCP):
+
+```bash
+grok plugin marketplace add cocoindex-io/cocoindex-code
+grok plugin install cocoindex-io/cocoindex-code --trust
+grok plugin enable cocoindex-code
+```
+
+Prefer the GitHub shorthand (`cocoindex-io/cocoindex-code`) for install — `grok plugin install cocoindex-code` can fail when no marketplace plugin matches that bare name.
+
+`--trust` is required so Grok activates the plugin's hooks and MCP server (skills load when the plugin is enabled).
+
+**Skill-only** (match Claude Code — no auto-index hook, no MCP tool):
+
+Install and enable as above, then disable the optional components:
+
+1. **Hooks** — open `/hooks`, select the `SessionStart` hook from `cocoindex-code`, press `Space` to disable.
+2. **MCP** — open `/mcps`, select `cocoindex-code`, press `Space` to disable; or persist in `~/.grok/config.toml`:
+
+```toml
+[mcp_servers.cocoindex-code]
+enabled = false
+```
+
+The agent still owns indexing via the `ccc` skill (`ccc index` / `ccc search --refresh` when stale), same as Claude Code.
+
+To avoid importing MCP servers from your Claude/Cursor user config (unrelated to this plugin):
+
+```toml
+[compat.claude]
+mcps = false
+
+[compat.cursor]
+mcps = false
+```
 
 ### MCP Server
 
@@ -134,6 +184,24 @@ Or use opencode.json:
 ```
 </details>
 
+<details>
+<summary>Kilo Code</summary>
+
+Add a local MCP server in `~/.config/kilo/kilo.jsonc`, `kilo.jsonc`, or `.kilo/kilo.jsonc`:
+
+```json
+{
+  "mcp": {
+    "cocoindex-code": {
+      "type": "local",
+      "command": ["ccc", "mcp"],
+      "enabled": true
+    }
+  }
+}
+```
+</details>
+
 Once configured, the agent automatically decides when semantic code search is helpful — finding code by description, exploring unfamiliar codebases, fuzzy/conceptual matches, or locating implementations without knowing exact names.
 
 > **Note:** The `cocoindex-code` command (without subcommand) still works as an MCP server for backward compatibility. It auto-creates settings from environment variables on first run.
@@ -171,7 +239,7 @@ ccc search "authentication logic"       # search!
 
 The background daemon starts automatically on first use.
 
-> **Tip:** `ccc index` auto-initializes if you haven't run `ccc init` yet, so you can skip straight to indexing.
+> **Tip:** You can skip `ccc init` and go straight to `ccc index` — it auto-initializes new projects with default settings. If global settings are missing too (first use on the machine), it walks you through the same model setup as `ccc init` when run interactively; non-interactive runs (scripts, hooks) still require a one-time `ccc init` first.
 
 ### CLI Reference
 
@@ -447,10 +515,15 @@ embedding:
 
 envs:                                                # extra environment variables for the daemon
   OPENAI_API_KEY: your-key                           # only needed if not already in your shell environment
+
+daemon:
+  idle_timeout_minutes: 180                          # optional: exit the daemon after this long without client activity (default 180, 0 = never)
 ```
 
 > **Note:** The daemon inherits your shell environment. If an API key (e.g. `OPENAI_API_KEY`) is already set as an environment variable, you don't need to duplicate it in `envs`. The `envs` field is only for values that aren't in your environment.
 
+> **Idle timeout:** the background daemon holds the embedding model in RAM, so it exits after `daemon.idle_timeout_minutes` without client activity and is restarted automatically on your next `ccc` command or MCP search. A live MCP session sends periodic heartbeats, so the daemon never idles out while your coding agent is connected. Set `0` to keep the daemon running forever.
+
 > **Custom location:** set `COCOINDEX_CODE_DIR` to place `global_settings.yml` somewhere other than `~/.cocoindex_code/` — useful if you want the file to live alongside your projects (e.g. on a synced folder).
 
 #### `indexing_params` / `query_params`
@@ -508,6 +581,14 @@ chunkers:
 
 > `.cocoindex_code/` is automatically added to `.gitignore` during init.
 
+After editing `include_patterns`, `exclude_patterns`, or `language_overrides`:
+
+- Run `ccc doctor` to preview which files match.
+- Run `ccc index` or `ccc search --refresh ...` to update the existing index.
+- You do not need to delete the index or restart the daemon for these file-matching changes.
+
+If you add or change custom `chunkers`, restart the daemon first so the chunker registry is reloaded, then run `ccc index`.
+
 Use `chunkers` when you want to control how a file type is split into chunks before indexing.
 
 `module: example_toml_chunker:toml_chunker` means:
@@ -706,6 +787,7 @@ embedding:
 | cpp | c++ | `.cpp`, `.cc`, `.cxx`, `.h`, `.hpp` |
 | csharp | csharp, cs | `.cs` |
 | css | | `.css`, `.scss` |
+| dart | | `.dart` |
 | dtd | | `.dtd` |
 | fortran | f, f90, f95, f03 | `.f`, `.f90`, `.f95`, `.f03` |
 | go | golang | `.go` |

{cocoindex_code-0.2.37 → cocoindex_code-0.2.39}/src/cocoindex_code/_daemon_paths.py

@@ -6,8 +6,11 @@ can import these without pulling in the full daemon stack.
 
 from __future__ import annotations
 
+import json
 import os
 import sys
+import time
+from dataclasses import dataclass
 from pathlib import Path
 
 from .settings import user_settings_dir
@@ -58,3 +61,50 @@ def daemon_pid_path() -> Path:
 def daemon_log_path() -> Path:
     """Return the path for the daemon's log file."""
     return daemon_runtime_dir() / "daemon.log"
+
+
+def daemon_last_exit_path() -> Path:
+    """Return the path for the daemon's graceful-exit marker file."""
+    return daemon_runtime_dir() / "last_exit"
+
+
+@dataclass
+class LastExitMarker:
+    """Record of the most recent *graceful* daemon exit.
+
+    Written by the daemon's graceful shutdown path (``StopRequest``,
+    SIGTERM/SIGINT) and removed again at the next daemon startup. A crashed
+    daemon (SIGKILL, OOM, segfault) never writes it — that absence is how the
+    client tells a crash from a graceful exit.
+    """
+
+    pid: int
+    reason: str
+    timestamp: float
+
+
+def write_last_exit_marker(pid: int, reason: str) -> None:
+    """Persist the graceful-exit marker. Best-effort — never raises."""
+    payload = json.dumps({"pid": pid, "reason": reason, "timestamp": time.time()})
+    try:
+        daemon_last_exit_path().write_text(payload)
+    except OSError:
+        pass
+
+
+def read_last_exit_marker() -> LastExitMarker | None:
+    """Read the graceful-exit marker, or None when absent/unreadable."""
+    try:
+        data = json.loads(daemon_last_exit_path().read_text())
+        return LastExitMarker(
+            pid=int(data["pid"]),
+            reason=str(data["reason"]),
+            timestamp=float(data["timestamp"]),
+        )
+    except (OSError, ValueError, KeyError, TypeError):
+        return None
+
+
+def clear_last_exit_marker() -> None:
+    """Remove the marker (daemon startup) so it always refers to the most recent exit."""
+    daemon_last_exit_path().unlink(missing_ok=True)

{cocoindex_code-0.2.37 → cocoindex_code-0.2.39}/src/cocoindex_code/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.2.37'
-__version_tuple__ = version_tuple = (0, 2, 37)
+__version__ = version = '0.2.39'
+__version_tuple__ = version_tuple = (0, 2, 39)
 
 __commit_id__ = commit_id = None

{cocoindex_code-0.2.37 → cocoindex_code-0.2.39}/src/cocoindex_code/cli.py

@@ -10,6 +10,7 @@ from collections.abc import Callable
 from pathlib import Path
 from typing import TYPE_CHECKING, TypeVar
 
+import msgspec as _msgspec
 import typer as _typer
 
 if TYPE_CHECKING:
@@ -76,22 +77,31 @@ def _apply_host_cwd() -> None:
 # ---------------------------------------------------------------------------
 
 
-def require_project_root() -> Path:
+def require_project_root(*, auto_init: bool = False) -> Path:
     """Find the project root by walking up from CWD.
 
     Checks global settings first (more fundamental), then project settings.
-    Exits with code 1 if either check fails.
+    With ``auto_init``, a missing project is initialized with default settings
+    instead of failing. Missing global settings run the same interactive model
+    setup as ``ccc init`` — but only on a TTY, since picking an embedding model
+    is a consequential choice; non-interactive runs (scripts, hooks, agents)
+    still exit with code 1 rather than silently committing to a default model.
     """
     gs_path = user_settings_path()
     if not gs_path.is_file():
-        _typer.echo(
-            f"Error: Global settings not found: {format_path_for_display(gs_path)}\n"
-            "Run `ccc init` to create it with default settings.",
-            err=True,
-        )
-        raise _typer.Exit(code=1)
+        if auto_init and sys.stdin.isatty():
+            _setup_user_settings_interactive(None)
+        else:
+            _typer.echo(
+                f"Error: Global settings not found: {format_path_for_display(gs_path)}\n"
+                "Run `ccc init` to create it with default settings.",
+                err=True,
+            )
+            raise _typer.Exit(code=1)
     root = find_project_root(Path.cwd())
     if root is None:
+        if auto_init:
+            return _auto_init_project(Path.cwd())
         _typer.echo(
             "Error: Not in an initialized project directory.\n"
             "Run `ccc init` in your project root to get started.",
@@ -101,6 +111,24 @@ def require_project_root() -> Path:
     return root
 
 
+def _auto_init_project(cwd: Path) -> Path:
+    """Create default project settings without an explicit ``ccc init``.
+
+    Anchors at the nearest parent git root when there is one, so running from
+    a repo subdirectory initializes the repo root rather than the subdirectory.
+    """
+    root = find_parent_with_marker(cwd) or cwd
+    _create_project_settings(root)
+    return root
+
+
+def _create_project_settings(root: Path) -> None:
+    """Write default project settings at *root* and gitignore the settings dir."""
+    save_project_settings(root, default_project_settings())
+    add_to_gitignore(root)
+    _typer.echo(f"Created project settings: {format_path_for_display(project_settings_path(root))}")
+
+
 _F = TypeVar("_F", bound=Callable[..., object])
 
 
@@ -599,12 +627,7 @@ def init(
             )
             raise _typer.Exit(code=1)
 
-    # Create project settings
-    save_project_settings(cwd, default_project_settings())
-    _typer.echo(f"Created project settings: {format_path_for_display(settings_file)}")
-
-    # Add to .gitignore
-    add_to_gitignore(cwd)
+    _create_project_settings(cwd)
 
     _typer.echo("You can edit the settings files to customize indexing behavior.")
     _typer.echo("Run `ccc index` to build the index.")
@@ -616,7 +639,7 @@ def index() -> None:
     """Create/update index for the codebase."""
     from . import client as _client
 
-    project_root = str(require_project_root())
+    project_root = str(require_project_root(auto_init=True))
     print_project_header(project_root)
     _run_index_with_progress(project_root)
     print_index_stats(_client.project_status(project_root))
@@ -631,6 +654,7 @@ def search(
     offset: int = _typer.Option(0, "--offset", help="Number of results to skip"),
     limit: int = _typer.Option(10, "--limit", help="Maximum results to return"),
     refresh: bool = _typer.Option(False, "--refresh", help="Refresh index before searching"),
+    json_output: bool = _typer.Option(False, "--json", help="Output results as JSON"),
 ) -> None:
     """Semantic search across the codebase."""
     project_root = str(require_project_root())
@@ -656,7 +680,14 @@ def search(
         limit=limit,
         offset=offset,
     )
-    print_search_results(resp)
+    if json_output:
+        sys.stdout.buffer.write(_msgspec.json.encode(resp))
+        sys.stdout.buffer.write(b"\n")
+        sys.stdout.buffer.flush()
+        if not resp.success:
+            raise _typer.Exit(code=1)
+    else:
+        print_search_results(resp)
 
 
 @app.command()
@@ -994,11 +1025,18 @@ def mcp() -> None:
     project_root = str(require_project_root())
 
     async def _run_mcp() -> None:
-        from .server import create_mcp_server
+        from .server import create_mcp_server, run_heartbeat_loop
 
         mcp_server = create_mcp_server(project_root)
-        asyncio.create_task(_bg_index(project_root))
-        await mcp_server.run_stdio_async()
+        background_tasks = {
+            asyncio.create_task(_bg_index(project_root)),
+            asyncio.create_task(run_heartbeat_loop()),
+        }
+        try:
+            await mcp_server.run_stdio_async()
+        finally:
+            for task in background_tasks:
+                task.cancel()
 
     asyncio.run(_run_mcp())
 
@@ -1028,6 +1066,8 @@ def daemon_status() -> None:
     resp = _client.daemon_status()
     _typer.echo(f"Daemon version: {resp.version}")
     _typer.echo(f"Uptime: {resp.uptime_seconds:.1f}s")
+    timeout_desc = f"{resp.idle_timeout_minutes}m" if resp.idle_timeout_minutes > 0 else "disabled"
+    _typer.echo(f"Idle: {resp.idle_seconds:.1f}s (timeout: {timeout_desc})")
     if resp.projects:
         _typer.echo("Projects:")
         for p in resp.projects: