SDK

SDK

GitClaw can be used programmatically as an npm package.

Installation

npm install gitclaw

Basic Usage

import { query } from "gitclaw";

const result = query({
  prompt: "Create a Python script that sorts a CSV file by the 'date' column",
  dir: "/path/to/agent",
});

for await (const msg of result) {
  if (msg.type === "assistant") {
    console.log(msg.content);
  }
  if (msg.type === "tool_use") {
    console.log(`Using tool: ${msg.toolName}`);
  }
}

// Get cost breakdown
console.log(result.costs());

Custom Tools

import { query, tool } from "gitclaw";

const weatherTool = tool(
  "get_weather",
  "Get current weather for a city",
  { properties: { city: { type: "string" } }, required: ["city"] },
  async (args) => {
    const res = await fetch(`https://api.weather.com/${args.city}`);
    return await res.text();
  }
);

const result = query({
  prompt: "What's the weather in Tokyo?",
  dir: "/path/to/agent",
  tools: [weatherTool],
});

buildTool Factory

import { buildTool } from "gitclaw";

const myTool = buildTool({
  name: "search_docs",
  description: "Search documentation",
  parameters: { properties: { query: { type: "string" } }, required: ["query"] },
  execute: async (args) => {
    // ... search logic
    return "Results: ...";
  },
  metadata: {
    isConcurrencySafe: true,   // safe to run in parallel
    isReadOnly: true,           // no side effects
    maxResultSizeChars: 20000,  // truncate large results
  },
});

Hooks

const result = query({
  prompt: "Deploy to production",
  dir: "/path/to/agent",
  hooks: {
    onSessionStart: async (ctx) => ({ action: "allow" }),
    preToolUse: async (ctx) => {
      if (ctx.toolName === "cli" && ctx.args.command.includes("deploy")) {
        console.log("Deployment detected — requiring approval");
        return { action: "block", reason: "Manual approval required" };
      }
      return { action: "allow" };
    },
    postResponse: async (ctx) => {
      console.log(`Session ${ctx.sessionId} responded`);
    },
    onError: async (ctx) => {
      console.error(`Error in session ${ctx.sessionId}: ${ctx.error}`);
    },
  },
});

Query Options

query({
  prompt: "...",                          // string or AsyncIterable<GCUserMessage>
  dir: "/path/to/agent",                 // agent directory
  model: "anthropic:claude-opus-4-6",    // override model
  env: "production",                      // load config/production.yaml
  systemPrompt: "Custom prompt...",       // replace system prompt
  systemPromptSuffix: "Extra context...", // append to system prompt
  tools: [myTool],                        // inject custom tools
  replaceBuiltinTools: true,              // disable built-in tools
  allowedTools: ["read", "write"],        // whitelist
  disallowedTools: ["cli"],               // blacklist
  maxTurns: 10,                           // limit agent turns
  constraints: { temperature: 0 },        // model constraints
  sessionId: "custom-id",                 // custom session ID
  abortController: new AbortController(), // cancel execution
});