AI Code Generation Guide

This guide provides a comprehensive overview of Maitento’s AI Code Generation feature, which leverages Claude (Anthropic’s AI) to generate, modify, and refactor code within Git repositories. This is a powerful feature that enables automated, multi-step development tasks executed by an intelligent coding assistant.

Table of Contents

1. What is AI Code Generation?
2. Process Workflow
3. Step Configuration
4. Git Integration
5. Claude Authentication Methods
6. API Reference Summary
7. SDK Usage Examples
8. Best Practices

What is AI Code Generation?

AI Code Generation is an AI-powered system that uses Claude (or Kimi) to generate and modify code within Git repositories. Unlike static code generation tools, this is an interactive AI coding assistant that can:

• Clone repositories and work on dedicated feature branches
• Analyze existing code to understand context and patterns
• Implement multi-step development tasks with intelligent reasoning
• Commit changes incrementally with meaningful commit messages
• Generate comprehensive diffs for code review

Key Capabilities

Supported AI Engines

Process Workflow

The code generation process follows a well-defined workflow from initiation to completion.

Architecture Overview

+---------------------------------------------------------------------------+
|                              API LAYER                                     |
+---------------------------------------------------------------------------+
|  POST /code-generation/processes                                          |
|      |                                                                     |
|      v                                                                     |
|  CodeGenerationProcessService.Start()                                     |
|      |                                                                     |
|      +---> Create CodeGenerationProcess entity (Status: New)              |
|      +---> Send CodeGenerationProcessStartMessage to queue                |
+---------------------------------------------------------------------------+
                              |
                              | RabbitMQ
                              v
+---------------------------------------------------------------------------+
|                         WORKER SERVICE                                     |
+---------------------------------------------------------------------------+
|  CodeGenerationProcessRunnerBackgroundService                             |
|      |                                                                     |
|      v                                                                     |
|  CodeGenerator.Run()                                                      |
|      |                                                                     |
|      +---> Setup: Clone repo, configure engine, mount files              |
|      +---> For each Step: StepRunner.ProcessStep()                       |
|      |       +---> Analysis Phase (structured output)                     |
|      |       +---> Implementation Phase (code generation)                 |
|      |       +---> Validation Phase (compile check)                      |
|      |       +---> Git Commit Cycle                                       |
|      +---> Generate Diff, Mark Success, Cleanup                          |
+---------------------------------------------------------------------------+

Session Setup

When a code generation process starts, the system performs the following setup:

CodeGenerationFileSystem.SetupSession():
    1. Purge engine home directory
    2. Clone skeleton directory template
    3. Set ownership to engine user
    4. Write Claude credentials (API key or license)
    5. Clone Git repository
    6. Setup Git author credentials
    7. Checkout or create work branch

Directory Structure Created:

[config]/claude/home/[user]/
+-- .ssh/
|   +-- id_rsa              # SSH key (if using SSH authentication)
+-- .claude/
|   +-- .credentials.json   # OAuth license (if using Claude Pro/Max)
+-- claude.key              # API key (if using API key auth)
+-- code/                   # Cloned repository
+-- files/                  # Attached documents/screenshots

Process Lifecycle

The process moves through these statuses:

New --> Running --> Success
           |
           v
        Failed
           |
           v
        Killed (via termination message)

Step Lifecycle

Each step within a process follows its own lifecycle:

NotStarted --> Running --> Success
                  |
                  v
               Failed (process also fails)

Step Configuration

Steps are the building blocks of code generation processes. Each step represents a discrete task for the AI to execute.

Commitable vs Analysis Steps

Steps can be configured in two modes:

Commitable Steps (IsCommitableStep: true)

These steps generate code changes that are committed to the Git repository. Each commitable step executes three phases:

Git Commit Cycle:

1. Refresh credentials (if needed)
2. Check local summary (staged/unstaged changes)
3. Stage files: git add .
4. Commit: git commit -m "[step description]"
5. Compare with source branch
6. Push to origin

Analysis Steps (IsCommitableStep: false)

These steps execute prompts without modifying the repository:

• Direct prompt execution
• No Git operations performed
• Output captured for documentation/planning purposes

Use analysis steps for:

• Initial codebase review
• Planning and architecture decisions
• Summarizing changes made
• Documentation generation

Structured Output

When IsStructuredOutput: true, the AI returns a JSON-formatted response:

{
  "output": "Detailed description of work done",
  "thinking": "Step-by-step thought process",
  "wasSuccessful": true,
  "didGenerateCode": true,
  "isAdditionalWorkRequiredToContinue": false
}

This is useful when you need:

• Programmatic access to the AI’s reasoning
• Verification of what was accomplished
• Detection of incomplete work

Example Step Configuration

{
  "steps": [
    {
      "step": "Review the codebase and identify areas that need refactoring",
      "isCommitableStep": false,
      "isStructuredOutput": true
    },
    {
      "step": "Add unit tests for the UserService class",
      "isCommitableStep": true,
      "isStructuredOutput": false
    },
    {
      "step": "Refactor the authentication module to use dependency injection",
      "isCommitableStep": true,
      "isStructuredOutput": true
    },
    {
      "step": "Summarize all changes made",
      "isCommitableStep": false,
      "isStructuredOutput": false
    }
  ]
}

Git Integration

Maitento’s code generation integrates directly with Git repositories, supporting both SSH and HTTPS authentication.

Supported Authentication Methods

SSH Authentication

• SSH private key stored at: [home]/.ssh/id_rsa
• Permissions set to: 600
• Auto-cleanup after push operation

Configuration:

{
  "gitUrl": "git@github.com:myorg/myrepo.git",
  "gitSshKeyBase64": "LS0tLS1CRUdJTiBPUEVOU1NIIFBSSVZBVEUgS0VZLS0tLS0K..."
}

SDK Usage:

// Read SSH private key and encode as Base64
byte[] sshKeyBytes = File.ReadAllBytes("/path/to/id_rsa");
string sshKeyBase64 = Convert.ToBase64String(sshKeyBytes);

var process = await client.CodeGenerationProcess.StartAsync(
    gitUrl: "git@github.com:myorg/myrepo.git",
    gitSshKeyBase64: sshKeyBase64,
    branchSource: "main",
    branchWork: "feature/ai-generated",
    // ... other parameters
);

HTTPS Authentication

• Credentials injected into URL
• Format: https://user:pass@host/repo.git
• Auto-cleanup after push operation

Configuration:

{
  "gitUrl": "https://github.com/myorg/myrepo.git",
  "gitHttpCredentials": "ghp_xxxxxxxxxxxxxxxxxxxx"
}

The credentials can be:

• Username:password combination
• Personal Access Token (PAT)
• App installation token

Git Operations

The system performs these Git operations:

Branch Configuration

The system will:

1. Clone the repository with the source branch
2. Create or checkout the work branch
3. Commit changes to the work branch
4. Push the work branch to origin

Diff Generation

When generateDiffOnCompletion: true, the system generates a comprehensive diff after all steps complete:

git diff [remote]/[source]

The diff is parsed into a structured format:

public class CodeDiff
{
    public CodeDiffFile[] Files { get; set; }
}

public class CodeDiffFile
{
    public string Filename { get; set; }
    public bool IsNew { get; set; }
    public bool IsDeleted { get; set; }
    public bool IsRenamed { get; set; }
    public bool IsBinary { get; set; }
    public CodeDiffChange[] Changes { get; set; }
}

public class CodeDiffChange
{
    public string Header { get; set; }           // e.g., "@@ -1,5 +1,7 @@"
    public CodeDiffChangeLine[] Diff { get; set; }
}

Claude Authentication Methods

Maitento supports multiple ways to authenticate with Claude for code generation.

Method 1: Default (Maitento API Key)

The simplest option - uses Maitento’s system-configured API key:

var process = await client.CodeGenerationProcess.StartAsync(
    // ... other parameters
    claudeAuthentication: null  // Uses Maitento's default key
);

Best for: Testing, getting started, low-volume usage

Method 2: Client API Key

Use your own Anthropic API key for direct billing:

var claudeAuth = new ClaudeAuthentication
{
    Source = ClaudeAuthenticationSource.ClientApiKey,
    ApiKey = "sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxx"
};

var process = await client.CodeGenerationProcess.StartAsync(
    // ... other parameters
    claudeAuthentication: claudeAuth
);

API Request:

{
  "claudeAuthentication": {
    "source": "ClientApiKey",
    "apiKey": "sk-ant-api03-..."
  }
}

Best for: Production workloads, dedicated billing, avoiding shared rate limits

Method 3: Client OAuth License (Claude Pro/Max)

Use your Claude Pro or Max subscription via OAuth:

var claudeAuth = new ClaudeAuthentication
{
    Source = ClaudeAuthenticationSource.ClientLicense,
    OAuthAccessToken = "sk-ant-oat01-xxxxx",
    OAuthRefreshToken = "sk-ant-ort01-xxxxx",
    OAuthExpiresAt = DateTime.UtcNow.AddHours(1),
    OAuthScopes = new[] { "user:inference", "user:profile" },
    OAuthSubscriptionType = "max"  // or "pro"
};

var process = await client.CodeGenerationProcess.StartAsync(
    // ... other parameters
    claudeAuthentication: claudeAuth
);

API Request:

{
  "claudeAuthentication": {
    "source": "ClientLicense",
    "oAuthAccessToken": "sk-ant-oat01-xxxxxxxxxxxx",
    "oAuthRefreshToken": "sk-ant-ort01-xxxxxxxxxxxx",
    "oAuthExpiresAt": "2024-01-16T10:30:00Z",
    "oAuthScopes": ["user:inference", "user:profile"],
    "oAuthSubscriptionType": "max"
  }
}

Best for: Leveraging existing Claude subscriptions, extended model access

Token Formats

Updating Authentication

You can update Claude authentication on a running or pending process:

SDK:

await client.CodeGenerationProcess.UpdateClaudeAuthentication(
    id: processId,
    claudeAuthentication: newAuth
);

API:

PUT /code-generation/processes/by-id/{id}/claude-authentication
Content-Type: application/json

{
  "claudeAuthentication": {
    "source": "ClientApiKey",
    "apiKey": "sk-ant-api03-new-key"
  }
}

API Reference Summary

Base URL

/code-generation/processes

Authentication

All endpoints require authentication:

Required Roles: Tenant.Admin or Tenant.User

Endpoints

Start Process Request

POST /code-generation/processes HTTP/1.1
Authorization: Bearer <token>
Content-Type: application/json

{
  "gitUrl": "git@github.com:myorg/myrepo.git",
  "gitSshKeyBase64": "LS0tLS1CRUdJTi...",
  "branchSource": "main",
  "branchWork": "feature/ai-generated-code",
  "steps": [
    {
      "step": "Add unit tests for the UserService class",
      "isCommitableStep": true,
      "isStructuredOutput": false
    }
  ],
  "codeGuidelines": "Use C# 12 features. Follow Microsoft naming conventions.",
  "fileIds": ["guid1", "guid2"],
  "generateDiffOnCompletion": true,
  "engine": "Claude",
  "claudeAuthentication": {
    "source": "ClientApiKey",
    "apiKey": "sk-ant-api03-..."
  }
}

Request Parameters

Response Status Codes

SDK Usage Examples

Basic Usage

using Maitento.Sdk;
using Maitento.Entities.CodeGeneration;

// Initialize the client
var client = new MaitentoClient("https://your-maitento-instance.com", "your-api-key");

// Access the code generation service
ICodeGenerationProcessService codeGenService = client.CodeGenerationProcess;

Starting a Process

var steps = new[]
{
    new CodeGenerationStepCreateRequest
    {
        Step = "Add XML documentation comments to all public methods",
        IsCommitableStep = true,
        IsStructuredOutput = false
    },
    new CodeGenerationStepCreateRequest
    {
        Step = "Write unit tests for the UserService class",
        IsCommitableStep = true,
        IsStructuredOutput = false
    }
};

var process = await client.CodeGenerationProcess.StartAsync(
    gitUrl: "https://github.com/myorg/myrepo.git",
    gitSshKeyBase64: null,
    branchSource: "main",
    branchWork: "feature/add-docs-and-tests",
    steps: steps,
    codeGuidelines: "Follow Microsoft C# coding conventions.",
    gitHttpCredentials: "ghp_xxxxxxxxxxxxxxxxxxxx",
    fileIds: Array.Empty<Guid>(),
    generateDiffOnCompletion: true,
    claudeAuthentication: null,
    engine: CodeGenerationEngineType.Claude
);

Console.WriteLine($"Process started with ID: {process.Id}");

SSH Authentication Example

// Read SSH private key and encode as Base64
byte[] sshKeyBytes = File.ReadAllBytes("/path/to/id_rsa");
string sshKeyBase64 = Convert.ToBase64String(sshKeyBytes);

var process = await client.CodeGenerationProcess.StartAsync(
    gitUrl: "git@github.com:myorg/myrepo.git",
    gitSshKeyBase64: sshKeyBase64,
    branchSource: "develop",
    branchWork: "feature/refactor-auth",
    steps: new[]
    {
        new CodeGenerationStepCreateRequest
        {
            Step = "Refactor the authentication module to use dependency injection",
            IsCommitableStep = true,
            IsStructuredOutput = false
        }
    },
    codeGuidelines: null,
    gitHttpCredentials: null,
    fileIds: Array.Empty<Guid>(),
    generateDiffOnCompletion: true
);

OAuth License Example

var claudeAuth = new ClaudeAuthentication(
    source: ClaudeAuthenticationSource.ClientLicense,
    oAuthAccessToken: "sk-ant-oat01-xxxxx",
    oAuthRefreshToken: "sk-ant-ort01-xxxxx",
    oAuthExpiresAt: DateTime.UtcNow.AddHours(1),
    oAuthScopes: new[] { "user:inference", "user:profile" },
    oAuthSubscriptionType: "max"
);

var process = await client.CodeGenerationProcess.StartAsync(
    gitUrl: "https://github.com/myorg/myrepo.git",
    gitSshKeyBase64: null,
    branchSource: "main",
    branchWork: "feature/ai-generated-code",
    steps: steps,
    codeGuidelines: null,
    gitHttpCredentials: "ghp_xxxxxxxxxxxxxxxxxxxx",
    fileIds: Array.Empty<Guid>(),
    generateDiffOnCompletion: true,
    claudeAuthentication: claudeAuth,
    engine: CodeGenerationEngineType.Claude
);

Monitoring Progress

// Poll for completion
while (true)
{
    await Task.Delay(TimeSpan.FromSeconds(10));

    var current = await client.CodeGenerationProcess.GetByIdAsync(process.Id);

    if (current == null)
    {
        Console.WriteLine("Process not found!");
        break;
    }

    Console.WriteLine($"Status: {current.Status}");

    // Show step progress
    foreach (var step in current.Steps)
    {
        var statusIcon = step.Status switch
        {
            CodeGenerationStepStatus.Success => "[OK]",
            CodeGenerationStepStatus.Running => "[..]",
            CodeGenerationStepStatus.Failed => "[X]",
            _ => "[ ]"
        };
        Console.WriteLine($"  {statusIcon} {step.Step.Substring(0, Math.Min(50, step.Step.Length))}...");
    }

    if (current.Status == CodeGenerationProcessStatus.Success)
    {
        Console.WriteLine("\nProcess completed successfully!");

        if (current.Diff != null)
        {
            Console.WriteLine($"\nFiles changed: {current.Diff.Files.Length}");
            foreach (var file in current.Diff.Files)
            {
                var changeType = file.IsNew ? "(new)" :
                                 file.IsDeleted ? "(deleted)" :
                                 file.IsRenamed ? "(renamed)" : "(modified)";
                Console.WriteLine($"  {file.Filename} {changeType}");
            }
        }
        break;
    }

    if (current.Status == CodeGenerationProcessStatus.Failed)
    {
        Console.WriteLine($"\nProcess failed: {current.FailureDetails}");
        break;
    }

    if (current.Status == CodeGenerationProcessStatus.Killed)
    {
        Console.WriteLine("\nProcess was terminated.");
        break;
    }
}

Listing Processes

// Get all processes
var processes = await client.CodeGenerationProcess.GetAllAsync();

foreach (var process in processes)
{
    Console.WriteLine($"ID: {process.Id}");
    Console.WriteLine($"  Git URL: {process.GitUrl}");
    Console.WriteLine($"  Branch: {process.BranchWork}");
    Console.WriteLine($"  Status: {process.Status}");
    Console.WriteLine($"  Created: {process.DateCreated}");
}

// Get only active processes
var aliveProcesses = await client.CodeGenerationProcess.GetAlive();

Console.WriteLine($"Currently active processes: {aliveProcesses.Length}");
foreach (var process in aliveProcesses)
{
    var runningStep = process.Steps.FirstOrDefault(s => s.Status == CodeGenerationStepStatus.Running);
    Console.WriteLine($"  {process.Id}: {runningStep?.Step ?? "Starting..."}");
}

Updating Credentials

// Update HTTP credentials
await client.CodeGenerationProcess.UpdateCredentialsAsync(
    id: processId,
    gitSshKey: null,
    gitHttpCredentials: "ghp_new_personal_access_token"
);

// Update SSH key
byte[] newSshKey = File.ReadAllBytes("/path/to/new_id_rsa");
await client.CodeGenerationProcess.UpdateCredentialsAsync(
    id: processId,
    gitSshKey: newSshKey,
    gitHttpCredentials: null
);

Best Practices

1. Use Meaningful Step Instructions

Provide clear, specific instructions for each step to get better results:

// Good
new CodeGenerationStepCreateRequest
{
    Step = "Add XML documentation comments to all public methods in the UserService class, including parameter descriptions and return value documentation",
    IsCommitableStep = true
}

// Less effective
new CodeGenerationStepCreateRequest
{
    Step = "Add documentation",
    IsCommitableStep = true
}

2. Enable Structured Output for Complex Steps

When you need detailed feedback about what was accomplished:

new CodeGenerationStepCreateRequest
{
    Step = "Refactor the authentication module to use dependency injection",
    IsCommitableStep = true,
    IsStructuredOutput = true  // Get detailed reasoning and success indicators
}

3. Use Commitable Steps Strategically

Each commitable step creates a Git commit, making it easier to:

• Review changes incrementally
• Revert specific changes
• Understand the evolution of modifications

// Breaking up work into logical commits
var steps = new[]
{
    new CodeGenerationStepCreateRequest
    {
        Step = "Add logging infrastructure",
        IsCommitableStep = true  // Commit 1
    },
    new CodeGenerationStepCreateRequest
    {
        Step = "Add logging to all controller actions",
        IsCommitableStep = true  // Commit 2
    },
    new CodeGenerationStepCreateRequest
    {
        Step = "Add unit tests for logging",
        IsCommitableStep = true  // Commit 3
    }
};

4. Provide Code Guidelines

Include coding standards, naming conventions, and architectural patterns:

var process = await client.CodeGenerationProcess.StartAsync(
    // ... other parameters
    codeGuidelines: @"
        - Use C# 12 features
        - Follow Microsoft naming conventions
        - All public methods must have XML documentation
        - Use ILogger for all logging
        - Follow SOLID principles
        - Prefer async/await for I/O operations
    "
);

5. Monitor Long-Running Processes

Use the dateRunnerPing field to detect stale processes:

var process = await client.CodeGenerationProcess.GetByIdAsync(processId);

if (process.Status == CodeGenerationProcessStatus.Running)
{
    var lastPing = process.DateRunnerPing;
    var staleThreshold = DateTime.UtcNow.AddMinutes(-5);

    if (lastPing < staleThreshold)
    {
        Console.WriteLine("Warning: Process may be stale");
    }
}

6. Use Your Own Claude Credentials for Production

Avoid rate limits on shared infrastructure:

var claudeAuth = new ClaudeAuthentication
{
    Source = ClaudeAuthenticationSource.ClientApiKey,
    ApiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY")
};

var process = await client.CodeGenerationProcess.StartAsync(
    // ... other parameters
    claudeAuthentication: claudeAuth
);

7. Include Context Files

Upload screenshots, specification documents, or reference files:

// First upload files using the Files API
var fileIds = new[] { uploadedFileId1, uploadedFileId2 };

var process = await client.CodeGenerationProcess.StartAsync(
    // ... other parameters
    fileIds: fileIds  // Include as context for the AI
);

8. Start with Analysis Steps

For complex refactoring, start with a non-commitable analysis step:

var steps = new[]
{
    new CodeGenerationStepCreateRequest
    {
        Step = "Analyze the codebase and identify all areas that need refactoring. List specific files and issues.",
        IsCommitableStep = false,  // Analysis only
        IsStructuredOutput = true
    },
    new CodeGenerationStepCreateRequest
    {
        Step = "Implement the refactoring based on the analysis",
        IsCommitableStep = true
    }
};

9. Handle Errors Gracefully

Check for failures and examine details:

var process = await client.CodeGenerationProcess.GetByIdAsync(processId);

if (process.Status == CodeGenerationProcessStatus.Failed)
{
    Console.WriteLine($"Process failed: {process.FailureDetails}");

    // Check which step failed
    var failedStep = process.Steps.FirstOrDefault(s => s.Status == CodeGenerationStepStatus.Failed);
    if (failedStep != null)
    {
        Console.WriteLine($"Failed step: {failedStep.Step}");
        Console.WriteLine($"Step failure details: {failedStep.FailureDetails}");
    }
}

10. Test with Dummy Mode

For testing without consuming AI credits:

var claudeAuth = new ClaudeAuthentication
{
    Source = ClaudeAuthenticationSource.ClientApiKey,
    ApiKey = "000-dummy"  // Special key for testing
};

This generates placeholder outputs and skips actual AI processing.

Error Handling

Common Engine Errors

Retry Logic

• Engine calls: 3 retries with exponential backoff (2.5s, 5s, 7.5s)
• Credential refresh: Automatic on auth failure
• Process requeue: If duplicate message received

Process Errors

Cogniscript Integration

Available syscalls for automation:

See Also

• Code Generation API Reference - Complete REST API documentation
• SDK Reference - Full SDK documentation
• Files API - For uploading context files