@secemp/elwood 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 secemp9
+
+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,132 @@
+# elwood
+
+Programmatically import and instrument the locally installed Claude Code CLI via Babel AST. Drop-in replacement for `@anthropic-ai/claude-agent-sdk` that runs **in-process** -- zero subprocess spawning.
+
+## How it works
+
+Instead of spawning `claude -p` as a subprocess (like the official SDK), elwood:
+
+1. Locates the installed Claude Code CLI (`cli.js`)
+2. Parses the 13MB bundle with Babel AST
+3. Fingerprints internal functions via evidence-based pattern matching
+4. Injects instrumentation hooks
+5. Calls `agentLoop()` directly in-process
+
+This gives you the same API as `@anthropic-ai/claude-agent-sdk` with lower latency and direct access to internals.
+
+## Install
+
+```bash
+npm install elwood
+```
+
+Requires Claude Code to be installed:
+```bash
+npm install -g @anthropic-ai/claude-code
+```
+
+## Quick start
+
+```js
+import { query } from 'elwood';
+
+for await (const message of query({
+  prompt: 'What files are in this directory?',
+  options: { maxTurns: 3 },
+})) {
+  if (message.type === 'result') {
+    console.log(message.result);
+  }
+}
+```
+
+No API key needed if logged in via `claude login` (Pro/Max subscription).
+
+## API
+
+### query({ prompt, options })
+
+Returns an async generator yielding messages. Options include:
+
+- `model` -- model to use
+- `systemPrompt` -- string or `{type: 'preset', append: '...'}`
+- `maxTurns` -- maximum conversation turns
+- `allowedTools` -- auto-approve these tools
+- `hooks` -- `{PreToolUse: [...], PostToolUse: [...], ...}`
+- `mcpServers` -- MCP server configs
+- `permissionMode` -- `'default' | 'acceptEdits' | 'bypassPermissions'`
+- `continue` / `resume` / `resumeSessionAt` / `forkSession` -- session management
+- `env` / `stderr` -- environment and output control
+- ...and all other official SDK options
+
+### Query control methods
+
+```js
+const conversation = query({ prompt: '...' });
+conversation.interrupt();          // soft interrupt
+conversation.setModel('...');      // change model mid-conversation
+conversation.setPermissionMode('acceptEdits');
+await conversation.supportedModels();
+await conversation.supportedCommands();
+conversation.close();              // cleanup
+```
+
+### tool(name, description, schema, handler)
+
+```js
+import { tool, createSdkMcpServer, query } from 'elwood';
+
+const weather = tool('get_weather', 'Get weather',
+  { type: 'object', properties: { city: { type: 'string' } } },
+  ({ city }) => `72F in ${city}`
+);
+
+const server = await createSdkMcpServer({ tools: [weather] });
+
+for await (const msg of query({
+  prompt: 'Weather in NYC?',
+  options: { mcpServers: [server] },
+})) { /* ... */ }
+```
+
+### Session utilities
+
+```js
+import { listSessions, getSessionMessages, getSessionInfo } from 'elwood';
+
+const sessions = await listSessions();
+const messages = await getSessionMessages(sessions[0].id);
+```
+
+### V2 Session API
+
+```js
+import { unstable_v2_createSession, unstable_v2_prompt } from 'elwood';
+
+const result = await unstable_v2_prompt('Explain recursion');
+```
+
+### Low-level AST access
+
+```js
+import { locate, load, instrument, parseBundle } from 'elwood';
+
+const { cliPath, version } = await locate();
+const ast = parseBundle(cliPath);
+```
+
+## Auth
+
+Works with all Claude Code auth methods:
+- Claude Pro/Max subscription (`claude login`)
+- `ANTHROPIC_API_KEY` environment variable
+- OAuth tokens
+- Bedrock/Vertex/Foundry
+
+## Examples
+
+See the [examples/](./examples/) directory for 24 working examples covering queries, hooks, MCP, custom tools, sessions, and more.
+
+## License
+
+MIT

package/examples/01-basic-query.js

@@ -0,0 +1,38 @@
+/**
+ * 01-basic-query.js
+ *
+ * Equivalent of the official @anthropic-ai/claude-agent-sdk "basic query" example.
+ *
+ * Official version:
+ *   import { query } from "@anthropic-ai/claude-agent-sdk";
+ *   for await (const message of query({
+ *     prompt: "What files are in this directory?",
+ *     options: { allowedTools: ["Bash", "Glob"] }
+ *   })) {
+ *     if ("result" in message) console.log(message.result);
+ *   }
+ *
+ * This elwood version uses the in-process query() function which runs
+ * cli.js via Babel AST instrumentation instead of spawning a subprocess.
+ *
+ * Prerequisites:
+ *   - ANTHROPIC_API_KEY set in environment
+ *   - Claude Code CLI installed (`npm install -g @anthropic-ai/claude-code`)
+ *
+ * Run:
+ *   node examples/01-basic-query.js
+ */
+
+import { query } from '../src/index.js';
+
+for await (const message of query({
+  prompt: 'What files are in this directory?',
+  options: {
+    allowedTools: ['Bash', 'Glob'],
+    maxTurns: 3,
+  },
+})) {
+  if ('result' in message) {
+    console.log(message.result);
+  }
+}

package/examples/02-bug-fixer.js

@@ -0,0 +1,57 @@
+/**
+ * 02-bug-fixer.js
+ *
+ * Equivalent of the official quickstart "bug fixer" agent example.
+ *
+ * Official version:
+ *   import { query } from "@anthropic-ai/claude-agent-sdk";
+ *   for await (const message of query({
+ *     prompt: "Review utils.py for bugs that would cause crashes. Fix any issues you find.",
+ *     options: {
+ *       allowedTools: ["Read", "Edit", "Glob"],
+ *       permissionMode: "acceptEdits"
+ *     }
+ *   })) {
+ *     if (message.type === "assistant" && message.message?.content) {
+ *       for (const block of message.message.content) {
+ *         if ("text" in block) console.log(block.text);
+ *         else if ("name" in block) console.log(`Tool: ${block.name}`);
+ *       }
+ *     } else if (message.type === "result") {
+ *       console.log(`Done: ${message.subtype}`);
+ *     }
+ *   }
+ *
+ * This elwood version runs the same agent loop in-process via Babel AST.
+ *
+ * Prerequisites:
+ *   - ANTHROPIC_API_KEY set in environment
+ *   - Claude Code CLI installed
+ *
+ * Run:
+ *   node examples/02-bug-fixer.js
+ */
+
+import { query } from '../src/index.js';
+
+// Agentic loop: streams messages as Claude works
+for await (const message of query({
+  prompt: 'Review utils.py for bugs that would cause crashes. Fix any issues you find.',
+  options: {
+    allowedTools: ['Read', 'Edit', 'Glob'], // Tools Claude can use
+    permissionMode: 'acceptEdits',           // Auto-approve file edits
+  },
+})) {
+  // Print human-readable output
+  if (message.type === 'assistant' && message.message?.content) {
+    for (const block of message.message.content) {
+      if ('text' in block) {
+        console.log(block.text);        // Claude's reasoning
+      } else if ('name' in block) {
+        console.log(`Tool: ${block.name}`); // Tool being called
+      }
+    }
+  } else if (message.type === 'result') {
+    console.log(`Done: ${message.subtype}`); // Final result
+  }
+}

package/examples/03-custom-system-prompt.js

@@ -0,0 +1,41 @@
+/**
+ * 03-custom-system-prompt.js
+ *
+ * Equivalent of the official "custom system prompt" example from the quickstart.
+ *
+ * Official version:
+ *   options: {
+ *     allowedTools: ["Read", "Edit", "Glob"],
+ *     permissionMode: "acceptEdits",
+ *     systemPrompt: "You are a senior Python developer. Always follow PEP 8 style guidelines."
+ *   }
+ *
+ * This elwood version uses the in-process query() with a custom system prompt.
+ *
+ * Prerequisites:
+ *   - ANTHROPIC_API_KEY set in environment
+ *   - Claude Code CLI installed
+ *
+ * Run:
+ *   node examples/03-custom-system-prompt.js
+ */
+
+import { query } from '../src/index.js';
+
+for await (const message of query({
+  prompt: 'Add type hints to all functions in utils.py',
+  options: {
+    allowedTools: ['Read', 'Edit', 'Glob'],
+    permissionMode: 'acceptEdits',
+    systemPrompt: 'You are a senior Python developer. Always follow PEP 8 style guidelines.',
+    maxTurns: 5,
+  },
+})) {
+  if (message.type === 'assistant' && message.message?.content) {
+    for (const block of message.message.content) {
+      if ('text' in block) console.log(block.text);
+    }
+  } else if (message.type === 'result') {
+    console.log(`Done: ${message.subtype}`);
+  }
+}

package/examples/04-read-only-agent.js

@@ -0,0 +1,38 @@
+/**
+ * 04-read-only-agent.js
+ *
+ * Equivalent of the official "permissions / read-only agent" example.
+ *
+ * Official version:
+ *   import { query } from "@anthropic-ai/claude-agent-sdk";
+ *   for await (const message of query({
+ *     prompt: "Review this code for best practices",
+ *     options: { allowedTools: ["Read", "Glob", "Grep"] }
+ *   })) {
+ *     if ("result" in message) console.log(message.result);
+ *   }
+ *
+ * This example creates a read-only agent that can analyze but never modify code.
+ * Only Read, Glob, and Grep are allowed -- no Write, Edit, or Bash.
+ *
+ * Prerequisites:
+ *   - ANTHROPIC_API_KEY set in environment
+ *   - Claude Code CLI installed
+ *
+ * Run:
+ *   node examples/04-read-only-agent.js
+ */
+
+import { query } from '../src/index.js';
+
+for await (const message of query({
+  prompt: 'Review this code for best practices',
+  options: {
+    allowedTools: ['Read', 'Glob', 'Grep'],
+    maxTurns: 5,
+  },
+})) {
+  if ('result' in message) {
+    console.log(message.result);
+  }
+}

package/examples/05-find-todos.js

@@ -0,0 +1,37 @@
+/**
+ * 05-find-todos.js
+ *
+ * Equivalent of the official "find TODO comments" example.
+ *
+ * Official version:
+ *   import { query } from "@anthropic-ai/claude-agent-sdk";
+ *   for await (const message of query({
+ *     prompt: "Find all TODO comments and create a summary",
+ *     options: { allowedTools: ["Read", "Glob", "Grep"] }
+ *   })) {
+ *     if ("result" in message) console.log(message.result);
+ *   }
+ *
+ * This elwood version searches for TODO comments using the in-process agent.
+ *
+ * Prerequisites:
+ *   - ANTHROPIC_API_KEY set in environment
+ *   - Claude Code CLI installed
+ *
+ * Run:
+ *   node examples/05-find-todos.js
+ */
+
+import { query } from '../src/index.js';
+
+for await (const message of query({
+  prompt: 'Find all TODO comments and create a summary',
+  options: {
+    allowedTools: ['Read', 'Glob', 'Grep'],
+    maxTurns: 10,
+  },
+})) {
+  if ('result' in message) {
+    console.log(message.result);
+  }
+}

package/examples/06-session-resume.js

@@ -0,0 +1,70 @@
+/**
+ * 06-session-resume.js
+ *
+ * Equivalent of the official "sessions" example showing session capture and resume.
+ *
+ * Official version:
+ *   import { query } from "@anthropic-ai/claude-agent-sdk";
+ *
+ *   let sessionId;
+ *   // First query: capture the session ID
+ *   for await (const message of query({
+ *     prompt: "Read the authentication module",
+ *     options: { allowedTools: ["Read", "Glob"] }
+ *   })) {
+ *     if (message.type === "system" && message.subtype === "init") {
+ *       sessionId = message.session_id;
+ *     }
+ *   }
+ *
+ *   // Resume with full context from the first query
+ *   for await (const message of query({
+ *     prompt: "Now find all places that call it",
+ *     options: { resume: sessionId }
+ *   })) {
+ *     if ("result" in message) console.log(message.result);
+ *   }
+ *
+ * This elwood version captures the session ID from the init message and
+ * resumes the session in a second query, maintaining full conversation context.
+ *
+ * Prerequisites:
+ *   - ANTHROPIC_API_KEY set in environment
+ *   - Claude Code CLI installed
+ *
+ * Run:
+ *   node examples/06-session-resume.js
+ */
+
+import { query } from '../src/index.js';
+
+let sessionId;
+
+// First query: capture the session ID
+console.log('--- First query: reading the authentication module ---');
+for await (const message of query({
+  prompt: 'Read the authentication module',
+  options: {
+    allowedTools: ['Read', 'Glob'],
+    maxTurns: 3,
+  },
+})) {
+  if (message.type === 'system' && message.subtype === 'init') {
+    sessionId = message.session_id;
+    console.log(`Session ID captured: ${sessionId}`);
+  }
+}
+
+// Resume with full context from the first query
+console.log('\n--- Second query: resuming to find callers ---');
+for await (const message of query({
+  prompt: 'Now find all places that call it', // "it" = auth module from context
+  options: {
+    resume: sessionId,
+    maxTurns: 5,
+  },
+})) {
+  if ('result' in message) {
+    console.log(message.result);
+  }
+}

package/examples/07-hooks-pretooluse.js

@@ -0,0 +1,74 @@
+/**
+ * 07-hooks-pretooluse.js
+ *
+ * Equivalent of the official "hooks" example showing PreToolUse to protect .env files.
+ *
+ * Official version:
+ *   import { query, HookCallback } from "@anthropic-ai/claude-agent-sdk";
+ *
+ *   const protectEnvFiles: HookCallback = async (input, toolUseID, { signal }) => {
+ *     const preInput = input as PreToolUseHookInput;
+ *     const toolInput = preInput.tool_input as Record<string, unknown>;
+ *     const filePath = toolInput?.file_path as string;
+ *     const fileName = filePath?.split("/").pop();
+ *
+ *     if (fileName === ".env") {
+ *       return {
+ *         hookSpecificOutput: {
+ *           hookEventName: preInput.hook_event_name,
+ *           permissionDecision: "deny",
+ *           permissionDecisionReason: "Cannot modify .env files"
+ *         }
+ *       };
+ *     }
+ *     return {};
+ *   };
+ *
+ * This elwood version uses the same hooks API (callback-based).
+ *
+ * Prerequisites:
+ *   - ANTHROPIC_API_KEY set in environment
+ *   - Claude Code CLI installed
+ *
+ * Run:
+ *   node examples/07-hooks-pretooluse.js
+ */
+
+import { query } from '../src/index.js';
+
+// Define a hook callback that blocks writes to .env files
+const protectEnvFiles = async (input, toolUseID, { signal }) => {
+  const toolInput = input.tool_input;
+  const filePath = typeof toolInput === 'object' ? toolInput?.file_path : undefined;
+  const fileName = typeof filePath === 'string' ? filePath.split('/').pop() : '';
+
+  // Block the operation if targeting a .env file
+  if (fileName === '.env') {
+    return {
+      hookSpecificOutput: {
+        hookEventName: input.hook_event_name,
+        permissionDecision: 'deny',
+        permissionDecisionReason: 'Cannot modify .env files',
+      },
+    };
+  }
+
+  // Return empty object to allow the operation
+  return {};
+};
+
+for await (const message of query({
+  prompt: 'Update the database configuration',
+  options: {
+    hooks: {
+      // Register the hook for PreToolUse events
+      // The matcher filters to only Write and Edit tool calls
+      PreToolUse: [{ matcher: 'Write|Edit', hooks: [protectEnvFiles] }],
+    },
+    maxTurns: 3,
+  },
+})) {
+  if (message.type === 'assistant' || message.type === 'result') {
+    console.log(message);
+  }
+}

package/examples/08-hooks-posttooluse-audit.js

@@ -0,0 +1,66 @@
+/**
+ * 08-hooks-posttooluse-audit.js
+ *
+ * Equivalent of the official "PostToolUse audit log" hooks example.
+ *
+ * Official version:
+ *   import { query, HookCallback } from "@anthropic-ai/claude-agent-sdk";
+ *   import { appendFile } from "fs/promises";
+ *
+ *   const logFileChange: HookCallback = async (input) => {
+ *     const filePath = (input as any).tool_input?.file_path ?? "unknown";
+ *     await appendFile("./audit.log",
+ *       `${new Date().toISOString()}: modified ${filePath}\n`);
+ *     return {};
+ *   };
+ *
+ *   for await (const message of query({
+ *     prompt: "Refactor utils.py to improve readability",
+ *     options: {
+ *       permissionMode: "acceptEdits",
+ *       hooks: {
+ *         PostToolUse: [{ matcher: "Edit|Write", hooks: [logFileChange] }]
+ *       }
+ *     }
+ *   })) {
+ *     if ("result" in message) console.log(message.result);
+ *   }
+ *
+ * This elwood version logs all file changes to an audit.log file
+ * using a PostToolUse hook.
+ *
+ * Prerequisites:
+ *   - ANTHROPIC_API_KEY set in environment
+ *   - Claude Code CLI installed
+ *
+ * Run:
+ *   node examples/08-hooks-posttooluse-audit.js
+ */
+
+import { query } from '../src/index.js';
+import { appendFile } from 'node:fs/promises';
+
+// Define a hook callback that logs file modifications
+const logFileChange = async (input, _toolUseID, _context) => {
+  const filePath = input?.tool_input?.file_path ?? 'unknown';
+  await appendFile(
+    './audit.log',
+    `${new Date().toISOString()}: modified ${filePath}\n`
+  );
+  return {};
+};
+
+for await (const message of query({
+  prompt: 'Refactor utils.py to improve readability',
+  options: {
+    permissionMode: 'acceptEdits',
+    hooks: {
+      PostToolUse: [{ matcher: 'Edit|Write', hooks: [logFileChange] }],
+    },
+    maxTurns: 5,
+  },
+})) {
+  if ('result' in message) {
+    console.log(message.result);
+  }
+}

package/examples/09-hooks-block-etc.js

@@ -0,0 +1,68 @@
+/**
+ * 09-hooks-block-etc.js
+ *
+ * Equivalent of the official "block writes to /etc" hooks example.
+ *
+ * Official version:
+ *   const blockEtcWrites: HookCallback = async (input, toolUseID, { signal }) => {
+ *     const preInput = input as PreToolUseHookInput;
+ *     const toolInput = preInput.tool_input as Record<string, unknown>;
+ *     const filePath = toolInput?.file_path as string;
+ *     if (filePath?.startsWith("/etc")) {
+ *       return {
+ *         systemMessage: "Remember: system directories like /etc are protected.",
+ *         hookSpecificOutput: {
+ *           hookEventName: preInput.hook_event_name,
+ *           permissionDecision: "deny",
+ *           permissionDecisionReason: "Writing to /etc is not allowed"
+ *         }
+ *       };
+ *     }
+ *     return {};
+ *   };
+ *
+ * This elwood version blocks writes to /etc and shows a system message.
+ *
+ * Prerequisites:
+ *   - ANTHROPIC_API_KEY set in environment
+ *   - Claude Code CLI installed
+ *
+ * Run:
+ *   node examples/09-hooks-block-etc.js
+ */
+
+import { query } from '../src/index.js';
+
+// Block writes to /etc system directory
+const blockEtcWrites = async (input, _toolUseID, { signal }) => {
+  const toolInput = input.tool_input;
+  const filePath = typeof toolInput === 'object' ? toolInput?.file_path : undefined;
+
+  if (typeof filePath === 'string' && filePath.startsWith('/etc')) {
+    return {
+      // Top-level field: message shown to the user
+      systemMessage: 'Remember: system directories like /etc are protected.',
+      // hookSpecificOutput: block the operation
+      hookSpecificOutput: {
+        hookEventName: input.hook_event_name,
+        permissionDecision: 'deny',
+        permissionDecisionReason: 'Writing to /etc is not allowed',
+      },
+    };
+  }
+  return {};
+};
+
+for await (const message of query({
+  prompt: 'Write a config file to /etc/myapp.conf',
+  options: {
+    hooks: {
+      PreToolUse: [{ matcher: 'Write|Edit', hooks: [blockEtcWrites] }],
+    },
+    maxTurns: 3,
+  },
+})) {
+  if (message.type === 'assistant' || message.type === 'result') {
+    console.log(message);
+  }
+}