@ai-coding/github-agent

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

🤖 GitHub Automation

• 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

🔧 Development Tools

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

🌐 Multi-Language Support

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

Installation

npm install @ai-coding/github-agent
# or
pnpm add @ai-coding/github-agent
# or
yarn add @ai-coding/github-agent

Quick Start

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

🚀 Automatic Repository Context Injection

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

Before (Manual Validation):

# Agent had to run these commands manually:
pwd
git remote -v
# Validate GitHub repository
# Then proceed with operation

After (Automatic Injection):

// 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:

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

Configuration

GitHub Authentication

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

export GITHUB_PERSONAL_ACCESS_TOKEN=your_github_token_here

Language Configuration

The GitHub Agent supports multiple languages for communication:

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:

// 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' });

Code Formatting Configuration

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.

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:

// 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

# 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