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

The SDK declares AI SDK and Zod as required package peers. The TanStack entry point uses its own execution loop:

pnpm add ai zod

npm install ai zod

yarn add ai zod

bun add ai zod

Optional: TanStack AI

Install @tanstack/ai and a model adapter. The TanStack AI guide includes installation commands for Gateway chat and Jev evaluation. Gateway is optional when you supply another chat adapter and your own evaluation adapter.

Optional: eve extension (recommended for eve agents)

For eve filesystem-first agents, install @github-tools/eve-extension and its eve peer (which itself requires ai v7). The extension declares eve as * so your agent supplies the runtime copy; eve checks the extension's generated capability metadata rather than an npm range:

pnpm add @github-tools/eve-extension eve

npm install @github-tools/eve-extension eve

yarn add @github-tools/eve-extension eve

bun add @github-tools/eve-extension eve

See Build a GitHub agent with the eve extension: the full agent is 3 files, mounted under agent/extensions/.

Optional: eve direct import (deprecated)

The lower-level @github-tools/sdk/eve import still works for existing agent/tools/ setups, but is deprecated in favor of the extension above. It needs eve and ai v7 on top of the SDK itself:

pnpm add eve ai

npm install eve ai

yarn add eve ai

bun add eve ai

See eve (direct import) for the deprecated instructions.

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.