Installation
Install the SDK
pnpm add @github-tools/sdk
npm install @github-tools/sdk
yarn add @github-tools/sdk
bun add @github-tools/sdk
Add peer dependencies
Required: AI SDK and Zod
The SDK 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: durable workflows
For durable agents with the Vercel Workflow SDK, add workflow and @workflow/ai when you import from @github-tools/sdk/workflow and use createDurableGithubAgent:
pnpm add workflow @workflow/ai
npm install workflow @workflow/ai
yarn add workflow @workflow/ai
bun add workflow @workflow/ai
See Durable workflows (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' })
.env locally and secret managers (Vercel, GitHub Actions secrets) in CI/production.Choose a token type
| Token type | When to use | Scope control |
|---|---|---|
| Fine-grained PAT | Production assistants | per-repository, per-permission |
| Classic PAT | Quick prototyping | broad, org-level |
See Configure token scopes for a detailed permission matrix.
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.
AI assistant prompt (integrate into this repo)
Use in Cursor, Claude Code, or any chat wired to your codebase:
Add @github-tools/sdk to this existing project for use with the Vercel AI SDK.
- Install @github-tools/sdk, ai, and zod; ensure GITHUB_TOKEN can be read from the environment
- Show a minimal example using createGithubTools with generateText or streamText
- Use a preset (e.g. code-review or repo-explorer) appropriate for this codebase unless full maintainer access is required
- Cite https://github-tools.com/getting-started/installation and https://github-tools.com/guide/quick-start
For the packaged skill (same domain), see Agent Skills.