npm package: @manet/ose
Description: A Self-iterating Autonomous Coding Agent, built for Open-Source Engineers
Latest version: 0.0.4

# OSE: Open Source Engineer

> [!NOTE] > **Status:** This project is currently under development and is built on MANET.

[![npm version](https://badge.fury.io/js/@manet/ose.svg)](https://badge.fury.io/js/@manet/ose)
[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=flat&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![GitHub issues](https://img.shields.io/github/issues/agent-contrib/github-agent)](https://github.com/agent-contrib/github-agent/issues)
[![GitHub stars](https://img.shields.io/github/stars/agent-contrib/github-agent)](https://github.com/agent-contrib/github-agent/stargazers)

A powerful Open Source Engineer 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

```bash
npm install @manet/ose
# or
pnpm add @manet/ose
# or
yarn add @manet/ose
```

## Quick Start

```typescript
import { OSEAgent } from '@manet/ose';

const agent = new OSEAgent({
  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 Open Source Engineer 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

### GitHub Authentication

The Open Source Engineer requires a GitHub Personal Access Token to interact with GitHub APIs:

```bash
export GITHUB_PERSONAL_ACCESS_TOKEN=your_github_token_here
```

### Language Configuration

The Open Source Engineer supports multiple languages for communication:

```typescript
const agent = new OSEAgent({
  // ... 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 OSEAgent({ language: 'en' });

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

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

### Code Formatting Configuration

The Open Source Engineer 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 OSEAgent({
  // ... 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 OSEAgent({
  workspace: '/path/to/typescript-project',
  enableCodeFormatting: true, // Will use Prettier if config found
});

// Disable formatting (default behavior)
const safeAgent = new OSEAgent({
  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 Open Source Engineer 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](https://github.com/agent-contrib)

## Related Projects

- [@mcp-agent/core](https://www.npmjs.com/package/@mcp-agent/core) - Core MCP Agent framework
- [@agent-infra/mcp-server-commands](https://www.npmjs.com/package/@agent-infra/mcp-server-commands) - Command execution server
- [GitHub MCP Server](https://github.com/github/github-mcp-server) - Official GitHub MCP integration