GitHub Agent

> [!NOTE] > Status: This project is currently under development and is built on the TARS Stack. Please visit TARS Stack for more information.


A powerful GitHub Agent built on the MCP (Model Context Protocol) framework that enables intelligent interaction with GitHub repositories through natural language commands. Features automatic repository context injection for seamless GitHub operations without manual validation steps.

Features

$3

- Automatic Repository Context Injection - No manual validation required
- Semantic branch management and automated PRs
- Issue creation with intelligent labeling
- Code reviews with CI/CD status validation
- Smart repository detection and GitHub integration

$3

- Intelligent code search and analysis
- File operations and dependency management
- Template generation and documentation
- Workflow automation and notifications

$3

- 6 languages with auto-detection
- Localized templates and documentation
- Consistent communication across operations

Installation

``bash
npm install @ai-coding/github-agent


or

pnpm add @ai-coding/github-agent

or

yarn add @ai-coding/github-agent
`

Quick Start

`typescript
import { GithubAgent } from '@ai-coding/github-agent';

const agent = new GithubAgent({
model: {
provider: 'openai', // or your preferred provider
id: 'gpt-4',
apiKey: process.env.OPENAI_API_KEY,
},
workspace: process.cwd(), // your working directory
language: 'en', // optional: 'en', 'zh', 'ja', 'es', 'fr', 'de', 'auto'
enableCodeFormatting: false, // optional: enable automatic code formatting
});

// Use the agent
const response = await agent.run(
'Create a new issue in my repository about bug fixes',
);
console.log(response.content);
`

Prerequisites

- GitHub Personal Access Token: Set GITHUB_PERSONAL_ACCESS_TOKEN environment variable
- Docker: Required for running the GitHub MCP server
- Node.js: Version 16 or higher

Key Features

$3

The GitHub Agent automatically detects and injects repository context before each operation, eliminating the need for manual validation commands:

Before (Manual Validation):

`bash


Agent had to run these commands manually:

pwd
git remote -v

Validate GitHub repository

Then proceed with operation

`

After (Automatic Injection):

`typescript
// Repository context is automatically available:
// - Working directory: /path/to/your/repo
// - GitHub repository: owner/repo-name
// - Git remotes: origin, upstream, etc.
// - Validation status: valid/invalid
`

Performance Benefits:

- ⚡ 200-500ms faster response times per operation
- 🔄 Zero redundant command execution
- 🎯 Smart caching with 30-second TTL
- 🛡️ Graceful fallback for non-Git directories

How it works:

1. onPrepareRequest Hook: Injects repository context into system prompt with intelligent caching
2. Smart Cache Management: 30-second TTL automatically refreshes context when needed
3. Intelligent Caching: Avoids redundant Git commands with smart invalidation
4. Error Handling: Gracefully handles non-Git directories and invalid repositories

Configuration

$3

The GitHub Agent requires a GitHub Personal Access Token to interact with GitHub APIs:

`bash
export GITHUB_PERSONAL_ACCESS_TOKEN=your_github_token_here
`

$3

The GitHub Agent supports multiple languages for communication:

`typescript
const agent = new GithubAgent({
// ... other options
language: 'zh', // Chinese
});

// Supported languages:
// 'en' - English (default)
// 'zh' - Chinese (中文)
// 'ja' - Japanese (日本語)
// 'es' - Spanish (Español)
// 'fr' - French (Français)
// 'de' - German (Deutsch)
// 'auto' - Auto-detect from system locale
`

Examples:

`typescript
// English Agent (default)
const enAgent = new GithubAgent({ language: 'en' });

// Chinese Agent - will create issues and PRs in Chinese
const zhAgent = new GithubAgent({ language: 'zh' });

// Auto-detect language from system
const autoAgent = new GithubAgent({ language: 'auto' });
`

$3

The GitHub Agent can automatically detect and format code when making changes. This feature is disabled by default to prevent unintended formatting of existing code.

`typescript
const agent = new GithubAgent({
// ... other options
enableCodeFormatting: true, // Enable automatic code formatting
});
`

Supported Formatters:

- Prettier for TypeScript/JavaScript (.ts, .tsx, .js, .jsx, .json, .md)
- Black for Python (.py)

Smart Detection:

- Auto-detects formatter configs in project root
- Only formats modified files, never touches unrelated files
- Runs formatter after code changes, before commit

Configuration Files Detected:

- Prettier: .prettierrc, .prettierrc.json, prettier.config.js
- Black: pyproject.toml, setup.cfg

Example Usage:

`typescript
// Enable formatting for a TypeScript project with Prettier
const agent = new GithubAgent({
workspace: '/path/to/typescript-project',
enableCodeFormatting: true, // Will use Prettier if config found
});

// Disable formatting (default behavior)
const safeAgent = new GithubAgent({
workspace: '/path/to/any-project',
enableCodeFormatting: false, // No automatic formatting
});
`

> ⚠️ Important: Code formatting is disabled by default to avoid unintended changes to existing codebases. Enable it only when you want the agent to automatically format code during development.

Development

`bash


Install dependencies

pnpm bootstrap

Run example

pnpm example

Build the project

pnpm build

Run tests

pnpm test

Watch mode for development

pnpm dev
``

Architecture

The GitHub Agent leverages:

- MCP Core: Foundation for agent communication
- GitHub MCP Server: Docker-based GitHub API integration
- Commands Server: Local command execution capabilities
- Prompt Engineering: Advanced tool calling engine

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT © agent-contrib

Related Projects

- @mcp-agent/core - Core MCP Agent framework
- @agent-infra/mcp-server-commands - Command execution server
- GitHub MCP Server - Official GitHub MCP integration