learnlance 0.1.0__tar.gz

learnlance-0.1.0/LICENSE

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

learnlance-0.1.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: learnlance
+Version: 0.1.0
+Summary: Turn what Claude Code builds into a growing personal knowledge graph.
+Author: aeroscissorz
+License: MIT
+Project-URL: Homepage, https://github.com/aeroscissorz/learnlance
+Project-URL: Repository, https://github.com/aeroscissorz/learnlance
+Project-URL: Issues, https://github.com/aeroscissorz/learnlance/issues
+Keywords: claude,claude-code,learning,knowledge-graph,cli,hooks
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Topic :: Education
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# learnlance 🧠🔍
+
+A learning companion for **Claude Code**. Every time Claude finishes a turn and
+has generated or edited code, learnlance quietly:
+
+1. reads the session transcript and pulls out the code that was just written,
+2. asks Claude *"what concepts could a developer learn from this?"* —
+   e.g. *"you used a **delta function**, here's what delta encoding is"*,
+3. merges those concepts into a **persistent knowledge graph**, and
+4. regenerates an interactive HTML graph you can open any time.
+
+**No API key required.** By default it reuses the `claude` CLI you're already
+logged into (your Claude Code subscription), so there's nothing extra to set up.
+
+So instead of code just appearing, you build up a visual map of everything
+you've picked up along the way — new nodes light up as *🌱 new topics learned*.
+
+## Why it won't slow you down or break your session
+- The API call runs in a **detached background process** — Claude Code never waits.
+- The hook is wrapped so any failure is logged and swallowed; it can never
+  interrupt your coding session.
+- Turns with no substantive code make **no API call** (no cost, no noise).
+
+## Install (no pip, no API key)
+
+```bash
+# just install the Claude Code Stop hook — it uses your logged-in `claude`
+python -m learnlance install
+```
+
+Run this from the `learnlance/` project folder. That's it — start (or restart)
+Claude Code and code as usual.
+
+If `claude` isn't on your PATH, point learnlance at it:
+
+```bash
+python -m learnlance config --claude-bin "C:\path\to\claude.cmd"
+```
+
+> Prefer a global `learnlance` command? `pip install -e .` in this folder, then
+> use `learnlance` instead of `python -m learnlance` everywhere.
+>
+> Prefer a direct API call instead of the CLI? `learnlance config --backend api
+> --set-key sk-ant-...`
+
+## Use it
+
+```bash
+learnlance show      # render + open the interactive knowledge graph in your browser
+learnlance list -v   # list learned concepts (with explanations) in the terminal
+learnlance stats     # quick counts, broken down by category
+```
+
+Per-session markdown recaps are written to `~/.learnlance/insights/<session>.md`.
+
+## Configuration
+
+```bash
+learnlance config                      # show current settings
+learnlance config --cli-model haiku    # make the cli backend use a faster model
+learnlance config --max-topics 3       # fewer concepts per turn
+learnlance config --background off      # run inline (blocks until analysis is done)
+learnlance config --disable             # pause without uninstalling the hook
+learnlance config --backend api --set-key sk-ant-...   # switch to the API backend
+```
+
+Everything lives under `~/.learnlance/`:
+`graph.json` (the graph), `graph.html` (the visualization), `insights/`
+(markdown recaps), `learnlance.log` (diagnostics).
+
+## Uninstall
+
+```bash
+python -m learnlance uninstall
+```
+
+## How it works (internals)
+
+| File | Role |
+|------|------|
+| `hook.py` | Stop-hook entry; spawns the detached worker |
+| `transcript.py` | Parses Claude Code's JSONL transcript for generated code |
+| `insights.py` | Generates insights — via the `claude` CLI (default) or the API |
+| `graph.py` | Merges concepts into the persistent knowledge graph |
+| `viz.py` | Renders the offline, self-contained HTML graph |
+| `install.py` | Wires the hook into `~/.claude/settings.json` |
+
+Zero third-party dependencies by design — the hook must run reliably wherever
+Claude Code launches it.

learnlance-0.1.0/README.md

@@ -0,0 +1,89 @@
+# learnlance 🧠🔍
+
+A learning companion for **Claude Code**. Every time Claude finishes a turn and
+has generated or edited code, learnlance quietly:
+
+1. reads the session transcript and pulls out the code that was just written,
+2. asks Claude *"what concepts could a developer learn from this?"* —
+   e.g. *"you used a **delta function**, here's what delta encoding is"*,
+3. merges those concepts into a **persistent knowledge graph**, and
+4. regenerates an interactive HTML graph you can open any time.
+
+**No API key required.** By default it reuses the `claude` CLI you're already
+logged into (your Claude Code subscription), so there's nothing extra to set up.
+
+So instead of code just appearing, you build up a visual map of everything
+you've picked up along the way — new nodes light up as *🌱 new topics learned*.
+
+## Why it won't slow you down or break your session
+- The API call runs in a **detached background process** — Claude Code never waits.
+- The hook is wrapped so any failure is logged and swallowed; it can never
+  interrupt your coding session.
+- Turns with no substantive code make **no API call** (no cost, no noise).
+
+## Install (no pip, no API key)
+
+```bash
+# just install the Claude Code Stop hook — it uses your logged-in `claude`
+python -m learnlance install
+```
+
+Run this from the `learnlance/` project folder. That's it — start (or restart)
+Claude Code and code as usual.
+
+If `claude` isn't on your PATH, point learnlance at it:
+
+```bash
+python -m learnlance config --claude-bin "C:\path\to\claude.cmd"
+```
+
+> Prefer a global `learnlance` command? `pip install -e .` in this folder, then
+> use `learnlance` instead of `python -m learnlance` everywhere.
+>
+> Prefer a direct API call instead of the CLI? `learnlance config --backend api
+> --set-key sk-ant-...`
+
+## Use it
+
+```bash
+learnlance show      # render + open the interactive knowledge graph in your browser
+learnlance list -v   # list learned concepts (with explanations) in the terminal
+learnlance stats     # quick counts, broken down by category
+```
+
+Per-session markdown recaps are written to `~/.learnlance/insights/<session>.md`.
+
+## Configuration
+
+```bash
+learnlance config                      # show current settings
+learnlance config --cli-model haiku    # make the cli backend use a faster model
+learnlance config --max-topics 3       # fewer concepts per turn
+learnlance config --background off      # run inline (blocks until analysis is done)
+learnlance config --disable             # pause without uninstalling the hook
+learnlance config --backend api --set-key sk-ant-...   # switch to the API backend
+```
+
+Everything lives under `~/.learnlance/`:
+`graph.json` (the graph), `graph.html` (the visualization), `insights/`
+(markdown recaps), `learnlance.log` (diagnostics).
+
+## Uninstall
+
+```bash
+python -m learnlance uninstall
+```
+
+## How it works (internals)
+
+| File | Role |
+|------|------|
+| `hook.py` | Stop-hook entry; spawns the detached worker |
+| `transcript.py` | Parses Claude Code's JSONL transcript for generated code |
+| `insights.py` | Generates insights — via the `claude` CLI (default) or the API |
+| `graph.py` | Merges concepts into the persistent knowledge graph |
+| `viz.py` | Renders the offline, self-contained HTML graph |
+| `install.py` | Wires the hook into `~/.claude/settings.json` |
+
+Zero third-party dependencies by design — the hook must run reliably wherever
+Claude Code launches it.

learnlance-0.1.0/learnlance/__init__.py

@@ -0,0 +1,6 @@
+"""learnlance — a learning companion for Claude Code.
+
+After every Claude Code turn, it extracts the concepts you could learn from the
+code that was generated and grows a personal knowledge graph.
+"""
+__version__ = "0.1.0"

learnlance-0.1.0/learnlance/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

learnlance-0.1.0/learnlance/cli.py

@@ -0,0 +1,176 @@
+"""learnlance command-line interface."""
+from __future__ import annotations
+
+import argparse
+import sys
+import webbrowser
+
+from . import config, graph, hook, insights, install, viz
+
+
+def _cmd_install(args):
+    print(install.install_hook())
+    cfg = config.load_config()
+    backend = cfg.get("backend", "cli")
+    if backend == "cli":
+        if insights.resolve_claude_bin(cfg):
+            print("\nBackend: cli — uses your logged-in `claude` (no API key needed).")
+        else:
+            print("\n⚠  Backend is 'cli' but `claude` wasn't found on PATH.")
+            print("     learnlance config --claude-bin \"C:\\path\\to\\claude.cmd\"")
+    else:
+        if not config.get_api_key(cfg):
+            print("\n⚠  Backend is 'api' but no API key is set:")
+            print("     learnlance config --set-key sk-ant-...   (or export ANTHROPIC_API_KEY)")
+    print("\nDone. New Claude Code sessions will now build your knowledge graph.")
+
+
+def _cmd_uninstall(args):
+    print(install.uninstall_hook())
+
+
+def _cmd_config(args):
+    cfg = config.load_config()
+    changed = False
+    if args.backend is not None:
+        cfg["backend"] = args.backend
+        changed = True
+    if args.claude_bin is not None:
+        cfg["claude_bin"] = args.claude_bin
+        changed = True
+    if args.cli_model is not None:
+        cfg["cli_model"] = args.cli_model
+        changed = True
+    if args.set_key is not None:
+        cfg["api_key"] = args.set_key
+        changed = True
+    if args.model is not None:
+        cfg["model"] = args.model
+        changed = True
+    if args.enable:
+        cfg["enabled"] = True
+        changed = True
+    if args.disable:
+        cfg["enabled"] = False
+        changed = True
+    if args.background is not None:
+        cfg["background"] = args.background == "on"
+        changed = True
+    if args.max_topics is not None:
+        cfg["max_topics_per_turn"] = args.max_topics
+        changed = True
+    if changed:
+        config.save_config(cfg)
+        print("Saved config.")
+    # Show current state (mask the key)
+    shown = dict(cfg)
+    if shown.get("api_key"):
+        shown["api_key"] = shown["api_key"][:7] + "…"
+    key_src = "config" if cfg.get("api_key") else ("env" if config.get_api_key(cfg) else "MISSING")
+    print(f"\nConfig ({config.CONFIG_PATH}):")
+    for k, v in shown.items():
+        print(f"  {k}: {v}")
+    print(f"  api key source: {key_src}")
+
+
+def _cmd_show(args):
+    g = graph.load()
+    path = viz.render_html(g)
+    print(f"Graph written to {path}")
+    if not args.no_open:
+        webbrowser.open(path.as_uri())
+
+
+def _cmd_list(args):
+    g = graph.load()
+    nodes = [n for n in g.get("nodes", {}).values() if not n.get("placeholder")]
+    if not nodes:
+        print("Nothing learned yet. Install the hook and let Claude Code write some code.")
+        return
+    nodes.sort(key=lambda n: (-n.get("count", 0), n["name"].lower()))
+    print(f"{len(nodes)} concepts learned:\n")
+    for n in nodes:
+        print(f"  • {n['name']}  [{n.get('category','')}·{n.get('level','')}]  seen {n.get('count',0)}×")
+        if args.verbose and n.get("explanation"):
+            print(f"      {n['explanation']}")
+
+
+def _cmd_stats(args):
+    g = graph.load()
+    nodes = g.get("nodes", {})
+    real = [n for n in nodes.values() if not n.get("placeholder")]
+    cats: dict[str, int] = {}
+    for n in real:
+        cats[n.get("category", "other")] = cats.get(n.get("category", "other"), 0) + 1
+    print(f"Concepts learned : {len(real)}")
+    print(f"Related links    : {len(g.get('edges', []))}")
+    print(f"Turns analyzed   : {g.get('meta', {}).get('turns', 0)}")
+    print(f"Sessions         : {len(g.get('sessions', {}))}")
+    if cats:
+        print("\nBy category:")
+        for c, n in sorted(cats.items(), key=lambda x: -x[1]):
+            print(f"  {c:18} {n}")
+
+
+def _cmd_hook(args):
+    hook.run_hook()
+
+
+def _cmd_worker(args):
+    hook.run_worker(args.job)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="learnlance",
+        description="Turn what Claude Code builds into a growing knowledge graph.")
+    sub = p.add_subparsers(dest="cmd")
+
+    sub.add_parser("install", help="install the Claude Code Stop hook").set_defaults(func=_cmd_install)
+    sub.add_parser("uninstall", help="remove the Stop hook").set_defaults(func=_cmd_uninstall)
+
+    c = sub.add_parser("config", help="view/set configuration")
+    c.add_argument("--backend", choices=["cli", "api"],
+                   help="cli = use logged-in `claude` (no key); api = Anthropic API")
+    c.add_argument("--claude-bin", dest="claude_bin", metavar="PATH",
+                   help="path to the claude executable (cli backend)")
+    c.add_argument("--cli-model", dest="cli_model", metavar="MODEL",
+                   help="optional model alias for the cli backend, e.g. haiku")
+    c.add_argument("--set-key", dest="set_key", metavar="KEY", help="Anthropic API key (api backend)")
+    c.add_argument("--model", help="model id for the api backend")
+    c.add_argument("--enable", action="store_true")
+    c.add_argument("--disable", action="store_true")
+    c.add_argument("--background", choices=["on", "off"], help="run API work detached")
+    c.add_argument("--max-topics", dest="max_topics", type=int)
+    c.set_defaults(func=_cmd_config)
+
+    s = sub.add_parser("show", help="render + open the HTML knowledge graph")
+    s.add_argument("--no-open", action="store_true", help="just write the file")
+    s.set_defaults(func=_cmd_show)
+
+    l = sub.add_parser("list", help="list learned concepts in the terminal")
+    l.add_argument("-v", "--verbose", action="store_true")
+    l.set_defaults(func=_cmd_list)
+
+    sub.add_parser("stats", help="summary counts").set_defaults(func=_cmd_stats)
+
+    h = sub.add_parser("hook", help="(internal) Stop-hook entry point")
+    h.set_defaults(func=_cmd_hook)
+    w = sub.add_parser("_worker", help=argparse.SUPPRESS)
+    w.add_argument("job")
+    w.set_defaults(func=_cmd_worker)
+
+    return p
+
+
+def main(argv=None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not getattr(args, "func", None):
+        parser.print_help()
+        return 0
+    args.func(args)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

learnlance-0.1.0/learnlance/config.py

@@ -0,0 +1,76 @@
+"""Configuration + on-disk paths for learnlance.
+
+Everything lives under ~/.learnlance (override with LEARNLANCE_HOME).
+No third-party dependencies anywhere in this package on purpose: the hook must
+run reliably in whatever environment Claude Code launches it in.
+"""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+HOME = Path(os.environ.get("LEARNLANCE_HOME", str(Path.home() / ".learnlance")))
+CONFIG_PATH = HOME / "config.json"
+GRAPH_PATH = HOME / "graph.json"
+HTML_PATH = HOME / "graph.html"
+STATE_PATH = HOME / "state.json"
+INSIGHTS_DIR = HOME / "insights"
+WORK_DIR = HOME / "work"
+LOG_PATH = HOME / "learnlance.log"
+
+DEFAULTS = {
+    "enabled": True,
+    # How insights are generated:
+    #   "cli" -> shell out to the `claude` CLI you're already logged into
+    #            (NO API key needed — uses your Claude Code subscription auth).
+    #   "api" -> direct Anthropic API call (needs an API key).
+    "backend": "cli",
+    "claude_bin": "",  # path to the `claude` executable ("" => auto-detect on PATH)
+    "cli_model": "",  # optional model alias for the CLI (e.g. "haiku"); "" => default
+    # Used only by the "api" backend:
+    "model": "claude-haiku-4-5-20251001",
+    "api_key": "",  # empty => fall back to ANTHROPIC_API_KEY env var
+    "max_topics_per_turn": 5,
+    "background": True,  # run the work detached so Claude Code stays snappy
+    "min_chars": 40,  # skip trivial edits (renames, one-liners) to save calls
+    "max_input_chars": 14000,  # cap the code we send per turn
+}
+
+# Env flag set on any `claude` process we spawn, so the Stop hook it fires can
+# recognize it's a learnlance-triggered call and bail instead of recursing.
+REENTRY_FLAG = "LEARNLANCE_ACTIVE"
+
+
+def ensure_home() -> None:
+    HOME.mkdir(parents=True, exist_ok=True)
+    INSIGHTS_DIR.mkdir(parents=True, exist_ok=True)
+    WORK_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def load_config() -> dict:
+    cfg = dict(DEFAULTS)
+    if CONFIG_PATH.exists():
+        try:
+            cfg.update(json.loads(CONFIG_PATH.read_text(encoding="utf-8")))
+        except Exception:
+            pass
+    return cfg
+
+
+def save_config(cfg: dict) -> None:
+    ensure_home()
+    CONFIG_PATH.write_text(json.dumps(cfg, indent=2), encoding="utf-8")
+
+
+def get_api_key(cfg: dict) -> str:
+    return (cfg.get("api_key") or "").strip() or os.environ.get("ANTHROPIC_API_KEY", "").strip()
+
+
+def log(msg: str) -> None:
+    try:
+        ensure_home()
+        with LOG_PATH.open("a", encoding="utf-8") as fh:
+            fh.write(msg.rstrip() + "\n")
+    except Exception:
+        pass