graphlin 0.1.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "graphlin",
+  "version": "0.1.0",
+  "description": "Local architecture and activity viewer with passive, bounded event hooks.",
+  "author": {
+    "name": "Graphlin contributors"
+  },
+  "hooks": "./adapters/claude/hooks.json",
+  "license": "MIT",
+  "repository": "https://github.com/royosherove/graphlin",
+  "homepage": "https://github.com/royosherove/graphlin"
+}

package/.codex-plugin/plugin.json

@@ -0,0 +1,29 @@
+{
+  "name": "graphlin",
+  "version": "0.1.0",
+  "description": "Local architecture and activity diagrams from observable coding-agent work.",
+  "author": {
+    "name": "Graphlin contributors"
+  },
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json",
+  "interface": {
+    "displayName": "Graphlin",
+    "shortDescription": "Live architecture and activity viewer",
+    "longDescription": "A local viewer with passive event collection, explicit source-sharing controls, and an offline fixture demo.",
+    "developerName": "Graphlin contributors",
+    "category": "Productivity",
+    "capabilities": [
+      "Interactive",
+      "Read",
+      "Write"
+    ],
+    "defaultPrompt": [
+      "Start Graphlin for this project in metadata-only mode."
+    ],
+    "brandColor": "#20BFA9"
+  },
+  "license": "MIT",
+  "repository": "https://github.com/royosherove/graphlin",
+  "homepage": "https://github.com/royosherove/graphlin"
+}

package/.mcp.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "graphlin": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/control.mjs"]
+    }
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Graphlin contributors
+
+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,71 @@
+# Graphlin
+
+Live architecture diagrams while **Claude Code or Codex** explores and builds your code.
+
+![Graphlin showing function calls, a cache write, and a browser-to-service connection](docs/images/graphlin-preview.png)
+
+## Get started
+
+**You need:** macOS or Linux, Node.js 22.14+, and Claude Code or Codex CLI.
+Source classification also needs a TypeSafe API key; metadata mode needs no key.
+
+### 1. Start the viewer
+
+In your project's terminal:
+
+```sh
+npx --yes graphlin@latest
+```
+
+Graphlin asks which host to install, offers **source or metadata** mode for this
+project, and accepts your key at a **masked prompt** if needed. It stores the key
+privately and builds stable plugins outside the npm cache. The browser opens
+automatically. Keep this terminal running; **Ctrl+C** stops the viewer.
+
+Source mode permits locally filtered source excerpts, user prompts, and public
+agent messages to be sent to TypeSafe for classification.
+
+### 2. Start your agent
+
+Open a **second terminal in the same project**. Choose one:
+
+**Claude Code**
+
+```sh
+claude
+```
+
+**Codex**
+
+```sh
+codex
+```
+
+Accept the host's project trust prompt. In Claude, use **`/plugin`** to confirm
+Graphlin is enabled. In Codex, use **`/hooks`** to review and trust Graphlin's
+hooks. Start a new agent session after installation. Then ask either agent:
+
+> Orient yourself in this project: read its main files and explain how the components connect.
+
+Watch the diagram populate as it explores. On later runs, repeat step 1 and
+launch your agent; Graphlin reuses the saved setup. Use the printed agent command
+if you selected a custom data directory.
+
+For setup alone, append `init` to the command. Append `uninstall` to remove
+Graphlin's host plugins across projects while keeping your saved key and history.
+
+## Just looking?
+
+Try the offline demo—no key or agent required:
+
+```sh
+npx --yes graphlin@latest demo
+```
+
+## More
+
+[User guide](docs/usage.md) · [Design](docs/graphlin-design.md) ·
+[Contributing](CONTRIBUTING.md) · [Releasing](docs/releasing.md) · [MIT license](LICENSE)
+
+Graphlin visualizes observable actions and code evidence. It does not capture
+private reasoning or prove runtime connectivity. Development preview.

package/adapters/README.md

@@ -0,0 +1,32 @@
+# Adapter scope
+
+The root `plugin.json` and `mcp.json` follow Agent Plugins 1.0.0. OpenAI
+presentation and the Codex hook path are under `extensions.com.openai`.
+`.codex-plugin/plugin.json` remains a compatibility manifest for skill validation.
+The native Claude manifest references its own hook profile and `.mcp.json`
+uses Claude's root-variable substitution.
+
+`scripts/build-packages.mjs` generates self-contained `portable/graphlin`,
+`claude/graphlin`, and `codex/graphlin` directories from this source tree.
+No package contains machine-specific paths, a credential, installed config,
+or a marketplace. The portable package contains skills and an MCP server;
+native hook behavior is an extension, not a portable observation guarantee.
+
+All hook commands call the same guarded POSIX launcher with their host name.
+They read a bounded JSON input, resolve its `cwd` to the canonical worktree,
+handoff through a private Unix socket, and exit 0 with no output. The collector
+does not make HTTP requests, start a daemon, write raw spools, or change agent
+inputs, outputs, permissions, or stop behavior. A stopped daemon loses events;
+no recovery claim is made for events that never reached it.
+
+Node.js 22+ and macOS/Linux are the implemented runtime profile. Windows
+private-pipe ACLs and launch behavior are not certified. Default data is
+`~/.local/state/graphlin`, shared by host adapters. Use the same
+`GRAPHLIN_DATA_DIR` in hooks and controls for an override.
+
+Package tests exercise fixtures, launcher outages, local IPC, MCP, and relocated
+package paths. They do not certify that host hooks are loaded, trusted, or active.
+
+Kiro has only an inactive experimental profile. The builder emits that profile
+and this scope note, not an active Kiro plugin or hooks. Nothing in this
+repository installs or edits the user's host configuration.

package/adapters/claude/hooks.json

@@ -0,0 +1,10 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [{"hooks":[{"type":"command","command":"if [ -r \"${CLAUDE_PLUGIN_ROOT}/scripts/collect.sh\" ]; then /bin/sh \"${CLAUDE_PLUGIN_ROOT}/scripts/collect.sh\" claude; fi >/dev/null 2>&1; exit 0","timeout":2}]}],
+    "PreToolUse": [{"matcher":".*","hooks":[{"type":"command","command":"if [ -r \"${CLAUDE_PLUGIN_ROOT}/scripts/collect.sh\" ]; then /bin/sh \"${CLAUDE_PLUGIN_ROOT}/scripts/collect.sh\" claude; fi >/dev/null 2>&1; exit 0","timeout":2}]}],
+    "PostToolUse": [{"matcher":".*","hooks":[{"type":"command","command":"if [ -r \"${CLAUDE_PLUGIN_ROOT}/scripts/collect.sh\" ]; then /bin/sh \"${CLAUDE_PLUGIN_ROOT}/scripts/collect.sh\" claude; fi >/dev/null 2>&1; exit 0","timeout":2}]}],
+    "PostToolUseFailure": [{"matcher":".*","hooks":[{"type":"command","command":"if [ -r \"${CLAUDE_PLUGIN_ROOT}/scripts/collect.sh\" ]; then /bin/sh \"${CLAUDE_PLUGIN_ROOT}/scripts/collect.sh\" claude; fi >/dev/null 2>&1; exit 0","timeout":2}]}],
+    "SessionStart": [{"hooks":[{"type":"command","command":"if [ -r \"${CLAUDE_PLUGIN_ROOT}/scripts/collect.sh\" ]; then /bin/sh \"${CLAUDE_PLUGIN_ROOT}/scripts/collect.sh\" claude; fi >/dev/null 2>&1; exit 0","timeout":2}]}],
+    "Stop": [{"hooks":[{"type":"command","command":"if [ -r \"${CLAUDE_PLUGIN_ROOT}/scripts/collect.sh\" ]; then /bin/sh \"${CLAUDE_PLUGIN_ROOT}/scripts/collect.sh\" claude; fi >/dev/null 2>&1; exit 0","timeout":2}]}]
+  }
+}

package/adapters/claude/profile.json

@@ -0,0 +1,18 @@
+{
+  "host": "claude",
+  "platforms": [
+    "darwin",
+    "linux"
+  ],
+  "events": [
+    "UserPromptSubmit",
+    "PreToolUse",
+    "PostToolUse",
+    "PostToolUseFailure",
+    "SessionStart",
+    "Stop"
+  ],
+  "activation": "not_verified",
+  "capture": "bounded_private_ipc",
+  "automaticDaemonStart": false
+}

package/adapters/codex/hooks.json

@@ -0,0 +1,9 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [{"hooks":[{"type":"command","command":"if [ -r \"${PLUGIN_ROOT}/scripts/collect.sh\" ]; then /bin/sh \"${PLUGIN_ROOT}/scripts/collect.sh\" codex; fi >/dev/null 2>&1; exit 0","timeout":2}]}],
+    "PreToolUse": [{"matcher":".*","hooks":[{"type":"command","command":"if [ -r \"${PLUGIN_ROOT}/scripts/collect.sh\" ]; then /bin/sh \"${PLUGIN_ROOT}/scripts/collect.sh\" codex; fi >/dev/null 2>&1; exit 0","timeout":2}]}],
+    "PostToolUse": [{"matcher":".*","hooks":[{"type":"command","command":"if [ -r \"${PLUGIN_ROOT}/scripts/collect.sh\" ]; then /bin/sh \"${PLUGIN_ROOT}/scripts/collect.sh\" codex; fi >/dev/null 2>&1; exit 0","timeout":2}]}],
+    "SessionStart": [{"hooks":[{"type":"command","command":"if [ -r \"${PLUGIN_ROOT}/scripts/collect.sh\" ]; then /bin/sh \"${PLUGIN_ROOT}/scripts/collect.sh\" codex; fi >/dev/null 2>&1; exit 0","timeout":2}]}],
+    "Stop": [{"hooks":[{"type":"command","command":"if [ -r \"${PLUGIN_ROOT}/scripts/collect.sh\" ]; then /bin/sh \"${PLUGIN_ROOT}/scripts/collect.sh\" codex; fi >/dev/null 2>&1; exit 0","timeout":2}]}]
+  }
+}

package/adapters/codex/profile.json

@@ -0,0 +1,22 @@
+{
+  "host": "codex",
+  "platforms": [
+    "darwin",
+    "linux"
+  ],
+  "events": [
+    "UserPromptSubmit",
+    "PreToolUse",
+    "PostToolUse",
+    "SessionStart",
+    "Stop"
+  ],
+  "activation": "not_verified",
+  "requiresHookTrust": true,
+  "coverageGaps": [
+    "hosted_tools",
+    "repeated_write_stdin",
+    "private_reasoning",
+    "unimplemented_streaming_events"
+  ]
+}

package/adapters/kiro/profile.json

@@ -0,0 +1,8 @@
+{
+  "host": "kiro",
+  "enabled": false,
+  "experimental": true,
+  "activation": "not_certified",
+  "events": [],
+  "reason": "IDE and CLI trigger/payload and passive-launch contracts require separate release-specific certification."
+}

package/mcp.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+  "mcpServers": {
+    "graphlin": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["${PLUGIN_ROOT}/scripts/control.mjs"],
+      "cwd": "${PLUGIN_DATA}"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,114 @@
+{
+  "name": "graphlin",
+  "version": "0.1.0",
+  "description": "Live architecture and activity diagrams from observable coding-agent work.",
+  "private": false,
+  "type": "module",
+  "engines": {
+    "node": ">=22.14.0"
+  },
+  "bin": {
+    "graphlin": "scripts/graphlin.mjs"
+  },
+  "scripts": {
+    "start": "node scripts/graphlin.mjs start",
+    "demo": "node scripts/graphlin.mjs demo",
+    "test": "node --test --test-timeout=30000",
+    "build": "node scripts/build-packages.mjs",
+    "doctor": "node scripts/graphlin.mjs doctor",
+    "eval:jev": "node scripts/evaluate-jev.mjs",
+    "eval:discovery": "node scripts/evaluate-discovery.mjs",
+    "validate": "node scripts/validate-packages.mjs",
+    "prepack": "npm run validate",
+    "release:check": "node .github/scripts/verify-release.mjs",
+    "pack:check": "node .github/scripts/verify-pack.mjs",
+    "check:packages": "npm run validate && npm run build && npm run pack:check"
+  },
+  "license": "MIT",
+  "author": "Graphlin contributors",
+  "homepage": "https://github.com/royosherove/graphlin#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/royosherove/graphlin.git"
+  },
+  "bugs": {
+    "url": "https://github.com/royosherove/graphlin/issues"
+  },
+  "keywords": [
+    "architecture",
+    "coding-agents",
+    "visualization",
+    "mcp",
+    "claude",
+    "codex"
+  ],
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": [
+    "./LICENSE",
+    "./README.md",
+    "./plugin.json",
+    "./mcp.json",
+    "./.mcp.json",
+    "./.claude-plugin/plugin.json",
+    "./.codex-plugin/plugin.json",
+    "./adapters/README.md",
+    "./adapters/claude/hooks.json",
+    "./adapters/claude/profile.json",
+    "./adapters/codex/hooks.json",
+    "./adapters/codex/profile.json",
+    "./adapters/kiro/profile.json",
+    "./skills/graphlin/SKILL.md",
+    "./runtime/collector/index.mjs",
+    "./runtime/core/candidates.mjs",
+    "./runtime/core/common.mjs",
+    "./runtime/core/evidence.mjs",
+    "./runtime/core/graph.mjs",
+    "./runtime/core/index.mjs",
+    "./runtime/core/lexical.mjs",
+    "./runtime/core/privacy.mjs",
+    "./runtime/core/tool-discovery.mjs",
+    "./runtime/daemon/auth.mjs",
+    "./runtime/daemon/connection-info.mjs",
+    "./runtime/daemon/demo.mjs",
+    "./runtime/daemon/diagnostics.mjs",
+    "./runtime/daemon/export.mjs",
+    "./runtime/daemon/ipc.mjs",
+    "./runtime/daemon/lock.mjs",
+    "./runtime/daemon/manager.mjs",
+    "./runtime/daemon/paths.mjs",
+    "./runtime/daemon/persistence.mjs",
+    "./runtime/daemon/server.mjs",
+    "./runtime/daemon/settings.mjs",
+    "./runtime/jev/fixture.mjs",
+    "./runtime/jev/index.mjs",
+    "./runtime/jev/questions.mjs",
+    "./runtime/jev/wire.mjs",
+    "./runtime/pipeline.mjs",
+    "./runtime/web/app.js",
+    "./runtime/web/index.html",
+    "./runtime/web/layout.js",
+    "./runtime/web/sidebar.js",
+    "./runtime/web/sketch.js",
+    "./runtime/web/style.css",
+    "./schemas/bundle.schema.json",
+    "./schemas/event.schema.json",
+    "./schemas/graph.schema.json",
+    "./schemas/patch.schema.json",
+    "./scripts/arguments.mjs",
+    "./scripts/build-packages.mjs",
+    "./scripts/collect.sh",
+    "./scripts/collector.mjs",
+    "./scripts/control.mjs",
+    "./scripts/daemon.mjs",
+    "./scripts/graphlin.mjs",
+    "./scripts/onboarding.mjs",
+    "./scripts/validate-packages.mjs"
+  ]
+}

package/plugin.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "graphlin",
+  "version": "0.1.0",
+  "description": "Local architecture and activity diagrams from observable coding-agent work.",
+  "extensions": {
+    "com.openai": {
+      "interface": {
+        "displayName": "Graphlin",
+        "shortDescription": "Live architecture and activity viewer",
+        "longDescription": "A local viewer with passive event collection, explicit source-sharing controls, and an offline fixture demo.",
+        "developerName": "Graphlin contributors",
+        "category": "Productivity",
+        "defaultPrompt": ["Start Graphlin for this project in metadata-only mode."],
+        "brandColor": "#20BFA9"
+      },
+      "hooks": "./adapters/codex/hooks.json"
+    }
+  }
+}

package/runtime/collector/index.mjs

@@ -0,0 +1,23 @@
+import { projectPaths, MAX_IPC_BYTES } from '../daemon/paths.mjs';
+import { requestIPC } from '../daemon/ipc.mjs';
+
+export async function collect(payload, { host = 'claude', dataDir, timeoutMs = 200 } = {}) {
+  if (!['claude', 'codex', 'kiro'].includes(host) || !payload || Array.isArray(payload) ||
+      typeof payload !== 'object' || typeof payload.cwd !== 'string') return false;
+  try {
+    const paths = await projectPaths(payload.cwd, dataDir);
+    const reply = await requestIPC(paths.socket, { host, payload }, { timeoutMs });
+    return reply.ok === true;
+  } catch { return false; }
+}
+
+export async function readHook(stream = process.stdin) {
+  const parts = []; let bytes = 0;
+  for await (const chunk of stream) {
+    bytes += chunk.length;
+    if (bytes > MAX_IPC_BYTES - 256) return null;
+    parts.push(chunk);
+  }
+  try { return JSON.parse(Buffer.concat(parts).toString('utf8')); }
+  catch { return null; }
+}