claude-ctx 0.5.0__tar.gz

claude_ctx-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Steve Solun
+
+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.

claude_ctx-0.5.0/PKG-INFO

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: claude-ctx
+Version: 0.5.0
+Summary: Skill and agent recommendation system for Claude Code — knowledge graph, wiki, and intake quality gates
+Author: Steve Solun
+License: MIT
+Project-URL: Homepage, https://stevesolun.github.io/ctx/
+Project-URL: Repository, https://github.com/stevesolun/ctx
+Project-URL: Documentation, https://stevesolun.github.io/ctx/
+Project-URL: Changelog, https://github.com/stevesolun/ctx/blob/main/CHANGELOG.md
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: networkx<4,>=3
+Requires-Dist: numpy<3,>=1.24
+Requires-Dist: plotly<7,>=5
+Requires-Dist: pyyaml<7,>=6
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Provides-Extra: embeddings
+Requires-Dist: sentence-transformers<4,>=2; extra == "embeddings"
+Requires-Dist: torch<3,>=2; extra == "embeddings"
+Dynamic: license-file
+
+# ctx — Skill & Agent Recommendation for Claude Code
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/Python-3.11+-green.svg)](https://python.org)
+[![PyPI](https://img.shields.io/pypi/v/claude-ctx.svg)](https://pypi.org/project/claude-ctx/)
+[![Tests](https://img.shields.io/badge/Tests-1363_passing-brightgreen.svg)](#)
+[![Graph](https://img.shields.io/badge/Graph-2,211_nodes_/_642K_edges-red.svg)](graph/)
+[![Docs](https://img.shields.io/badge/docs-MkDocs_Material-blue.svg)](https://stevesolun.github.io/ctx/)
+
+Watches what you develop, walks a knowledge graph of **1,769 skills and 443 agents** (2,212 nodes, 885 edges, 865 communities), and recommends the right ones on the fly — you decide what to load and unload. Powered by a Karpathy LLM wiki with persistent memory that gets smarter every session.
+
+## Why it exists
+
+- **Discovery** — with 1,700+ skills and 400+ agents, you can't possibly know which exist or which apply to your current repo.
+- **Context budget** — loading everything wastes tokens and degrades quality. You need the right 10–15 per session.
+- **Skill rot** — skills you installed months ago and never used are cluttering context. Stale ones should be flagged automatically.
+
+## Install
+
+```bash
+pip install claude-ctx
+ctx-init --hooks            # one-shot setup: directories, hooks, starter toolboxes
+```
+
+Optional extras: `pip install "claude-ctx[embeddings]"` for the semantic backend, `pip install "claude-ctx[dev]"` for the test toolchain.
+
+### Pre-built knowledge graph (optional)
+
+A pre-built knowledge graph of 2,211 nodes and 642K edges ships as a tarball. Extract to get a ready-to-use `~/.claude/skill-wiki/`:
+
+```bash
+# after `git clone` — or download graph/wiki-graph.tar.gz from the GitHub release
+mkdir -p ~/.claude/skill-wiki
+tar xzf graph/wiki-graph.tar.gz -C ~/.claude/skill-wiki/
+```
+
+## Use
+
+After install, the `ctx` hooks integrate automatically with Claude Code's `PostToolUse` + `Stop` events. Typical flow:
+
+```bash
+ctx-scan-repo --repo .     # scan current repo, surface recommended skills/agents
+ctx-skill-quality list     # four-signal quality score for every skill
+ctx-skill-quality explain python-patterns   # drill into a single skill
+ctx-skill-health dashboard # structural health + drift detection
+ctx-toolbox run --event pre-commit          # run a council on the current diff
+ctx-monitor serve          # local dashboard: http://127.0.0.1:8765/
+```
+
+The **`ctx-monitor`** dashboard shows currently loaded skills with load/unload buttons, a cytoscape graph view (`/graph?slug=…`), the LLM-wiki entity browser (`/wiki/<slug>`), a filterable skills grid, a session timeline, an audit log viewer, and a live SSE event stream.
+
+Full docs, architecture, and every module: **<https://stevesolun.github.io/ctx/>**
+
+## License
+
+MIT — see [LICENSE](LICENSE).

claude_ctx-0.5.0/README.md

@@ -0,0 +1,56 @@
+# ctx — Skill & Agent Recommendation for Claude Code
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/Python-3.11+-green.svg)](https://python.org)
+[![PyPI](https://img.shields.io/pypi/v/claude-ctx.svg)](https://pypi.org/project/claude-ctx/)
+[![Tests](https://img.shields.io/badge/Tests-1363_passing-brightgreen.svg)](#)
+[![Graph](https://img.shields.io/badge/Graph-2,211_nodes_/_642K_edges-red.svg)](graph/)
+[![Docs](https://img.shields.io/badge/docs-MkDocs_Material-blue.svg)](https://stevesolun.github.io/ctx/)
+
+Watches what you develop, walks a knowledge graph of **1,769 skills and 443 agents** (2,212 nodes, 885 edges, 865 communities), and recommends the right ones on the fly — you decide what to load and unload. Powered by a Karpathy LLM wiki with persistent memory that gets smarter every session.
+
+## Why it exists
+
+- **Discovery** — with 1,700+ skills and 400+ agents, you can't possibly know which exist or which apply to your current repo.
+- **Context budget** — loading everything wastes tokens and degrades quality. You need the right 10–15 per session.
+- **Skill rot** — skills you installed months ago and never used are cluttering context. Stale ones should be flagged automatically.
+
+## Install
+
+```bash
+pip install claude-ctx
+ctx-init --hooks            # one-shot setup: directories, hooks, starter toolboxes
+```
+
+Optional extras: `pip install "claude-ctx[embeddings]"` for the semantic backend, `pip install "claude-ctx[dev]"` for the test toolchain.
+
+### Pre-built knowledge graph (optional)
+
+A pre-built knowledge graph of 2,211 nodes and 642K edges ships as a tarball. Extract to get a ready-to-use `~/.claude/skill-wiki/`:
+
+```bash
+# after `git clone` — or download graph/wiki-graph.tar.gz from the GitHub release
+mkdir -p ~/.claude/skill-wiki
+tar xzf graph/wiki-graph.tar.gz -C ~/.claude/skill-wiki/
+```
+
+## Use
+
+After install, the `ctx` hooks integrate automatically with Claude Code's `PostToolUse` + `Stop` events. Typical flow:
+
+```bash
+ctx-scan-repo --repo .     # scan current repo, surface recommended skills/agents
+ctx-skill-quality list     # four-signal quality score for every skill
+ctx-skill-quality explain python-patterns   # drill into a single skill
+ctx-skill-health dashboard # structural health + drift detection
+ctx-toolbox run --event pre-commit          # run a council on the current diff
+ctx-monitor serve          # local dashboard: http://127.0.0.1:8765/
+```
+
+The **`ctx-monitor`** dashboard shows currently loaded skills with load/unload buttons, a cytoscape graph view (`/graph?slug=…`), the LLM-wiki entity browser (`/wiki/<slug>`), a filterable skills grid, a session timeline, an audit log viewer, and a live SSE event stream.
+
+Full docs, architecture, and every module: **<https://stevesolun.github.io/ctx/>**
+
+## License
+
+MIT — see [LICENSE](LICENSE).

claude_ctx-0.5.0/pyproject.toml

@@ -0,0 +1,133 @@
+[build-system]
+requires = ["setuptools>=42"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "claude-ctx"
+version = "0.5.0"
+description = "Skill and agent recommendation system for Claude Code — knowledge graph, wiki, and intake quality gates"
+authors = [{ name = "Steve Solun" }]
+license = { text = "MIT" }
+readme = "README.md"
+requires-python = ">=3.11"
+
+dependencies = [
+    "networkx>=3,<4",
+    "numpy>=1.24,<3",
+    "plotly>=5,<7",
+    "pyyaml>=6,<7",
+]
+
+[project.urls]
+Homepage = "https://stevesolun.github.io/ctx/"
+Repository = "https://github.com/stevesolun/ctx"
+Documentation = "https://stevesolun.github.io/ctx/"
+Changelog = "https://github.com/stevesolun/ctx/blob/main/CHANGELOG.md"
+
+[project.scripts]
+ctx-init = "ctx_init:main"
+ctx-install-hooks = "inject_hooks:main"
+ctx-monitor = "ctx_monitor:main"
+ctx-scan-repo = "scan_repo:main"
+ctx-skill-quality = "skill_quality:main"
+ctx-skill-health = "skill_health:main"
+ctx-toolbox = "toolbox:main"
+ctx-lifecycle = "ctx_lifecycle:main"
+ctx-skill-add = "skill_add:main"
+ctx-wiki-graphify = "wiki_graphify:main"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-cov>=5",
+    "mypy>=1.8",
+    "ruff>=0.4",
+]
+embeddings = [
+    "sentence-transformers>=2,<4",
+    "torch>=2,<3",
+]
+
+[tool.setuptools]
+# src/ holds ~55 flat top-level modules (scan_repo.py, skill_quality.py, …),
+# not a proper package tree. `packages.find` only discovers directories with
+# __init__.py, so the earlier config packaged only `tests/` and shipped a
+# broken wheel. List every runtime module explicitly via py-modules and tell
+# setuptools to look for them under src/.
+package-dir = {"" = "src"}
+py-modules = [
+    "_file_lock",
+    "_fs_utils",
+    "agent_add",
+    "backup_config",
+    "backup_mirror",
+    "backup_retention",
+    "backup_watchdog",
+    "batch_convert",
+    "behavior_miner",
+    "catalog_builder",
+    "change_detector",
+    "context_monitor",
+    "corpus_cache",
+    "cosine_ranker",
+    "council_runner",
+    "ctx_audit_log",
+    "ctx_config",
+    "ctx_init",
+    "ctx_lifecycle",
+    "ctx_monitor",
+    "embedding_backend",
+    "flatten_agents",
+    "import_strix_skills",
+    "inject_hooks",
+    "intake_gate",
+    "intake_pipeline",
+    "intent_interview",
+    "kpi_dashboard",
+    "link_conversions",
+    "memory_anchor",
+    "quality_signals",
+    "resolve_graph",
+    "resolve_skills",
+    "scan_repo",
+    "skill_add",
+    "skill_add_detector",
+    "skill_category",
+    "skill_health",
+    "skill_loader",
+    "skill_quality",
+    "skill_suggest",
+    "skill_telemetry",
+    "skill_unload",
+    "toolbox",
+    "toolbox_config",
+    "toolbox_hooks",
+    "toolbox_verdict",
+    "update_repo_stats",
+    "usage_tracker",
+    "versions_catalog",
+    "wiki_batch_entities",
+    "wiki_graphify",
+    "wiki_lint",
+    "wiki_orchestrator",
+    "wiki_query",
+    "wiki_sync",
+    "wiki_utils",
+    "wiki_visualize",
+]
+# Do NOT ship the test suite to PyPI. The previous build inadvertently
+# bundled src/tests/ because it was the only directory with __init__.py.
+packages = []
+
+[tool.setuptools.package-data]
+"*" = ["config.json", "skill-registry.json"]
+
+[tool.pytest.ini_options]
+testpaths = ["src/tests"]
+markers = [
+    "integration: marks tests that require external models or network (deselect with -m 'not integration')",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"

claude_ctx-0.5.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

claude_ctx-0.5.0/src/_file_lock.py

@@ -0,0 +1,94 @@
+"""
+_file_lock.py -- Cross-platform advisory file lock.
+
+Used by the toolbox and skill-health modules to serialize read-modify-write
+cycles on shared config/manifest files (e.g. ~/.claude/skill-manifest.json,
+~/.claude/toolbox-runs/<hash>.verdict.json) so that concurrent agent sessions
+do not clobber each other's writes.
+
+Usage:
+
+    with file_lock(manifest_path):
+        data = json.loads(manifest_path.read_text())
+        data["load"].append(...)
+        manifest_path.write_text(json.dumps(data))
+
+The lock is advisory -- it only blocks other callers that also use ``file_lock``.
+It does not protect against processes that ignore locking.
+
+On POSIX we use fcntl.flock (whole-file exclusive). On Windows we use
+msvcrt.locking on the companion .lock file so we don't hold a handle to the
+file the caller is about to replace.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Iterator
+
+if sys.platform == "win32":
+    import msvcrt  # type: ignore[import-not-found]
+else:
+    import fcntl  # type: ignore[import-not-found]
+
+
+@contextmanager
+def file_lock(target: Path, timeout: float = 10.0) -> Iterator[None]:
+    """Acquire an exclusive advisory lock on ``target``.
+
+    Creates ``target.with_suffix(target.suffix + '.lock')`` as the lock
+    file so we don't hold a handle to the target itself (which callers
+    typically replace via ``os.replace``). The lock file is left on disk
+    after release -- it's cheap and avoids a race where two processes
+    both try to create-and-lock at once.
+
+    Raises TimeoutError if the lock cannot be acquired within ``timeout``.
+    """
+    target = Path(target)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    lock_path = target.with_suffix(target.suffix + ".lock")
+    lock_path.touch(exist_ok=True)
+
+    fd = os.open(str(lock_path), os.O_RDWR)
+    try:
+        _acquire(fd, timeout)
+        try:
+            yield
+        finally:
+            _release(fd)
+    finally:
+        os.close(fd)
+
+
+def _acquire(fd: int, timeout: float) -> None:
+    import time
+    deadline = time.monotonic() + max(0.0, timeout)
+    while True:
+        try:
+            if sys.platform == "win32":
+                # Lock 1 byte at offset 0 non-blockingly.
+                msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
+            else:
+                fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+            return
+        except (OSError, BlockingIOError):
+            if time.monotonic() >= deadline:
+                raise TimeoutError("file_lock: timed out acquiring lock")
+            time.sleep(0.05)
+
+
+def _release(fd: int) -> None:
+    try:
+        if sys.platform == "win32":
+            try:
+                os.lseek(fd, 0, os.SEEK_SET)
+                msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)
+            except OSError:
+                pass
+        else:
+            fcntl.flock(fd, fcntl.LOCK_UN)
+    except OSError:
+        pass

claude_ctx-0.5.0/src/_fs_utils.py

@@ -0,0 +1,104 @@
+"""
+_fs_utils.py -- Shared atomic file-write helpers for the ctx project.
+
+Why this exists: 14 modules independently implemented nearly identical
+``_atomic_write`` / ``_atomic_write_text`` private functions, leading to
+subtle divergences (missing Windows retry, missing parent-dir creation,
+predictable temp names).  This module provides a single hardened
+implementation that all of them delegate to.
+
+The ``atomic_write_*`` family writes via a temp file in the same directory
+as the target, then calls ``os.replace()`` which is atomic on POSIX and
+best-effort atomic on Windows.  On Windows, ``os.replace()`` raises
+``PermissionError`` if the destination is held open; we retry 3 times with
+a 50 ms sleep between attempts before re-raising.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+import time
+from pathlib import Path
+from typing import Any
+
+__all__ = ["atomic_write_text", "atomic_write_bytes", "atomic_write_json"]
+
+
+def atomic_write_text(path: Path, text: str, encoding: str = "utf-8") -> None:
+    """Write *text* to *path* atomically.
+
+    Uses a temp file in the same directory so that the final ``os.replace``
+    stays on the same filesystem (avoids cross-device rename failures).
+    Creates parent directories if they are missing.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(prefix=path.name + ".", dir=str(path.parent))
+    try:
+        with os.fdopen(fd, "w", encoding=encoding) as fh:
+            fh.write(text)
+        _replace_with_retry(tmp, path)
+    except Exception:
+        _unlink_silent(tmp)
+        raise
+
+
+def atomic_write_bytes(path: Path, data: bytes) -> None:
+    """Write raw *data* to *path* atomically.
+
+    Same temp-file-in-same-dir + ``os.replace`` strategy as
+    :func:`atomic_write_text`.  Creates parent directories if missing.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(prefix=path.name + ".", dir=str(path.parent))
+    try:
+        with os.fdopen(fd, "wb") as fh:
+            fh.write(data)
+        _replace_with_retry(tmp, path)
+    except Exception:
+        _unlink_silent(tmp)
+        raise
+
+
+def atomic_write_json(path: Path, obj: Any, indent: int | None = 2) -> None:
+    """Serialise *obj* as JSON and write to *path* atomically.
+
+    Produces a trailing newline for clean diffs.  Uses UTF-8 encoding.
+    Creates parent directories if missing.
+    """
+    atomic_write_text(path, json.dumps(obj, indent=indent) + "\n", encoding="utf-8")
+
+
+# ── Internal helpers ──────────────────────────────────────────────────────────
+
+
+def _replace_with_retry(src: str, dst: Path, *, attempts: int = 10, delay: float = 0.05) -> None:
+    """Call ``os.replace(src, dst)``, retrying on ``PermissionError``.
+
+    On POSIX, ``os.replace`` is a single atomic syscall.  On Windows it can
+    raise ``PermissionError`` when another process or thread holds the
+    destination open — or even just a transient AV/indexer read handle.
+    We retry *attempts* times, sleeping *delay* seconds between each try.
+
+    Defaults (10 * 50ms = 500ms max) were tuned after CI flakes under
+    8-thread concurrent writes on windows-latest; 3 * 50ms was not enough
+    under load. 500ms total is still fast for interactive work.
+    """
+    last_exc: Exception | None = None
+    for _ in range(attempts):
+        try:
+            os.replace(src, dst)
+            return
+        except PermissionError as exc:
+            last_exc = exc
+            time.sleep(delay)
+    raise last_exc  # type: ignore[misc]
+
+
+def _unlink_silent(path: str) -> None:
+    """Delete *path* without raising if it is already gone."""
+    try:
+        os.unlink(path)
+    except OSError:
+        pass