Add GitHub Mode to MyCoder

[bhouston]

Add GitHub Mode to MyCoder

Goal

Implement a "GitHub mode" for MyCoder that enables the agent to work with GitHub issues and PRs as its primary workflow. When enabled, the agent will:

• Start from existing GitHub issues or create new ones for tasks
• Create branches for issues it's working on
• Create PRs when work is complete
• Create additional GitHub issues for follow-up tasks or ideas

Problem Statement

Currently, MyCoder operates primarily on local files and doesn't have a built-in way to track tasks through GitHub. Adding GitHub integration would allow the agent to use GitHub as its external memory and persistence layer, providing better continuity between sessions and making it easier to track progress on larger projects.

Requirements

• GitHub mode should be configurable globally and persist in the .mycoder settings directory
• The agent should use the GitHub CLI (gh) for all GitHub interactions
• In GitHub mode, the agent should:
  • Read from or create GitHub issues for tasks
  • Create branches for issues it's working on
  • Make commits and push changes
  • Create PRs linked to issues
  • Create additional GitHub issues for follow-up tasks or ideas

Feasibility Study

The implementation is highly feasible as:

1. GitHub CLI (gh) is already available and provides a simple interface to GitHub
2. MyCoder already has a settings directory structure at ~/.mycoder
3. The agent already has shell execution capabilities
4. The changes are mostly additive and don't require significant refactoring

Implementation Plan

See the detailed implementation plan in the attached file: github_mode_implementation_plan.md

Key components include:

1. Adding GitHub settings storage in the .mycoder directory
2. Creating CLI flags to enable GitHub mode
3. Implementing GitHub tools for issue and PR management
4. Updating the system prompt to include GitHub mode instructions
5. Adding documentation for the new feature

Dependencies

• GitHub CLI (gh) needs to be installed and authenticated
• User needs to have appropriate GitHub permissions for the target repository

Timeline

This feature can be implemented in approximately 1-2 weeks, with most of the time spent on testing and documentation.

[bhouston]

GitHub Mode Implementation Plan for MyCoder

Overview

This implementation plan details how to add GitHub mode to MyCoder, allowing the agent to work with GitHub issues and PRs as part of its workflow.

File Changes

1. Settings Module Updates

packages/cli/src/settings/settings.ts

• Add GitHub mode configuration management:

// Add to existing imports
import * as path from 'path';
import * as fs from 'fs';

// Add GitHub settings interface
interface GitHubSettings {
  enabled: boolean;
  repository?: string;
  defaultBranch?: string;
  createIssuesForIdeas: boolean;
}

// Add default GitHub settings
const defaultGitHubSettings: GitHubSettings = {
  enabled: false,
  createIssuesForIdeas: true,
};

// Add GitHub settings file path
const githubSettingsFile = path.join(settingsDir, 'github.json');

// Add functions to get and update GitHub settings
export const getGitHubSettings = (): GitHubSettings => {
  if (!fs.existsSync(githubSettingsFile)) {
    return defaultGitHubSettings;
  }
  try {
    return JSON.parse(fs.readFileSync(githubSettingsFile, 'utf-8'));
  } catch (error) {
    return defaultGitHubSettings;
  }
};

export const updateGitHubSettings = (settings: Partial<GitHubSettings>): GitHubSettings => {
  const currentSettings = getGitHubSettings();
  const updatedSettings = { ...currentSettings, ...settings };
  fs.writeFileSync(githubSettingsFile, JSON.stringify(updatedSettings, null, 2));
  return updatedSettings;
};

export const enableGitHubMode = (repository?: string, defaultBranch?: string): GitHubSettings => {
  return updateGitHubSettings({ 
    enabled: true, 
    repository, 
    defaultBranch
  });
};

export const disableGitHubMode = (): GitHubSettings => {
  return updateGitHubSettings({ enabled: false });
};

2. CLI Command Updates

packages/cli/src/options.ts

• Add GitHub mode option:

// Add to sharedOptions
github: {
  type: 'boolean',
  description: 'Enable GitHub mode for working with issues and PRs',
  default: false,
},
githubRepo: {
  type: 'string',
  description: 'GitHub repository to use (format: owner/repo)',
},

packages/cli/src/commands/$default.ts

• Update the handler to enable GitHub mode if requested:

// Add to imports
import { 
  hasUserConsented, 
  saveUserConsent, 
  getGitHubSettings, 
  enableGitHubMode 
} from '../settings/settings.js';

// Add to the handler function after consent check
if (argv.github) {
  const githubSettings = getGitHubSettings();
  
  if (argv.githubRepo || !githubSettings.repository) {
    // If repository is provided or not configured, update settings
    enableGitHubMode(argv.githubRepo);
    logger.info(`GitHub mode enabled for repository: ${argv.githubRepo || githubSettings.repository || 'not specified'}`);
  } else {
    // Use existing repository configuration
    enableGitHubMode();
    logger.info(`GitHub mode enabled for repository: ${githubSettings.repository}`);
  }
}

3. GitHub Tools Implementation

packages/agent/src/tools/github/index.ts (New File)

export * from './githubIssue.js';
export * from './githubPR.js';

packages/agent/src/tools/github/githubIssue.ts (New File)

import { z } from 'zod';
import { Tool } from '../../core/types.js';
import { executeShellCommand } from '../system/shellExecute.js';

// Schema for creating a GitHub issue
const createIssueSchema = z.object({
  title: z.string().describe('Title of the GitHub issue'),
  body: z.string().describe('Body content of the GitHub issue'),
  labels: z.array(z.string()).optional().describe('Labels to apply to the issue'),
});

// Schema for getting a GitHub issue
const getIssueSchema = z.object({
  issueNumber: z.number().describe('Issue number to retrieve'),
});

/**
 * Creates a new GitHub issue
 */
export const createGitHubIssueTool: Tool = {
  name: 'createGitHubIssue',
  description: 'Creates a new GitHub issue in the configured repository',
  schema: createIssueSchema,
  execute: async ({ title, body, labels }) => {
    // Prepare labels argument if provided
    const labelsArg = labels && labels.length > 0 
      ? labels.map(label => `-l "${label}"`).join(' ') 
      : '';
    
    // Create the issue using gh cli
    const command = `gh issue create --title "${title}" --body "${body}" ${labelsArg}`;
    const result = await executeShellCommand(command);
    
    return {
      success: !result.error,
      result: result.stdout,
      error: result.error,
    };
  },
};

/**
 * Gets a GitHub issue by number
 */
export const getGitHubIssueTool: Tool = {
  name: 'getGitHubIssue',
  description: 'Gets a GitHub issue by number from the configured repository',
  schema: getIssueSchema,
  execute: async ({ issueNumber }) => {
    // Get the issue using gh cli
    const command = `gh issue view ${issueNumber} --json number,title,body,state,labels,assignees,url`;
    const result = await executeShellCommand(command);
    
    if (result.error) {
      return {
        success: false,
        error: result.error,
      };
    }
    
    // Parse the JSON output
    try {
      const issue = JSON.parse(result.stdout);
      return {
        success: true,
        result: issue,
      };
    } catch (error) {
      return {
        success: false,
        error: `Failed to parse issue data: ${error}`,
      };
    }
  },
};

packages/agent/src/tools/github/githubPR.ts (New File)

import { z } from 'zod';
import { Tool } from '../../core/types.js';
import { executeShellCommand } from '../system/shellExecute.js';

// Schema for creating a GitHub PR
const createPRSchema = z.object({
  title: z.string().describe('Title of the GitHub PR'),
  body: z.string().describe('Body content of the GitHub PR'),
  baseBranch: z.string().optional().describe('Base branch for the PR (default: main)'),
  draft: z.boolean().optional().describe('Whether to create as a draft PR'),
  issueNumber: z.number().optional().describe('Issue number to link to this PR'),
});

/**
 * Creates a new GitHub PR from the current branch
 */
export const createGitHubPRTool: Tool = {
  name: 'createGitHubPR',
  description: 'Creates a new GitHub PR from the current branch',
  schema: createPRSchema,
  execute: async ({ title, body, baseBranch = 'main', draft = false, issueNumber }) => {
    // Prepare command arguments
    const draftArg = draft ? '--draft' : '';
    
    // If issue number is provided, link the PR to the issue
    const bodyWithIssue = issueNumber 
      ? `${body}\n\nCloses #${issueNumber}` 
      : body;
    
    // Create the PR using gh cli
    const command = `gh pr create --title "${title}" --body "${bodyWithIssue}" --base "${baseBranch}" ${draftArg}`;
    const result = await executeShellCommand(command);
    
    return {
      success: !result.error,
      result: result.stdout,
      error: result.error,
    };
  },
};

// Schema for checking out a branch for an issue
const checkoutIssueBranchSchema = z.object({
  issueNumber: z.number().describe('Issue number to create branch for'),
  branchName: z.string().optional().describe('Custom branch name (default: issue-{number})'),
});

/**
 * Creates and checks out a branch for working on a GitHub issue
 */
export const checkoutIssueBranchTool: Tool = {
  name: 'checkoutIssueBranch',
  description: 'Creates and checks out a branch for working on a GitHub issue',
  schema: checkoutIssueBranchSchema,
  execute: async ({ issueNumber, branchName }) => {
    // Generate branch name if not provided
    const branch = branchName || `issue-${issueNumber}`;
    
    // Create and checkout the branch
    const command = `git checkout -b ${branch}`;
    const result = await executeShellCommand(command);
    
    return {
      success: !result.error,
      result: `Checked out branch: ${branch}`,
      error: result.error,
    };
  },
};

4. Update Tool Registry

packages/agent/src/tools/getTools.ts

• Add GitHub tools to the available tools:

// Add to imports
import {
  createGitHubIssueTool,
  getGitHubIssueTool,
  createGitHubPRTool,
  checkoutIssueBranchTool,
} from './github/index.js';

// Add to getTools function
export function getTools(): Tool[] {
  return [
    // ... existing tools
    
    // GitHub tools
    createGitHubIssueTool,
    getGitHubIssueTool,
    createGitHubPRTool,
    checkoutIssueBranchTool,
  ];
}

5. Update System Prompt for GitHub Mode

packages/agent/src/core/toolAgent/config.ts

• Modify the system prompt to include GitHub mode instructions when enabled:

// Add to imports
import { getGitHubSettings } from '../../../../cli/src/settings/settings.js';

// Update getDefaultSystemPrompt function
export function getDefaultSystemPrompt(): string {
  // ... existing code
  
  // Check if GitHub mode is enabled
  const githubSettings = getGitHubSettings();
  const githubModePrompt = githubSettings.enabled
    ? [
        '',
        '=== GitHub Mode Enabled ===',
        `Repository: ${githubSettings.repository || 'Not specified'}`,
        'In GitHub mode, you should:',
        '1. Start by understanding existing GitHub issues or creating new ones for tasks',
        '2. Create feature branches for issues you are working on',
        '3. Make commits with descriptive messages as you implement changes',
        '4. Create pull requests when features are complete',
        '5. Document additional ideas or tasks as new GitHub issues',
        '6. Use the gh CLI tool for all GitHub interactions rather than direct API calls',
        '',
      ].join('\n')
    : '';
  
  return [
    // ... existing system prompt
    githubModePrompt,
  ].join('\n');
}

Testing Plan

1. Test enabling GitHub mode via CLI:

   pnpm cli --github --githubRepo="owner/repo"
   

2. Verify GitHub settings are saved correctly to ~/.mycoder/github.json

3. Test GitHub tools:

   • Create a GitHub issue
   • Get GitHub issue details
   • Create a branch for an issue
   • Create a PR linked to an issue

4. Test end-to-end workflow:

   • Enable GitHub mode
   • Create an issue for a feature
   • Create a branch for the issue
   • Make changes and commits
   • Create a PR linked to the issue

Documentation Updates

1. Update README.md to include GitHub mode information
2. Add a section in the CLI documentation about GitHub mode
3. Create a GitHub workflow guide explaining how to use MyCoder with GitHub

[bhouston]

Updated GitHub Mode Implementation Plan for MyCoder

Overview

This implementation plan details how to add GitHub mode to MyCoder, allowing the agent to work with GitHub issues and PRs as part of its workflow.

Design Decisions

1. Use the GitHub CLI directly: Rather than creating wrapper tools around the GitHub CLI, we'll use the gh CLI tool directly via shell commands. This avoids unnecessary complexity and duplication.

2. Unified settings approach: Instead of creating GitHub-specific settings functions, we'll implement a generic settings system where GitHub mode is just one configuration option.

3. Minimal state tracking: We won't track repository or branch information in settings as these can be determined dynamically using Git and GitHub CLI commands. This allows working with multiple repositories and branches without restrictions.

File Changes

1. Settings Module Updates

packages/cli/src/settings/settings.ts

• Update to use a generic settings approach:

// Add to existing imports
import * as path from 'path';
import * as fs from 'fs';

// Generic settings interface
interface Settings {
  githubMode: boolean;
  createIssuesForIdeas?: boolean;
  // Other settings can be added here
}

// Default settings
const defaultSettings: Settings = {
  githubMode: false,
  createIssuesForIdeas: true,
};

// Settings file path
const settingsFile = path.join(settingsDir, 'settings.json');

// Generic functions to get and update settings
export const getSettings = (): Settings => {
  if (!fs.existsSync(settingsFile)) {
    return defaultSettings;
  }
  try {
    return JSON.parse(fs.readFileSync(settingsFile, 'utf-8'));
  } catch (error) {
    return defaultSettings;
  }
};

export const updateSettings = (settings: Partial<Settings>): Settings => {
  const currentSettings = getSettings();
  const updatedSettings = { ...currentSettings, ...settings };
  fs.writeFileSync(settingsFile, JSON.stringify(updatedSettings, null, 2));
  return updatedSettings;
};

// Convenience functions for GitHub mode
export const enableGitHubMode = (): Settings => {
  return updateSettings({ githubMode: true });
};

export const disableGitHubMode = (): Settings => {
  return updateSettings({ githubMode: false });
};

2. CLI Command Updates

packages/cli/src/options.ts

• Add GitHub mode option:

// Add to sharedOptions
github: {
  type: 'boolean',
  description: 'Enable GitHub mode for working with issues and PRs',
  default: false,
},

packages/cli/src/commands/$default.ts

• Update the handler to enable GitHub mode if requested:

// Add to imports
import { 
  hasUserConsented, 
  saveUserConsent, 
  getSettings, 
  enableGitHubMode 
} from '../settings/settings.js';

// Add to the handler function after consent check
if (argv.github) {
  enableGitHubMode();
  logger.info('GitHub mode enabled');
}

3. Update System Prompt for GitHub Mode

packages/agent/src/core/toolAgent/config.ts

• Modify the system prompt to include GitHub mode instructions when enabled:

// Add to imports
import { getSettings } from '../../../../cli/src/settings/settings.js';

// Update getDefaultSystemPrompt function
export function getDefaultSystemPrompt(): string {
  // ... existing code
  
  // Check if GitHub mode is enabled
  const settings = getSettings();
  const githubModePrompt = settings.githubMode
    ? [
        '',
        '=== GitHub Mode Enabled ===',
        'In GitHub mode, you should:',
        '1. Start by understanding existing GitHub issues or creating new ones for tasks',
        '2. Create feature branches for issues you are working on',
        '3. Make commits with descriptive messages as you implement changes',
        '4. Create pull requests when features are complete',
        '5. Document additional ideas or tasks as new GitHub issues',
        '6. Use the gh CLI tool directly for all GitHub interactions',
        '   - For issue creation: gh issue create --title "Title" --body $\'Multiline\\nContent\'',
        '   - For PR creation: gh pr create --title "Title" --body $\'Description\'',
        '   - For checking issues: gh issue list --state open',
        '   - For viewing an issue: gh issue view [number]',
        '7. Use git commands directly for branch management:',
        '   - git checkout -b issue-123',
        '   - git add .',
        '   - git commit -m "Descriptive message"',
        '   - git push -u origin issue-123',
        '',
        'Note: When passing multiline text to gh CLI commands, use the $\'string\' syntax in bash to properly interpret escape sequences.',
        '',
      ].join('\n')
    : '';
  
  return [
    // ... existing system prompt
    githubModePrompt,
  ].join('\n');
}

Testing Plan

1. Test enabling GitHub mode via CLI:

   pnpm cli --github
   

2. Verify settings are saved correctly to ~/.mycoder/settings.json

3. Test end-to-end workflow:

   • Enable GitHub mode
   • Use GitHub CLI directly to create an issue
   • Create a branch for the issue using git commands
   • Make changes and commits
   • Create a PR linked to the issue using GitHub CLI

Documentation Updates

1. Update README.md to include GitHub mode information
2. Add a section in the CLI documentation about GitHub mode
3. Create a GitHub workflow guide explaining how to use MyCoder with GitHub

[bhouston]

Settings Command Implementation for GitHub Mode

Based on CLI best practices from tools like git, gcloud, and npm, we should implement a dedicated settings command for MyCoder. This will provide a consistent interface for managing all global settings, including GitHub mode.

New Settings Command Structure

1. Add a new settings command

packages/cli/src/commands/settings.ts (New File)

import chalk from 'chalk';
import { Logger, LogLevel } from 'mycoder-agent';

import { SharedOptions } from '../options.js';
import { getSettings, updateSettings } from '../settings/settings.js';
import { nameToLogIndex } from '../utils/nameToLogIndex.js';

import type { CommandModule, Argv } from 'yargs';

interface SettingsArgs extends SharedOptions {
  get?: string;
  set?: string;
  value?: string;
  githubMode?: boolean;
  list?: boolean;
}

export const command: CommandModule<SharedOptions, SettingsArgs> = {
  command: 'settings',
  describe: 'Manage MyCoder settings',
  builder: (yargs: Argv<object>): Argv<SettingsArgs> => {
    return yargs
      .option('get', {
        type: 'string',
        description: 'Get the value of a specific setting',
      })
      .option('set', {
        type: 'string',
        description: 'Set a specific setting',
      })
      .option('value', {
        type: 'string',
        description: 'Value to set (used with --set)',
      })
      .option('githubMode', {
        type: 'boolean',
        description: 'Enable or disable GitHub mode',
      })
      .option('list', {
        type: 'boolean',
        description: 'List all settings',
        alias: 'l',
      })
      .example('$0 settings --list', 'List all settings')
      .example('$0 settings --get githubMode', 'Get the value of githubMode setting')
      .example('$0 settings --set githubMode --value true', 'Enable GitHub mode')
      .example('$0 settings --githubMode true', 'Enable GitHub mode (shorthand)');
  },
  handler: async (argv) => {
    const logger = new Logger({
      name: 'Settings',
      logLevel: nameToLogIndex(argv.logLevel),
    });

    const settings = getSettings();

    // Handle --list option
    if (argv.list) {
      logger.info('Current settings:');
      Object.entries(settings).forEach(([key, value]) => {
        logger.info(`  ${key}: ${chalk.green(value)}`);
      });
      return;
    }

    // Handle --get option
    if (argv.get) {
      const key = argv.get as keyof typeof settings;
      if (key in settings) {
        logger.info(`${key}: ${chalk.green(settings[key])}`);
      } else {
        logger.error(`Setting '${key}' not found`);
      }
      return;
    }

    // Handle --set option
    if (argv.set) {
      const key = argv.set as keyof typeof settings;
      if (argv.value === undefined) {
        logger.error('--value is required when using --set');
        return;
      }
      
      // Parse the value based on current type
      let parsedValue: any = argv.value;
      if (typeof settings[key] === 'boolean') {
        parsedValue = argv.value.toLowerCase() === 'true';
      } else if (typeof settings[key] === 'number') {
        parsedValue = Number(argv.value);
      }
      
      const updatedSettings = updateSettings({ [key]: parsedValue });
      logger.info(`Updated ${key}: ${chalk.green(updatedSettings[key])}`);
      return;
    }

    // Handle --githubMode shorthand
    if (argv.githubMode !== undefined) {
      const updatedSettings = updateSettings({ githubMode: argv.githubMode });
      logger.info(`GitHub mode ${updatedSettings.githubMode ? 'enabled' : 'disabled'}`);
      return;
    }

    // If no options provided, show help
    if (!argv.list && !argv.get && !argv.set && argv.githubMode === undefined) {
      logger.info('Use --list to view all settings, --get to view a specific setting, or --set to update a setting');
      logger.info('Example: mycoder settings --githubMode true');
    }
  },
};

2. Update Main CLI to Include Settings Command

packages/cli/src/index.ts

// Add to imports
import { command as settingsCommand } from './commands/settings.js';

// Update commands array
.command([
  defaultCommand,
  testSentryCommand,
  toolsCommand,
  settingsCommand, // Add settings command
] as CommandModule[])

3. Remove GitHub Flag from Default Command

Since we now have a dedicated settings command, we should remove the GitHub flag from the default command to avoid confusion:

packages/cli/src/options.ts

• Remove the GitHub-specific option from shared options

packages/cli/src/commands/$default.ts

• Remove the GitHub mode enabling code from the default command handler

Example Usage

# Enable GitHub mode
mycoder settings --githubMode true

# Disable GitHub mode
mycoder settings --githubMode false

# List all settings
mycoder settings --list

# Get a specific setting
mycoder settings --get githubMode

# Set a setting with a specific value
mycoder settings --set createIssuesForIdeas --value false

This approach follows the patterns used by other CLI tools:

• git config --global user.name "Your Name"
• gcloud config set project my-project
• npm config set init-author-name "Your Name"

It provides a consistent interface for managing settings and allows for easy expansion as more settings are added in the future.

[bhouston]

Config Command Implementation for GitHub Mode

Following the syntax patterns of npm and gcloud more closely, we should implement a config command instead of settings. This will provide a familiar interface for managing all global configuration options, including GitHub mode.

New Config Command Structure

NOTE: This is being handled in the separate GitHub issue #68.

[bhouston]

GitHub Mode Implementation Update

Based on our discussion, I've separated the config command implementation into its own issue: #68

For the GitHub mode feature, we will:

1. Depend on the new config command for enabling/disabling GitHub mode
2. Use mycoder config set githubMode true to enable GitHub mode
3. Focus on implementing the GitHub mode behavior in the system prompt

The GitHub mode will rely on the gh CLI tool directly rather than creating wrapper tools. When enabled, the agent will:

• Start from or create GitHub issues for tasks
• Create branches for issues it's working on
• Make commits and push changes
• Create PRs linked to issues
• Create additional GitHub issues for follow-up tasks or ideas

This approach:

• Keeps the implementation simpler
• Avoids unnecessary abstraction layers
• Follows the principle of using existing tools directly
• Allows the agent to leverage the full power of the gh CLI tool

[github-actions]

🎉 This issue has been resolved in version mycoder-agent-v1.0.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[github-actions]

🎉 This issue has been resolved in version mycoder-v1.0.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀