A Self-iterating Autonomous Coding Agent, built for Open-Source Engineers
npm install @ai-coding/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.
- 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
- Intelligent code search and analysis
- File operations and dependency management
- Template generation and documentation
- Workflow automation and notifications
- 6 languages with auto-detection
- Localized templates and documentation
- Consistent communication across operations
``bash`
npm install @ai-coding/github-agentor
pnpm add @ai-coding/github-agentor
yarn add @ai-coding/github-agent
`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);
`
- 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
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 -vValidate 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
The GitHub Agent requires a GitHub Personal Access Token to interact with GitHub APIs:
`bash`
export GITHUB_PERSONAL_ACCESS_TOKEN=your_github_token_here
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' });
`
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.jspyproject.toml
- Black: , 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.
`bashInstall dependencies
pnpm bootstrap
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
Contributions are welcome! Please feel free to submit a Pull Request.
MIT © agent-contrib
- @mcp-agent/core - Core MCP Agent framework
- @agent-infra/mcp-server-commands - Command execution server
- GitHub MCP Server - Official GitHub MCP integration