> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentium.in/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub

> Interact with GitHub repos, issues, PRs, and file content.

# GitHub

Interact with GitHub repositories, issues, pull requests, and file content via the GitHub REST API.

***

## Quick Start

```typescript theme={null}
import { Agent, openai, GitHubToolkit } from "@agentium/core";

const gh = new GitHubToolkit();
// Uses GITHUB_TOKEN env var

const agent = new Agent({
  name: "github-assistant",
  model: openai("gpt-4o"),
  instructions: "Help manage GitHub repositories and issues.",
  tools: [...gh.getTools()],
});

const result = await agent.run("List open issues in agentiumOS/agentium");
```

***

## Config

<ParamField body="token" type="string">
  GitHub personal access token. Falls back to `GITHUB_TOKEN` env var.
</ParamField>

<ParamField body="apiBase" type="string" default="https://api.github.com">
  GitHub API base URL. Override for GitHub Enterprise.
</ParamField>

***

## Tools

| Tool                      | Description                                                       |
| ------------------------- | ----------------------------------------------------------------- |
| `github_search_repos`     | Search repositories by query. Returns names, stars, descriptions. |
| `github_list_issues`      | List issues for a repository (excludes PRs).                      |
| `github_get_issue`        | Get full details of a specific issue.                             |
| `github_create_issue`     | Create a new issue with title, body, and labels.                  |
| `github_list_prs`         | List pull requests for a repository.                              |
| `github_get_file_content` | Get file content from a repo (auto-decodes base64).               |

***

## Environment Variables

```bash theme={null}
export GITHUB_TOKEN="ghp_..."
```

Create a token at [github.com/settings/tokens](https://github.com/settings/tokens). Required scopes depend on your use case — `repo` for private repos, `public_repo` for public only.

***

## Tool Usage Examples

### List Issues

```typescript theme={null}
const result = await agent.run("List all open bugs in agentiumOS/agentium");

// The agent calls github_list_issues with:
// { owner: "agentiumOS", repo: "agentium", state: "open", labels: "bug" }
//
// Returns:
// #42 — Memory leak in SessionManager (bug, high-priority)
// #38 — Tool router fails with empty tool list (bug)
// #35 — CostTracker reports zero tokens (bug, fixed)
```

### Create Issue

```typescript theme={null}
const result = await agent.run(
  "Create an issue in agentiumOS/agentium titled 'Add retry logic to MCP client' " +
  "with label 'enhancement'. The body should describe adding exponential backoff."
);

// The agent calls github_create_issue with:
// {
//   owner: "agentiumOS",
//   repo: "agentium",
//   title: "Add retry logic to MCP client",
//   body: "Add exponential backoff retry logic to the MCP client...",
//   labels: ["enhancement"]
// }
```

### Search Repos

```typescript theme={null}
const result = await agent.run("Find popular TypeScript AI agent frameworks on GitHub");

// The agent calls github_search_repos with:
// { query: "AI agent framework language:typescript", sort: "stars" }
//
// Returns top repositories with stars, descriptions, and URLs
```

### Read File Content

```typescript theme={null}
const result = await agent.run(
  "Show me the package.json from agentiumOS/agentium"
);

// The agent calls github_get_file_content with:
// { owner: "agentiumOS", repo: "agentium", path: "package.json" }
```