@pixelguild/loom 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,137 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/pixelguild/loom/main/assets/loom_app_icon.png" width="96" height="96" alt="Loom">
+</p>
+
+<h1 align="center">@pixelguild/loom</h1>
+
+<p align="center">
+  Session intelligence layer for <a href="https://claude.ai/code">Claude Code</a>.<br>
+  <strong>Persistent memory &middot; Intelligent archiving &middot; Cross-project patterns &middot; Peer LLM consultation</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@pixelguild/loom"><img src="https://img.shields.io/npm/v/@pixelguild/loom?color=0a7bca&label=npm" alt="npm"></a>
+  <a href="https://github.com/pixelguild/loom/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@pixelguild/loom?color=333" alt="license"></a>
+  <a href="https://github.com/pixelguild/loom"><img src="https://img.shields.io/badge/github-pixelguild%2Floom-333?logo=github" alt="github"></a>
+</p>
+
+---
+
+Loom is an [MCP server](https://modelcontextprotocol.io) that gives Claude Code a long-term memory. It logs what Claude does, archives context when it grows large, and lets Claude pick up exactly where it left off in the next session.
+
+## Install
+
+```bash
+npx @pixelguild/loom init
+```
+
+This scaffolds `docs/loom/`, wires the MCP server into `.claude/mcp.json`, and adds instructions to your `CLAUDE.md`. That's it.
+
+Or add manually:
+
+```bash
+claude mcp add loom -- npx @pixelguild/loom
+```
+
+## What it does
+
+| Feature | Description |
+|---------|-------------|
+| **Context logging** | Structured entries (decisions, actions, issues, questions) appended to `docs/loom/context.md` |
+| **Session pickup** | Claude reads context at session start and resumes where it left off |
+| **Intelligent archiving** | Spawns a Claude subprocess to produce narrative archives with rolling carry-forward summaries |
+| **Pattern library** | Global SQLite store with FTS5 search — save solutions in one project, find them everywhere |
+| **Peer consultation** | Ask OpenAI, Vertex AI, or Ollama for a second opinion on architecture, debugging, or design |
+| **Execution manifests** | Save structured plans for headless `claude` runs |
+| **Per-project config** | Customize thresholds, providers, and settings via `loom.config.json` |
+
+## How it works
+
+```
+Session start                          Session end
+     |                                      |
+     v                                      v
+ loom_get_context  -->  Claude works  -->  loom_log_context
+     |                  with full           |
+     |                  history             v
+     v                                 Token threshold?
+ Resume where                          Yes --> loom_archive_context
+ you left off                                  |
+                                               v
+                                         Narrative archive with
+                                         carry-forward summary
+```
+
+The latest archive's carry-forward summary + current `context.md` always gives Claude full project history without reading every old archive.
+
+## MCP Tools
+
+| Tool | Purpose |
+|------|---------|
+| `loom_get_context` | Read current context. Call at session start. |
+| `loom_log_context` | Log a structured entry (action, decision, issue, question, dead_end, session_end) |
+| `loom_get_session_status` | Token count, archive count, threshold status |
+| `loom_archive_context` | Archive context (intelligent with Claude subprocess, mechanical fallback) |
+| `loom_save_pattern` | Save a reusable pattern to the global library |
+| `loom_find_pattern` | Search patterns across all projects |
+| `loom_create_manifest` | Save a structured execution manifest |
+| `loom_get_manifest` | List or retrieve manifests |
+| `loom_consult_peer` | Ask a peer LLM for a second opinion |
+
+## CLI
+
+```bash
+npx @pixelguild/loom init      # Scaffold project, wire MCP, inject CLAUDE.md
+npx @pixelguild/loom status    # Token count, archive status, context health
+```
+
+## Configuration
+
+Layered config — per-project overrides global defaults.
+
+**Global** `~/.loom/config.json`:
+
+```json
+{
+  "default_provider": "openai",
+  "providers": {
+    "openai": { "model": "gpt-4o" },
+    "vertex": { "model": "gemini-2.0-flash", "project": "my-gcp-project", "location": "us-central1" },
+    "ollama": { "model": "llama3.1", "host": "http://localhost:11434" }
+  }
+}
+```
+
+**Per-project** `docs/loom/loom.config.json`:
+
+```json
+{
+  "archive_thresholds": { "warning": 40000, "archive": 50000 },
+  "peer_consultation": { "enabled": true, "allowed_providers": ["openai", "ollama"] }
+}
+```
+
+| Variable | Purpose |
+|----------|---------|
+| `LOOM_PROJECT_ROOT` | Project directory (falls back to cwd) |
+| `LOOM_OPENAI_API_KEY` | OpenAI API key for peer consultation |
+
+## Storage
+
+```
+docs/loom/
+  context.md              # Active session context
+  loom.config.json        # Per-project config (optional)
+  archives/
+    2026-03-08-001.md     # Timestamped narrative archives
+  manifests/
+    deploy-plan.md        # Execution manifests
+
+~/.loom/
+  config.json             # Global config
+  loom.db                 # SQLite pattern library (FTS5)
+```
+
+## License
+
+MIT &copy; [Pixel Guild, LLC](https://pixelguild.com)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixelguild/loom",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Session intelligence layer for Claude Code — persistent memory, intelligent archiving, cross-project patterns, and peer LLM consultation.",
   "type": "module",
   "main": "dist/index.js",
@@ -9,7 +9,8 @@
   },
   "files": [
     "dist",
-    "!dist/**/__tests__"
+    "!dist/**/__tests__",
+    "README.md"
   ],
   "keywords": [
     "claude",