Installation

Install the SDK

pnpm add @github-tools/sdk

npm install @github-tools/sdk

yarn add @github-tools/sdk

bun add @github-tools/sdk

Pick your peer dependencies

What you install next depends on the framework you build on:

Required: AI SDK and Zod

Every entry point relies on AI SDK for tool execution and Zod for schema validation:

pnpm add ai zod

npm install ai zod

yarn add ai zod

bun add ai zod

Optional: eve agents

For eve filesystem-first agents, add eve and ai v7 when you import from @github-tools/sdk/eve:

pnpm add eve ai

npm install eve ai

yarn add eve ai

bun add eve ai

See Build a GitHub agent with eve — the full agent is 3 files.

Optional: durable workflows

For durable agents with the Vercel Workflow SDK, add workflow and @ai-sdk/workflow when you import from @github-tools/sdk/workflow and use createDurableGithubAgent:

pnpm add workflow @ai-sdk/workflow

npm install workflow @ai-sdk/workflow

yarn add workflow @ai-sdk/workflow

bun add workflow @ai-sdk/workflow

See Durable agents with Vercel Workflow for the full pattern.

Set your GitHub token

The SDK reads GITHUB_TOKEN from your environment automatically. Create a .env file at the root of your project:

GITHUB_TOKEN=github_pat_xxxxxxxxxxxx

You can also pass the token explicitly if you prefer:

createGithubTools({ token: 'github_pat_xxxxxxxxxxxx' })

Choose a token type

See Tokens and authentication for the detailed permission matrix and the Vercel Connect setup.

Verify the setup

Run a minimal script to confirm the SDK initializes and a read tool resolves:

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

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

console.log('Tools loaded:', Object.keys(tools).join(', '))

If the script prints tool names, your environment is ready. Continue with Run your first call.

For the packaged skill (same domain), see Agent Skills.