gitcaddy-ai/README.md

GitCaddy AI Service

AI-powered code intelligence service for GitCaddy. Provides code review, documentation generation, issue triage, and agentic workflows.

Features

• Code Review: AI-powered pull request and commit reviews with security analysis
• Code Intelligence: Explain code, suggest fixes, summarize changes
• Issue Management: Auto-triage issues, suggest labels, generate responses
• Documentation: Generate docs for code, commit messages
• Agentic Workflows: Multi-step AI workflows for complex tasks
• Chat Interface: Interactive AI assistant for developers

Architecture

The AI service runs as a sidecar alongside the GitCaddy server. It exposes two gRPC services on the same port (HTTP/2 + HTTP/1.1):

• GitCaddyAIService - AI operations (review, triage, docs, chat) called by the server's AI client
• PluginService - Plugin lifecycle protocol (initialize, health, events) managed by the server's external plugin manager

┌──────────────────────────────────────────────────────────────────────┐
│  GitCaddy Server (Go)                                                │
│  ├── AI Client (gRPC) ──────────────── GitCaddyAIService             │
│  │     ReviewPullRequest, TriageIssue,     │                         │
│  │     ExplainCode, GenerateDocumentation  │                         │
│  │                                         │                         │
│  └── External Plugin Manager (gRPC) ─── PluginService                │
│        Initialize, HealthCheck (30s),      │                         │
│        OnEvent, Shutdown                   ▼                         │
│                                   ┌──────────────────────────┐      │
│                                   │  GitCaddy AI (.NET 9)    │      │
│                                   │  Port 5000 (h2c + HTTP)  │      │
│                                   │  ├── AI Providers         │      │
│                                   │  │   (Claude/OpenAI/      │      │
│                                   │  │    Gemini)             │      │
│                                   │  └── License Validation   │      │
│                                   └──────────────────────────┘      │
└──────────────────────────────────────────────────────────────────────┘

Quick Start

Prerequisites

• .NET 9.0 SDK
• Docker (optional)
• API key for Claude, OpenAI, or Gemini

Development

# Clone the repository
git clone https://git.marketally.com/gitcaddy/gitcaddy-ai.git
cd gitcaddy-ai

# Set environment variables
export Providers__Claude__ApiKey="your-api-key"

# Run the service
cd src/GitCaddy.AI.Service
dotnet run

Docker

# Set environment variables
export CLAUDE_API_KEY="your-api-key"
export GITCADDY_AI_LICENSE="your-license-key"

# Run with Docker Compose
docker-compose up -d

Configuration

Configuration is done via appsettings.json or environment variables:

{
  "AIService": {
    "DefaultProvider": "Claude",
    "DefaultModel": "claude-sonnet-4-20250514",
    "MaxTokens": 4096,
    "Temperature": 0.7
  },
  "Providers": {
    "Claude": {
      "ApiKey": "sk-ant-...",
      "Enabled": true
    },
    "OpenAI": {
      "ApiKey": "sk-...",
      "Enabled": true
    }
  },
  "License": {
    "LicenseKey": "your-license-key"
  }
}

Environment variable format: AIService__DefaultProvider=Claude

API Reference

The service exposes two gRPC services on port 5000 (cleartext HTTP/2):

AI Operations (protos/gitcaddy_ai.proto)

Code Review

rpc ReviewPullRequest(ReviewPullRequestRequest) returns (ReviewPullRequestResponse);
rpc ReviewCommit(ReviewCommitRequest) returns (ReviewCommitResponse);

Code Intelligence

rpc SummarizeChanges(SummarizeChangesRequest) returns (SummarizeChangesResponse);
rpc ExplainCode(ExplainCodeRequest) returns (ExplainCodeResponse);
rpc SuggestFix(SuggestFixRequest) returns (SuggestFixResponse);

Issue Management

rpc TriageIssue(TriageIssueRequest) returns (TriageIssueResponse);
rpc SuggestLabels(SuggestLabelsRequest) returns (SuggestLabelsResponse);
rpc GenerateIssueResponse(GenerateIssueResponseRequest) returns (GenerateIssueResponseResponse);

Documentation

rpc GenerateDocumentation(GenerateDocumentationRequest) returns (GenerateDocumentationResponse);
rpc GenerateCommitMessage(GenerateCommitMessageRequest) returns (GenerateCommitMessageResponse);

Workflows & Chat

rpc StartWorkflow(StartWorkflowRequest) returns (stream WorkflowEvent);
rpc ExecuteTask(ExecuteTaskRequest) returns (ExecuteTaskResponse);
rpc Chat(stream ChatRequest) returns (stream ChatResponse);

Plugin Protocol (protos/plugin.proto)

The plugin protocol allows the GitCaddy server to manage this service as an external plugin:

rpc Initialize(InitializeRequest) returns (InitializeResponse);
rpc Shutdown(ShutdownRequest) returns (ShutdownResponse);
rpc HealthCheck(PluginHealthCheckRequest) returns (PluginHealthCheckResponse);
rpc GetManifest(GetManifestRequest) returns (PluginManifest);
rpc OnEvent(PluginEvent) returns (EventResponse);
rpc HandleHTTP(HTTPRequest) returns (HTTPResponse);

The server calls Initialize on startup, HealthCheck every 30 seconds, OnEvent for subscribed events (e.g., license:updated), and Shutdown on server stop. The service declares its capabilities (routes, permissions, license tier) via the PluginManifest returned during initialization.

Client Libraries

.NET Client

using GitCaddy.AI.Client;

var client = new GitCaddyAIClient("http://localhost:5000");

var response = await client.ReviewPullRequestAsync(new ReviewPullRequestRequest
{
    RepoId = 1,
    PullRequestId = 42,
    PrTitle = "Add feature X",
    Files = { new FileDiff { Path = "src/foo.cs", Patch = "..." } }
});

Console.WriteLine(response.Summary);

Go Client

import ai "git.marketally.com/gitcaddy/gitcaddy-ai/go/gitcaddy-ai-client"

client, err := ai.NewClient("localhost:5000")
if err != nil {
    log.Fatal(err)
}
defer client.Close()

resp, err := client.ReviewPullRequest(ctx, &pb.ReviewPullRequestRequest{
    RepoId:        1,
    PullRequestId: 42,
    PrTitle:       "Add feature X",
    Files:         []*pb.FileDiff{{Path: "src/foo.go", Patch: "..."}},
})

Licensing

GitCaddy AI is licensed under the Business Source License 1.1 (BSL-1.1).

License Tiers

Tier	Features
Standard	Code review, code intelligence, documentation, chat
Professional	+ Issue management, agentic workflows
Enterprise	+ Custom models, audit logging, SSO integration

Trial Mode

Without a license key, the service runs in trial mode with Standard tier features for 30 days.

Development

Building

dotnet build

Testing

dotnet test

Generating Proto Files

For Go client:

cd go/gitcaddy-ai-client
go generate

Integration with GitCaddy Server

Add both sections to the server's app.ini:

1. AI client configuration (how the server calls AI operations):

[ai]
ENABLED = true
SERVICE_URL = localhost:5000
DEFAULT_PROVIDER = claude
DEFAULT_MODEL = claude-sonnet-4-20250514
CLAUDE_API_KEY = sk-ant-...

See the server README for the full [ai] reference.

2. Plugin registration (how the server manages the sidecar's lifecycle):

[plugins]
ENABLED = true
HEALTH_CHECK_INTERVAL = 30s

[plugins.gitcaddy-ai]
ENABLED = true
ADDRESS = localhost:5000
HEALTH_TIMEOUT = 5s
SUBSCRIBED_EVENTS = license:updated

With both sections configured, the server will:

• Call AI operations (review, triage, etc.) via [ai] SERVICE_URL
• Manage the sidecar's lifecycle via the plugin protocol on [plugins.gitcaddy-ai] ADDRESS
• Health-check the sidecar every 30 seconds and log status changes
• Dispatch subscribed events (e.g., license updates) to the sidecar in real-time

Transport: All communication uses cleartext HTTP/2 (h2c). The sidecar's Kestrel server is configured for Http1AndHttp2 on port 5000, supporting both gRPC (HTTP/2) and REST (HTTP/1.1) on the same port.

Support

• Documentation: https://docs.gitcaddy.com/ai
• Issues: https://git.marketally.com/gitcaddy/gitcaddy-ai/issues
• Email: support@marketally.com

License

Copyright 2026 MarketAlly. All rights reserved.

Licensed under the Business Source License 1.1 (BSL-1.1).