@oked/claude-code 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OKed
+
+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,62 @@
+# @oked/claude-code
+
+[![npm version](https://img.shields.io/npm/v/@oked/claude-code.svg)](https://www.npmjs.com/package/@oked/claude-code)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
+
+Zero-code integration for Claude Code. Installs a `PreToolUse` hook that routes sensitive actions (destructive Bash commands, payment MCP tools, etc.) through the OKed backend and waits for a human decision before Claude Code proceeds.
+
+Non-dangerous actions are left to Claude's normal permission flow - OKed only intervenes when it matters.
+
+## Install
+
+```bash
+npm install -g @oked/claude-code
+oked init
+```
+
+`oked init` writes a `PreToolUse` hook entry into the current project's `.claude/settings.json`, opens OKed's device-pairing flow in your browser, and stores the paired API key in `~/.oked/config.json`. Open a new Claude Code session in that project to activate the hook.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `oked init` | Install or update the project hook and pair this device. |
+| `oked status` | Show install state and ping the backend. |
+| `oked uninstall` | Remove the project hook entry (other hooks are preserved). |
+
+## What gets intercepted
+
+The hook uses a four-tier classifier:
+
+| Tier | Behavior | Examples |
+|---|---|---|
+| `safe` | Auto-allow, no notification | `Read`, `Glob`, read-only Bash (`ls`, `git status`, plain `curl` GET) |
+| `warning` | Terminal log only, no push | `Write` / `Edit` / `NotebookEdit` on a file inside the project |
+| `review` | Push notification, tap to approve | `Write` / `Edit` on a file outside the project, MCP `create_*` / `send_*` / `update_*` |
+| `high_stakes` | Push notification with confirmation | `rm -rf`, `git push --force`, `DROP TABLE`, `delete_*` MCP tools |
+
+Everything not matched by the classifier defaults to `review`.
+
+## How it works
+
+1. Claude Code fires the `PreToolUse` hook before every tool call.
+2. The hook classifies the action locally (no network call for safe actions).
+3. If it's high-stakes, it sends an approval request to the OKed backend.
+4. You get a notification (Telegram, web push, or dashboard).
+5. Approve or deny - Claude waits for your decision.
+
+## Environment
+
+| Var | Required | Description |
+|---|---|---|
+| `OKED_API_KEY` | no, after pairing | Optional override. `oked init` normally stores the paired key in `~/.oked/config.json`. |
+| `OKED_BACKEND_URL` | no | Override the hosted backend URL. |
+| `OKED_STRICT_FAIL_CLOSED` | no | Set to `1` or `true` to deny every sensitive action when the backend is unreachable. |
+
+## Degraded-mode behavior
+
+Explicit denials and invalid API keys deny the action. If the backend is unreachable, OKed denies `high_stakes` actions and, by default, allows lower tiers so a temporary outage does not stop every Claude Code workflow. If no API key is configured, the hook returns `ask` so Claude Code's native permission flow can handle the decision. Set `OKED_STRICT_FAIL_CLOSED=1` to deny every sensitive action during backend outages.
+
+## License
+
+[MIT](./LICENSE)

package/bin/oked-hook.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/hook.js";

package/bin/oked.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/cli.js";

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,250 @@
+#!/usr/bin/env node
+import { readFileSync, writeFileSync, existsSync, mkdirSync, chmodSync } from "fs";
+import { hostname } from "os";
+import { join, dirname } from "path";
+import { spawn } from "child_process";
+import { OKedClient, loadOKedConfig, OKED_CONFIG_PATH } from "@oked/sdk";
+const MCP_TOOL_MATCHER = "mcp__.*";
+const DEFAULT_TOOL_MATCHER = `Bash|Write|Edit|Agent|${MCP_TOOL_MATCHER}`;
+const HOOK_CONFIG = {
+    matcher: DEFAULT_TOOL_MATCHER,
+    hooks: [
+        {
+            type: "command",
+            command: "oked-hook",
+            timeout: 300,
+        },
+    ],
+};
+const DEFAULT_BACKEND_URL = process.env.OKED_BACKEND_URL || "https://api.oked.ai";
+const CLIENT_VERSION = "0.1.0";
+function getSettingsPath() {
+    return join(process.cwd(), ".claude", "settings.json");
+}
+function readSettings(path) {
+    if (!existsSync(path))
+        return {};
+    try {
+        return JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch {
+        return {};
+    }
+}
+function writeSettings(path, settings) {
+    const dir = join(process.cwd(), ".claude");
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    writeFileSync(path, JSON.stringify(settings, null, 2) + "\n");
+}
+function writeOkedConfig(apiKey, backendUrl) {
+    const dir = dirname(OKED_CONFIG_PATH);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    const existing = loadOKedConfig();
+    const payload = { ...existing, apiKey, backendUrl };
+    writeFileSync(OKED_CONFIG_PATH, JSON.stringify(payload, null, 2) + "\n");
+    try {
+        chmodSync(OKED_CONFIG_PATH, 0o600);
+    }
+    catch {
+        // Windows doesn't honor chmod; the file lives in the user profile anyway.
+    }
+}
+function hasOkedCommandHook(entry) {
+    return Boolean(entry.hooks?.some((h) => typeof h === "object" &&
+        h !== null &&
+        h.command === "oked-hook"));
+}
+function ensureMcpMatcher(matcher) {
+    if (!matcher)
+        return matcher;
+    const parts = matcher.split("|").map((part) => part.trim());
+    if (parts.some((part) => part === MCP_TOOL_MATCHER || part.startsWith("mcp__"))) {
+        return matcher;
+    }
+    return `${matcher}|${MCP_TOOL_MATCHER}`;
+}
+function openBrowser(url) {
+    const platform = process.platform;
+    let cmd;
+    let args;
+    if (platform === "darwin") {
+        cmd = "open";
+        args = [url];
+    }
+    else if (platform === "win32") {
+        cmd = "cmd";
+        args = ["/c", "start", "", url];
+    }
+    else {
+        cmd = "xdg-open";
+        args = [url];
+    }
+    try {
+        spawn(cmd, args, { detached: true, stdio: "ignore" }).unref();
+    }
+    catch {
+        // Best effort. The user has the URL on screen anyway.
+    }
+}
+async function pair(clientType) {
+    const codeRes = await fetch(`${DEFAULT_BACKEND_URL}/api/v1/device/code`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            client_type: clientType,
+            hostname: hostname(),
+            client_version: CLIENT_VERSION,
+        }),
+    });
+    if (!codeRes.ok) {
+        console.log(`  Failed to start pairing: ${codeRes.status} ${await codeRes.text()}`);
+        return null;
+    }
+    const code = (await codeRes.json());
+    console.log("");
+    console.log("  To pair this device, open:");
+    console.log(`    ${code.verification_uri_complete}`);
+    console.log("");
+    console.log("  Or visit " + code.verification_uri + " and enter the code:");
+    console.log(`    ${code.user_code}`);
+    console.log("");
+    console.log("  Waiting for confirmation in your browser...");
+    openBrowser(code.verification_uri_complete);
+    const deadline = Date.now() + code.expires_in * 1000;
+    const intervalMs = Math.max(1, code.interval) * 1000;
+    while (Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, intervalMs));
+        const pollRes = await fetch(`${DEFAULT_BACKEND_URL}/api/v1/device/poll`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ device_code: code.device_code }),
+        });
+        if (pollRes.status === 410) {
+            console.log("  Pairing code expired. Run `oked init` again.");
+            return null;
+        }
+        if (!pollRes.ok)
+            continue;
+        const body = (await pollRes.json());
+        if (body.status === "approved" && body.api_key) {
+            return body.api_key;
+        }
+    }
+    console.log("  Pairing timed out. Run `oked init` again.");
+    return null;
+}
+async function init() {
+    const settingsPath = getSettingsPath();
+    const settings = readSettings(settingsPath);
+    // Merge OKed hook into existing hooks
+    const hooks = (settings.hooks || {});
+    const preToolUse = (hooks.PreToolUse || []);
+    // Check if OKed hook already exists and upgrade older matchers to cover MCP
+    // tools (`mcp__<server>__<tool>`) as regular PreToolUse events.
+    let updatedOkedMatcher = false;
+    const hasOked = preToolUse.some((entry) => {
+        if (!hasOkedCommandHook(entry))
+            return false;
+        const nextMatcher = ensureMcpMatcher(entry.matcher);
+        if (nextMatcher !== entry.matcher) {
+            entry.matcher = nextMatcher;
+            updatedOkedMatcher = true;
+        }
+        return true;
+    });
+    if (!hasOked) {
+        preToolUse.push(HOOK_CONFIG);
+        hooks.PreToolUse = preToolUse;
+        settings.hooks = hooks;
+        writeSettings(settingsPath, settings);
+        console.log("OKed hook installed.");
+        console.log(`  Config: ${settingsPath}`);
+    }
+    else if (updatedOkedMatcher) {
+        hooks.PreToolUse = preToolUse;
+        settings.hooks = hooks;
+        writeSettings(settingsPath, settings);
+        console.log("OKed hook updated.");
+        console.log(`  Config: ${settingsPath}`);
+    }
+    else {
+        console.log("OKed hook already configured.");
+        console.log(`  Config: ${settingsPath}`);
+    }
+    // Already paired? Just ping and exit.
+    const existingClient = new OKedClient();
+    if (existingClient.apiKey) {
+        const ok = await existingClient.ping();
+        console.log("");
+        console.log(`  API key: ${existingClient.apiKey.slice(0, 8)}... (already paired)`);
+        console.log(`  Backend: ${existingClient.backendUrl} (${ok ? "connected" : "not reachable"})`);
+        console.log("");
+        console.log("Every Claude Code session in this project is now protected.");
+        return;
+    }
+    // Pair this device.
+    const apiKey = await pair("claude-code");
+    if (!apiKey)
+        return;
+    writeOkedConfig(apiKey, DEFAULT_BACKEND_URL);
+    console.log("");
+    console.log(`  Paired. Key saved to ${OKED_CONFIG_PATH}`);
+    console.log("");
+    console.log("Every Claude Code session in this project is now protected.");
+}
+async function status() {
+    const settingsPath = getSettingsPath();
+    const settings = readSettings(settingsPath);
+    const hooks = (settings.hooks || {});
+    const preToolUse = (hooks.PreToolUse || []);
+    const hasOked = preToolUse.some(hasOkedCommandHook);
+    const client = new OKedClient();
+    console.log(`OKed status:`);
+    console.log(`  Hook: ${hasOked ? "installed" : "not installed"}`);
+    console.log(`  Project config: ${existsSync(settingsPath) ? settingsPath : "not found"}`);
+    console.log(`  API key: ${client.apiKey ? client.apiKey.slice(0, 8) + "..." : "not paired"}`);
+    console.log(`  User config: ${existsSync(OKED_CONFIG_PATH) ? OKED_CONFIG_PATH : "not found"}`);
+    if (client.apiKey) {
+        const ok = await client.ping();
+        console.log(`  Backend: ${client.backendUrl} (${ok ? "connected" : "not reachable"})`);
+    }
+}
+function uninstall() {
+    const settingsPath = getSettingsPath();
+    const settings = readSettings(settingsPath);
+    const hooks = (settings.hooks || {});
+    const preToolUse = (hooks.PreToolUse || []);
+    // Remove OKed hook entries
+    hooks.PreToolUse = preToolUse.filter((entry) => !hasOkedCommandHook(entry));
+    if (hooks.PreToolUse.length === 0) {
+        delete hooks.PreToolUse;
+    }
+    if (Object.keys(hooks).length === 0) {
+        delete settings.hooks;
+    }
+    writeSettings(settingsPath, settings);
+    console.log("OKed hooks removed from this project.");
+}
+// CLI entry point
+const command = process.argv[2];
+switch (command) {
+    case "init":
+        init().catch(console.error);
+        break;
+    case "status":
+        status().catch(console.error);
+        break;
+    case "uninstall":
+        uninstall();
+        break;
+    default:
+        console.log("Usage: oked <command>");
+        console.log("");
+        console.log("Commands:");
+        console.log("  init        Install OKed hooks in current project and pair this device");
+        console.log("  status      Show current config and connection status");
+        console.log("  uninstall   Remove OKed hooks from current project");
+        break;
+}

package/dist/hook.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/hook.js

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+import { OKedClient, classify, describe, describeFields, applyRules, degradedDecision, OKedAuthError, OKedBackendUnreachableError, } from "@oked/sdk";
+function makeOutput(decision, reason) {
+    return {
+        hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            permissionDecision: decision,
+            ...(reason && { permissionDecisionReason: reason }),
+        },
+    };
+}
+function log(msg) {
+    process.stderr.write(`[OKed] ${msg}\n`);
+}
+async function main() {
+    // Read hook input from stdin
+    let rawInput = "";
+    for await (const chunk of process.stdin) {
+        rawInput += chunk;
+    }
+    let input;
+    try {
+        input = JSON.parse(rawInput);
+    }
+    catch {
+        // Can't parse input - don't break Claude, let it through
+        process.stdout.write(JSON.stringify(makeOutput("allow")));
+        return;
+    }
+    const { tool_name: toolName, tool_input: toolInput } = input;
+    // Classify risk
+    const tier = classify(toolName, toolInput);
+    const client = new OKedClient();
+    // Presence ping (throttled to once/day on disk, never throws). Fired before
+    // the safe/warning fast-path return so installs that only ever run safe
+    // actions still register for retention. Bounded by the 3s internal timeout,
+    // and only the once/day send actually waits.
+    if (client.apiKey)
+        await client.heartbeat();
+    const fields = describeFields(toolName, toolInput) ?? undefined;
+    // safe/warning normally short-circuit locally with no network call. But a
+    // user rule can escalate (or auto-decide) such an action, and rules live
+    // server-side. Consult the locally-cached rules: if one matches this action,
+    // route it to the backend so the rule is applied authoritatively. With no
+    // matching rule (the common case) we keep the cheap local fast-path.
+    if (tier === "safe" || tier === "warning") {
+        let ruleMatches = false;
+        if (client.apiKey) {
+            try {
+                const rules = await client.getRules();
+                if (rules.length > 0) {
+                    const decision = applyRules({ tier, fields: fields ?? {} }, rules, { cwd: input.cwd });
+                    ruleMatches = Boolean(decision.appliedRuleId);
+                }
+            }
+            catch {
+                // Advisory: a failed rules lookup must never block the action.
+            }
+        }
+        if (!ruleMatches) {
+            if (tier === "warning") {
+                const summary = (toolInput.file_path ?? toolInput.command ?? toolName);
+                process.stderr.write(`WARNING  OKed: ${toolName} ${summary} - allowed (inside project)\n`);
+            }
+            process.stdout.write(JSON.stringify(makeOutput("allow")));
+            return;
+        }
+        // A rule matched a normally-silent action — fall through to the backend,
+        // which applies the rule authoritatively (escalate / auto-decide + audit).
+    }
+    // Check if API key is configured
+    if (!client.apiKey) {
+        log("not paired - run `oked init` to pair this device. Falling back to Claude's built-in prompt.");
+        process.stdout.write(JSON.stringify(makeOutput("ask")));
+        return;
+    }
+    // Generate human-readable description
+    const description = describe(toolName, toolInput);
+    log(`${toolName}: "${description}" - ${tier}`);
+    log("Requesting approval... (check your phone)");
+    try {
+        const result = await client.approve({
+            action: toolName,
+            description,
+            tier,
+            fields,
+            tool_input: toolInput,
+            session_id: input.session_id,
+            cwd: input.cwd,
+        });
+        if (result.approved) {
+            log(`Approved (${result.approval_id})`);
+            process.stdout.write(JSON.stringify(makeOutput("allow", `Approved via OKed`)));
+        }
+        else {
+            log(`Denied (${result.approval_id})`);
+            process.stdout.write(JSON.stringify(makeOutput("deny", `Denied via OKed: ${description}`)));
+        }
+    }
+    catch (err) {
+        if (err instanceof OKedAuthError) {
+            // Auth misconfig is not an outage - always deny.
+            log(`Invalid API key - action denied`);
+            process.stdout.write(JSON.stringify(makeOutput("deny", "OKed: invalid API key")));
+        }
+        else if (err instanceof OKedBackendUnreachableError) {
+            const decision = degradedDecision(tier, {
+                strictFailClosed: client.strictFailClosed,
+            });
+            if (decision === "allow") {
+                log(`Backend unreachable - allowed (degraded; ${tier}, non-high-stakes)`);
+                process.stdout.write(JSON.stringify(makeOutput("allow", "OKed backend unreachable - allowed (degraded; non-high-stakes)")));
+            }
+            else {
+                const why = client.strictFailClosed
+                    ? "strict fail-closed"
+                    : "high-stakes";
+                log(`Backend unreachable - ${why} denied (fail-safe)`);
+                process.stdout.write(JSON.stringify(makeOutput("deny", `OKed backend unreachable - ${why} denied (fail-safe)`)));
+            }
+        }
+        else {
+            // Unknown error - fail safe deny.
+            log(`Unexpected error - action denied (fail-safe)`);
+            process.stdout.write(JSON.stringify(makeOutput("deny", "OKed: unexpected error (fail-safe)")));
+        }
+    }
+}
+main().catch((err) => {
+    process.stderr.write(`[OKed] Fatal: ${err}\n`);
+    // Fail-safe: deny
+    process.stdout.write(JSON.stringify(makeOutput("deny", "OKed: internal error (fail-safe)")));
+    process.exit(0); // exit 0 so Claude reads our JSON, not a crash
+});

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@oked/claude-code",
+  "version": "0.1.0",
+  "description": "OKed for Claude Code - zero-code human approval for sensitive actions",
+  "type": "module",
+  "bin": {
+    "oked": "./bin/oked.js",
+    "oked-hook": "./bin/oked-hook.js"
+  },
+  "scripts": {
+    "prebuild": "npm run build --workspace=@oked/sdk",
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "claude-code",
+    "claude",
+    "approval",
+    "hook",
+    "agents",
+    "oked"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oked-ai/oked-sdk.git",
+    "directory": "packages/claude-code"
+  },
+  "bugs": {
+    "url": "https://github.com/oked-ai/oked-sdk/issues"
+  },
+  "homepage": "https://github.com/oked-ai/oked-sdk#readme",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@oked/sdk": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0"
+  }
+}