SDK Reference

import { query } from "@open-gitagent/gitagent";

for await (const msg of query({
  repo: "https://github.com/your-gitagent",
  prompt: "Summarise the open pull requests",
})) {
  if (msg.type === "assistant") console.log(msg.content);
}

import { query } from "@open-gitagent/gitagent";

for await (const msg of query({
  prompt: "Refactor the auth module in src/auth.ts",
  model: "anthropic:claude-sonnet-4-6",
  dir: "./my-project",
})) {
  if (msg.type === "assistant") console.log(msg.content);
}

import { query } from "@open-gitagent/gitagent";

for await (const msg of query({
  prompt: "Refactor the auth module",
  dir: "/path/to/agent",
  model: "anthropic:claude-sonnet-4-6",
})) {
  switch (msg.type) {
    case "delta":       // streaming text chunk
      process.stdout.write(msg.content); break;
    case "assistant":   // complete response
      console.log(`\nTokens: ${msg.usage?.totalTokens}`); break;
    case "tool_use":    // tool invocation
      console.log(`Tool: ${msg.toolName}(${JSON.stringify(msg.args)})`); break;
    case "tool_result": // tool output
      console.log(`Result: ${msg.content}`); break;
    case "system":      // lifecycle events & errors
      console.log(`[${msg.subtype}] ${msg.content}`); break;
  }
}

import { query, tool } from "@open-gitagent/gitagent";

const search = tool(
  "search_docs",
  "Search the documentation",
  {
    properties: {
      query: { type: "string", description: "Search query" },
      limit: { type: "number", description: "Max results" },
    },
    required: ["query"],
  },
  async (args) => {
    const results = await mySearchEngine(args.query, args.limit ?? 10);
    return { text: JSON.stringify(results), details: { count: results.length } };
  },
);

for await (const msg of query({ prompt: "Find auth docs", tools: [search] })) {
  // agent can now call search_docs
}

import { buildTool } from "@open-gitagent/gitagent";

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

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")) {
        return { action: "block", reason: "Manual approval required" };
      }
      return { action: "allow" };
    },
    postToolFailure: async (ctx) => {
      console.error(`Tool ${ctx.toolName} failed: ${ctx.error}`);
    },
    preQuery: async (ctx) => {
      console.log(`Sending prompt to LLM: ${ctx.sessionId}`);
      return { action: "allow" };
    },
    postResponse: async (ctx) => {
      console.log(`Session ${ctx.sessionId} responded`);
    },
    fileChanged: async (ctx) => {
      console.log(`File changed: ${ctx.path}`);
    },
    onError: async (ctx) => {
      console.error(`Error in ${ctx.sessionId}: ${ctx.error}`);
    },
  },
});

const result = query({ prompt: "...", dir: "..." });

for await (const msg of result) { /* handle messages */ }

const costs = result.costs();
console.log(`Cost: $${costs.totalCostUsd.toFixed(4)}`);
console.log(`Tokens: ${costs.totalInputTokens} in / ${costs.totalOutputTokens} out`);