Metadata-Version: 2.4
Name: learnlance-univ
Version: 0.2.15
Summary: Turn what AI coding agents build into a growing personal knowledge graph.
Author: aeroscissorz
License: MIT
Project-URL: Homepage, https://github.com/aeroscissorz/learnlance-univ
Project-URL: Repository, https://github.com/aeroscissorz/learnlance-univ
Project-URL: Issues, https://github.com/aeroscissorz/learnlance-univ/issues
Keywords: ai,agents,learning,knowledge-graph,cli,hooks,claude-code,cursor,copilot,gemini,kiro,antigravity
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.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.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Dynamic: license-file

# learnlance 🧠🔍

Turn what AI coding agents build into a growing personal knowledge graph.

learnlance watches your agent — **Claude Code, OpenAI Codex, Cursor, GitHub
Copilot (CLI / cloud / VS Code), Command Code, Kiro, Gemini CLI, Antigravity**,
or plain `git commit` — and after every turn that writes or edits code, it
quietly:

1. pulls out the code the agent just wrote,
2. asks an LLM *"what transferable 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.

Over time you get a browsable map of everything you've picked up while coding —
new nodes light up as *🌱 new topics learned*.

**No API key required.** By default it reuses an LLM CLI you're already logged
into (`claude`, `gemini`, `copilot`, `cursor-agent`, or `ollama`). Or use
`--in-chat` and the agent analyzes its own work — no separate CLI at all.

## Why it won't slow you down or break your session

- Analysis runs in a **detached background process** — your session never waits.
- Every hook is wrapped so a failure is logged and swallowed; it can't interrupt
  your coding session.
- Turns with no substantive code make **no LLM call** (no cost, no noise).

## Install

```bash
pip install learnlance-univ
learnlance setup
```

`setup` detects the agents you have and writes their hooks for the current
project. Run it again in each project you want tracked, then reload your editor
and code as usual.

Prefer the agent to analyze its own work in your chat, instead of a separate CLI?

```bash
learnlance setup --in-chat
```

Check what's actually installed and firing:

```bash
learnlance doctor
```

### Install one agent by hand

`learnlance install` with no flags targets Claude Code; a flag targets the rest.

```bash
learnlance install                # Claude Code (Stop hook)
learnlance install --cursor        # Cursor
learnlance install --codex         # OpenAI Codex
learnlance install --copilot       # Copilot CLI / cloud / VS Code Chat
learnlance install --commandcode   # Command Code
learnlance install --kiro          # Kiro
learnlance install --gemini        # Gemini CLI
learnlance install --antigravity   # Antigravity
learnlance install --git           # git post-commit (universal fallback)
```

## Supported agents

| Agent | Captures on | Analyzes on |
|-------|-------------|-------------|
| Claude Code | (whole transcript) | `Stop` |
| OpenAI Codex | `PostToolUse` | `Stop` |
| Cursor | `afterFileEdit` | `stop` |
| GitHub Copilot — CLI, cloud, VS Code | `PostToolUse` | `Stop` |
| Command Code | `PostToolUse` | `Stop` |
| Kiro | `PostToolUse` | `Stop` |
| Gemini CLI | `AfterTool` | `AfterAgent` |
| Antigravity | `PostToolUse` | `Stop` |
| git | — | `post-commit` |

Each integration is written from the vendor's hook docs. `learnlance doctor`
reports what's configured on disk versus what has actually fired.

## Use it

```bash
learnlance show      # render + open the knowledge graph in your browser
learnlance list -v   # list learned concepts, with explanations
learnlance stats     # quick counts by category
learnlance help      # every available command
```

The `show` view opens with a live loading spinner, then two declutter controls:
*show related concepts* (reveal dimmed umbrella nodes) and a *min link strength*
slider (hide one-off links).

### Add a concept the agent missed

```bash
learnlance add "debouncing"                 # search the current dir for the topic
learnlance add "topological sort" --path ./src
learnlance add "event sourcing" --force     # add even if it's not in the code
```

### Clear the graph

```bash
learnlance clear "delta encoding"   # remove one concept (+ orphaned related nodes)
learnlance clear                    # wipe the graph (asks first; -y to skip)
```

Per-session recaps are written to `~/.learnlance/insights/<session>.md`.

## Configuration

```bash
learnlance config                            # show current settings
learnlance config --llm-cmd "ollama run llama3"   # use any CLI that reads stdin
learnlance config --cli-model haiku          # model alias for the CLI backend
learnlance config --max-topics 3             # fewer concepts per turn
learnlance config --background off           # run analysis inline (blocks)
learnlance config --disable                  # pause without uninstalling hooks
learnlance config --enable                   # re-enable
```

Everything lives under `~/.learnlance/`: `graph.json` (the graph), `graph.html`
(the visualization), `insights/` (recaps), `learnlance.log` (diagnostics).

## Uninstall

```bash
learnlance uninstall                 # Claude Code (default)
learnlance uninstall --commandcode   # one specific agent
```

## How it works

learnlance normalizes every agent's hook payload into one `CodeEvent`, then runs
a harness-blind pipeline: insights → knowledge graph → HTML → recap. See
[ARCHITECTURE.md](ARCHITECTURE.md) for the full design.

| File | Role |
|------|------|
| `adapters.py` | Translates each agent's hook payload into a `CodeEvent` |
| `install.py` | Writes each agent's hook config (per project) |
| `autosetup.py` | Detects your agents and installs missing hooks |
| `hook.py` | Hook entrypoint; spawns the detached worker |
| `core.py` | The harness-blind learning pipeline |
| `insights.py` | Generates insights via an LLM CLI (or in-chat) |
| `transcript.py` | Parses Claude Code's JSONL transcript |
| `pending.py` | Buffers mid-session edits from tool-at-a-time agents |
| `graph.py` | Merges concepts into the knowledge graph |
| `viz.py` | Renders the offline, self-contained HTML graph |
| `codesearch.py` | Finds where a topic lives in your code (`add`) |

Zero third-party dependencies by design — hooks must run reliably wherever an
agent launches them.

## Contributing

LearnLance is actively looking for contributors. You don't need to understand the
entire codebase to contribute.

### Areas to help

- A coding-agent integration (adapter + installer)
- Knowledge graph algorithms
- Concept extraction
- Graph visualization
- CLI/UX
- Testing
- Documentation
- New learning workflows

### Good first contributions

- Add support for another coding agent
- Improve graph visualization
- Add tests for transcript parsing
- Improve Windows compatibility
- Add a CLI command
- Improve concept deduplication
- Improve graph accessibility
- Add documentation or examples

## License

MIT — see [LICENSE](LICENSE).
