twining-mcp 1.3.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,165 @@
+<p align="center">
+  <img src="assets/logo.png" alt="Twining" width="400">
+</p>
+
+<p align="center">
+  <strong>Separate threads, stronger together.</strong><br>
+  Agent coordination for Claude Code and other MCP clients.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/twining-mcp"><img src="https://img.shields.io/npm/v/twining-mcp" alt="npm version"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License"></a>
+</p>
+
+---
+
+Twining provides a shared blackboard, decision tracking with rationale, selective context assembly, a lightweight knowledge graph, agent coordination with capability-based delegation, and local semantic search — all backed by plain JSONL/JSON files that are git-trackable and human-inspectable. Includes an embedded web dashboard for browsing and visualizing all state.
+
+## Features
+
+- **Shared Blackboard** — Append-only message stream for findings, needs, warnings, and questions across agents
+- **Decision Tracking** — Record decisions with rationale, alternatives, confidence, dependency chains, and git commit linking
+- **Context Assembly** — Build tailored context packages for a task within a token budget, with handoff results and agent suggestions
+- **Knowledge Graph** — Lightweight entity-relation graph with traversal, search, and full state export
+- **Semantic Search** — Local embeddings via all-MiniLM-L6-v2 with automatic keyword fallback
+- **Agent Coordination** — Registry with capability-based discovery, delegation matching, structured handoffs, and liveness tracking
+- **Web Dashboard** — Embedded HTTP server with stats, search, decision timeline, interactive graph visualization, and agent coordination views
+- **Archiving** — Move stale entries to archive while preserving decision records
+
+## Quick Start
+
+### Install
+
+```bash
+npm install -g twining-mcp
+```
+
+### Configure in Claude Code
+
+Add to your Claude Code MCP settings (`~/.claude/claude_desktop_config.json` or project `.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "twining": {
+      "command": "twining-mcp",
+      "args": ["--project", "/path/to/your/project"]
+    }
+  }
+}
+```
+
+If `--project` is omitted, Twining uses the current working directory.
+
+### Usage
+
+Once configured, Twining tools are available in your Claude Code sessions:
+
+```
+> Use twining_post to share a finding about the auth module
+> Use twining_assemble to get context for the refactoring task
+> Use twining_decide to record the database choice with rationale
+> Use twining_why to understand why we chose PostgreSQL
+> Use twining_agents to see which agents are available
+```
+
+All state is stored in a `.twining/` directory in your project root.
+
+### Claude Code Integration
+
+For maximum value with Claude Code, add Twining instructions to your project's `CLAUDE.md`. See **[docs/CLAUDE_TEMPLATE.md](docs/CLAUDE_TEMPLATE.md)** for a ready-to-copy template covering Twining + Serena + GSD integration.
+
+### Dashboard
+
+The web dashboard starts automatically on port 24282 (configurable via `TWINING_DASHBOARD_PORT`). Open `http://localhost:24282` to browse blackboard entries, decisions, knowledge graph, and agent coordination state.
+
+## Tools
+
+### Blackboard
+
+| Tool | Description |
+|------|-------------|
+| `twining_post` | Post an entry (finding, need, warning, question) to the shared blackboard |
+| `twining_read` | Read blackboard entries with optional filters by type, scope, or agent |
+| `twining_query` | Semantic search across blackboard entries, with keyword fallback |
+| `twining_recent` | Get the most recent blackboard entries |
+
+### Decisions
+
+| Tool | Description |
+|------|-------------|
+| `twining_decide` | Record a decision with rationale, alternatives, and traceability |
+| `twining_why` | Retrieve all decisions affecting a given scope or file |
+| `twining_trace` | Trace a decision's dependency chain upstream and/or downstream |
+| `twining_reconsider` | Flag a decision for reconsideration with downstream impact analysis |
+| `twining_override` | Override a decision with a reason, optionally creating a replacement |
+| `twining_search_decisions` | Search decisions by keyword or semantic similarity with filters |
+| `twining_link_commit` | Link a git commit hash to an existing decision |
+| `twining_commits` | Query decisions by git commit hash |
+
+### Context & Lifecycle
+
+| Tool | Description |
+|------|-------------|
+| `twining_assemble` | Build tailored context for a task within a token budget |
+| `twining_summarize` | Get a high-level summary of project state and activity |
+| `twining_what_changed` | Report what changed since a given point in time |
+| `twining_status` | Overall health check — entry counts, agent counts, warnings, and summary |
+| `twining_archive` | Archive old blackboard entries to reduce working set size |
+| `twining_export` | Export full Twining state as a single markdown document |
+
+### Knowledge Graph
+
+| Tool | Description |
+|------|-------------|
+| `twining_add_entity` | Add or update a knowledge graph entity (upsert semantics) |
+| `twining_add_relation` | Add a relation between two knowledge graph entities |
+| `twining_neighbors` | Traverse the knowledge graph from an entity up to depth 3 |
+| `twining_graph_query` | Search the knowledge graph by name or property substring |
+
+### Agent Coordination
+
+| Tool | Description |
+|------|-------------|
+| `twining_agents` | List registered agents with capabilities, liveness status, and filtering |
+| `twining_discover` | Find agents matching required capabilities, ranked by overlap and liveness |
+| `twining_delegate` | Post a delegation request to the blackboard with capability requirements |
+| `twining_handoff` | Create a handoff between agents with work results and auto-assembled context |
+| `twining_acknowledge` | Acknowledge receipt of a handoff |
+
+## Architecture
+
+Twining is organized in layers:
+
+- **Storage Layer** — File-backed stores for blackboard (JSONL), decisions (JSON index + individual files), knowledge graph (JSON), agent registry, and handoff records. All I/O goes through this layer with file locking for concurrent access.
+- **Engine Layer** — Business logic for each domain: blackboard posting/querying, decision recording/tracing, graph traversal, context assembly with token budgeting, agent coordination with capability-based discovery and delegation, and archiving.
+- **Embeddings Layer** — Lazy-loaded local embeddings using `@huggingface/transformers` with all-MiniLM-L6-v2. Falls back to keyword search if model loading fails. The server never fails to start because of embedding issues.
+- **Dashboard Layer** — Embedded HTTP server running alongside MCP stdio transport. Vanilla HTML/CSS/JS with cytoscape.js for graph visualization and vis-timeline for decision timelines. Read-only observer of Twining state.
+- **Tools Layer** — MCP tool definitions that map 1:1 to the tool surface. Each tool validates input with Zod and returns structured results.
+
+All state lives in `.twining/` as plain files — JSONL for the blackboard stream, JSON for decisions, graph, agents, and handoffs. Everything is `jq`-queryable, `grep`-able, and git-diffable.
+
+See [TWINING-DESIGN-SPEC.md](TWINING-DESIGN-SPEC.md) for the full design specification.
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npm test
+
+# Watch mode
+npm run test:watch
+```
+
+Requires Node.js >= 18.
+
+## License
+
+[MIT](LICENSE)

package/dist/config.d.ts

@@ -0,0 +1,8 @@
+import type { TwiningConfig } from "./utils/types.js";
+export declare const DEFAULT_CONFIG: TwiningConfig;
+/**
+ * Load config from .twining/config.yml, deep-merged with defaults.
+ * If the file doesn't exist, returns DEFAULT_CONFIG.
+ */
+export declare function loadConfig(twiningDir: string): TwiningConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,eAAO,MAAM,cAAc,EAAE,aAgC5B,CAAC;AA+BF;;;GAGG;AACH,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,aAAa,CAc5D"}

package/dist/config.js

@@ -0,0 +1,78 @@
+/**
+ * Configuration loading from .twining/config.yml with sensible defaults.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import yaml from "js-yaml";
+export const DEFAULT_CONFIG = {
+    version: 1,
+    project_name: "",
+    embedding_model: "all-MiniLM-L6-v2",
+    archive: {
+        auto_archive_on_commit: true,
+        auto_archive_on_context_switch: true,
+        max_blackboard_entries_before_archive: 500,
+    },
+    context_assembly: {
+        default_max_tokens: 4000,
+        priority_weights: {
+            recency: 0.3,
+            relevance: 0.4,
+            decision_confidence: 0.2,
+            warning_boost: 0.1,
+        },
+    },
+    conflict_resolution: "human",
+    agents: {
+        liveness: {
+            idle_after_ms: 300000, // 5 minutes
+            gone_after_ms: 1800000, // 30 minutes
+        },
+    },
+    delegations: {
+        timeouts: {
+            high_ms: 300000, // 5 minutes
+            normal_ms: 1800000, // 30 minutes
+            low_ms: 14400000, // 4 hours
+        },
+    },
+};
+/** Deep merge source into target, returning a new object */
+function deepMerge(target, source) {
+    const result = { ...target };
+    for (const key of Object.keys(target)) {
+        const targetVal = target[key];
+        const sourceVal = source[key];
+        if (sourceVal === undefined)
+            continue;
+        if (targetVal !== null &&
+            typeof targetVal === "object" &&
+            !Array.isArray(targetVal) &&
+            sourceVal !== null &&
+            typeof sourceVal === "object" &&
+            !Array.isArray(sourceVal)) {
+            result[key] = deepMerge(targetVal, sourceVal);
+        }
+        else {
+            result[key] = sourceVal;
+        }
+    }
+    return result;
+}
+/**
+ * Load config from .twining/config.yml, deep-merged with defaults.
+ * If the file doesn't exist, returns DEFAULT_CONFIG.
+ */
+export function loadConfig(twiningDir) {
+    const configPath = path.join(twiningDir, "config.yml");
+    if (!fs.existsSync(configPath)) {
+        return { ...DEFAULT_CONFIG };
+    }
+    const raw = fs.readFileSync(configPath, "utf-8");
+    const parsed = yaml.load(raw);
+    if (parsed === null || parsed === undefined || typeof parsed !== "object") {
+        return { ...DEFAULT_CONFIG };
+    }
+    return deepMerge(DEFAULT_CONFIG, parsed);
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,IAAI,MAAM,SAAS,CAAC;AAG3B,MAAM,CAAC,MAAM,cAAc,GAAkB;IAC3C,OAAO,EAAE,CAAC;IACV,YAAY,EAAE,EAAE;IAChB,eAAe,EAAE,kBAAkB;IACnC,OAAO,EAAE;QACP,sBAAsB,EAAE,IAAI;QAC5B,8BAA8B,EAAE,IAAI;QACpC,qCAAqC,EAAE,GAAG;KAC3C;IACD,gBAAgB,EAAE;QAChB,kBAAkB,EAAE,IAAI;QACxB,gBAAgB,EAAE;YAChB,OAAO,EAAE,GAAG;YACZ,SAAS,EAAE,GAAG;YACd,mBAAmB,EAAE,GAAG;YACxB,aAAa,EAAE,GAAG;SACnB;KACF;IACD,mBAAmB,EAAE,OAAO;IAC5B,MAAM,EAAE;QACN,QAAQ,EAAE;YACR,aAAa,EAAE,MAAM,EAAE,YAAY;YACnC,aAAa,EAAE,OAAO,EAAE,aAAa;SACtC;KACF;IACD,WAAW,EAAE;QACX,QAAQ,EAAE;YACR,OAAO,EAAE,MAAM,EAAQ,YAAY;YACnC,SAAS,EAAE,OAAO,EAAK,aAAa;YACpC,MAAM,EAAE,QAAQ,EAAO,UAAU;SAClC;KACF;CACF,CAAC;AAEF,4DAA4D;AAC5D,SAAS,SAAS,CAChB,MAA+B,EAC/B,MAA+B;IAE/B,MAAM,MAAM,GAA4B,EAAE,GAAG,MAAM,EAAE,CAAC;IACtD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QACtC,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QAC9B,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,SAAS,KAAK,SAAS;YAAE,SAAS;QACtC,IACE,SAAS,KAAK,IAAI;YAClB,OAAO,SAAS,KAAK,QAAQ;YAC7B,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC;YACzB,SAAS,KAAK,IAAI;YAClB,OAAO,SAAS,KAAK,QAAQ;YAC7B,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,EACzB,CAAC;YACD,MAAM,CAAC,GAAG,CAAC,GAAG,SAAS,CACrB,SAAoC,EACpC,SAAoC,CACrC,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC;QAC1B,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,UAAkB;IAC3C,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;IACvD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAC/B,OAAO,EAAE,GAAG,cAAc,EAAE,CAAC;IAC/B,CAAC;IACD,MAAM,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IACjD,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC9B,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,KAAK,SAAS,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC1E,OAAO,EAAE,GAAG,cAAc,EAAE,CAAC;IAC/B,CAAC;IACD,OAAO,SAAS,CACd,cAAoD,EACpD,MAAiC,CACN,CAAC;AAChC,CAAC"}

package/dist/dashboard/api-routes.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Dashboard API route handlers.
+ *
+ * Factory function creates a request handler that serves JSON endpoints
+ * for blackboard entries, decisions, graph data, and operational status.
+ *
+ * CRITICAL: Never use console.log or process.stdout in this module.
+ * The MCP StdioServerTransport owns stdout exclusively.
+ */
+import http from "node:http";
+/**
+ * Create an API request handler for the given project root.
+ *
+ * Returns an async function that handles /api/* routes and returns true
+ * if the request was handled, false if it should fall through to other
+ * handlers (e.g., static file serving).
+ *
+ * Store instances are created once in the closure, not per-request.
+ */
+export declare function createApiHandler(projectRoot: string): (req: http.IncomingMessage, res: http.ServerResponse) => Promise<boolean>;
+//# sourceMappingURL=api-routes.d.ts.map

package/dist/dashboard/api-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-routes.d.ts","sourceRoot":"","sources":["../../src/dashboard/api-routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,IAAI,MAAM,WAAW,CAAC;AAsC7B;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,MAAM,GAClB,CAAC,GAAG,EAAE,IAAI,CAAC,eAAe,EAAE,GAAG,EAAE,IAAI,CAAC,cAAc,KAAK,OAAO,CAAC,OAAO,CAAC,CAukB3E"}