Api

API Reference

Browse all tools Commit attribution Durable workflows

Type signatures for createGithubTools, createGithubAgent, createDurableGithubAgent, and createOctokit.

`createGithubTools(options?)`

Returns a record of AI SDK tools you can pass to generateText or streamText. All options are optional — the SDK reads GITHUB_TOKEN from your environment by default:

types.ts

type GithubToolsOptions = {
  token?: string
  requireApproval?: boolean | Partial<Record<GithubWriteToolName, boolean>>
  overrides?: Partial<Record<string, ToolOverrides>>
  preset?: GithubToolPreset | GithubToolPreset[]
  author?: CommitIdentity
  committer?: CommitIdentity
  coAuthors?: CommitIdentity[]
}

type CommitIdentity = {
  name: string
  email: string
}

type GithubToolPreset =
  | 'code-review'
  | 'issue-triage'
  | 'repo-explorer'
  | 'ci-ops'
  | 'maintainer'

Minimal usage — reads GITHUB_TOKEN automatically:

minimal.ts

import { createGithubTools } from '@github-tools/sdk'

const tools = createGithubTools()

With a preset and explicit token:

with-options.ts

import { createGithubTools } from '@github-tools/sdk'

const tools = createGithubTools({
  token: 'github_pat_xxxxxxxxxxxx',
  preset: 'repo-explorer',
})

See Scope with presets for preset details and Control write safety for approval options.

Tool overrides

The overrides option lets you customize any AI SDK tool() property on a per-tool basis, keyed by tool name:

overrides.ts

import { createGithubTools } from '@github-tools/sdk'

const tools = createGithubTools({
  overrides: {
    deleteGist: { needsApproval: false },
    listIssues: { description: 'List bugs for the current sprint' },
  },
})

type.ts

import type { ToolOverrides } from '@github-tools/sdk'

Supported override properties:

Property	Type	Description
`description`	`string`	Custom tool description for the model
`title`	`string`	Human-readable title
`strict`	`boolean`	Strict mode for input generation
`needsApproval`	`boolean \| function`	Gate execution behind approval
`providerOptions`	`ProviderOptions`	Provider-specific metadata
`onInputStart`	`function`	Callback when argument streaming starts
`onInputDelta`	`function`	Callback on each streaming delta
`onInputAvailable`	`function`	Callback when full input is available
`toModelOutput`	`function`	Custom mapping of tool result to model output

Core properties (execute, inputSchema, outputSchema) cannot be overridden.

Commit attribution

The author, committer, and coAuthors options control how commits are attributed when using createOrUpdateFile or mergePullRequest:

attribution.ts

import { createGithubTools } from '@github-tools/sdk'

const tools = createGithubTools({
  token: 'github_pat_xxxxxxxxxxxx',
  coAuthors: [
    { name: 'my-bot[bot]', email: '12345+my-bot[bot]@users.noreply.github.com' }
  ]
})

Option	Type	Description
`author`	`CommitIdentity`	The person who wrote the code. Falls back to the authenticated user.
`committer`	`CommitIdentity`	The person who applied the commit. Falls back to the authenticated user.
`coAuthors`	`CommitIdentity[]`	Additional contributors. Added as `Co-authored-by` trailers to commit messages.

Commits made via the GitHub API are automatically signed by GitHub's web-flow key, passing branch protection rules that require signed commits.

See Commit attribution for detailed guidance.

`createGithubAgent(options)`

Returns a ToolLoopAgent with GitHub tools and system instructions pre-configured. The token is also auto-detected from GITHUB_TOKEN:

types.ts

type GithubAgentOptions = {
  model: string
  token?: string
  preset?: GithubToolPreset | GithubToolPreset[]
  requireApproval?: boolean | Partial<Record<GithubWriteToolName, boolean>>
  system?: string
  author?: CommitIdentity
  committer?: CommitIdentity
  coAuthors?: CommitIdentity[]
}

Use this when you want:

reusable .generate() / .stream() calls across multiple prompts
preset-aware system instructions without manual wiring
a centralized agent definition shared across your codebase

agent.ts

import { createGithubAgent } from '@github-tools/sdk'

const agent = createGithubAgent({
  model: 'anthropic/claude-sonnet-4.6',
  preset: 'code-review',
  system: 'You review PRs for security issues. Cite file paths and line numbers.',
})

`createDurableGithubAgent(options)`

Returns a DurableAgent for use inside a Vercel Workflow function ("use workflow"). Each LLM step and each GitHub tool invocation runs as a durable, retryable workflow step. Import from the workflow subpath:

import.ts

import { createDurableGithubAgent } from '@github-tools/sdk/workflow'

Requires optional peer dependencies workflow and @workflow/ai — see Installation.

Options align with createGithubAgent (model, token, preset, requireApproval, instructions, additionalInstructions, maxSteps, temperature, and other agent options passed through). Important: requireApproval is accepted for forward compatibility but is currently ignored by DurableAgent; use createGithubAgent when you need interactive approval on writes.

durable-agent.ts

import { createDurableGithubAgent } from '@github-tools/sdk/workflow'
import { getWritable } from 'workflow'
import type { ModelMessage, UIMessageChunk } from 'ai'

export async function githubAssistant(messages: ModelMessage[], token: string) {
  'use workflow'

  const agent = createDurableGithubAgent({
    model: 'anthropic/claude-sonnet-4.6',
    token,
    preset: 'maintainer',
  })
  const writable = getWritable<UIMessageChunk>()
  await agent.stream({ messages, writable })
}

Conceptual overview: Durable workflows (Vercel Workflow).

`createOctokit(token?)`

Returns a configured @octokit/rest instance. Use this when you need lower-level GitHub API access or want to build custom tool factories:

custom-tool.ts

import { createOctokit } from '@github-tools/sdk'

const octokit = createOctokit()
const { data } = await octokit.repos.get({ owner: 'HugoRCD', repo: 'github-tools' })

AI assistant prompt (Octokit → AI SDK tools)

Prompt

This file uses Octokit for calls that should be model-driven. Migrate the LLM-facing surface to @github-tools/sdk: createGithubTools or createGithubAgent with the right preset so the model uses typed AI SDK tools.

- Preserve behavior; prefer presets from https://github-tools.com/guide/presets
- Keep createOctokit from @github-tools/sdk only for non-LLM / server-only code

External references

Edit this pageorReport an issue

Tools Catalog

Every available tool, grouped by domain and write-safety status. Tools run as durable workflow steps when used with Vercel Workflow.