Where to Find the gRPC Proto Definition for OpenClaude: Complete File Guide

The gRPC proto definition for OpenClaude is located at src/proto/openclaude.proto and defines the AgentService interface with a bidirectional streaming Chat RPC, specifying message types like ClientMessage and ServerMessage for real-time agent communication.

The OpenClaude project uses Protocol Buffers to define its service contracts, enabling strongly typed communication between AI agents and clients. Understanding the exact location and structure of this gRPC proto definition for OpenClaude is essential for developers building custom clients or extending the server functionality.

Locating the gRPC Proto Definition File

The complete service contract resides in a single Protocol Buffers file within the repository's source tree:

• File Path: src/proto/openclaude.proto
• Repository: Gitlawb/openclaude

This file contains the full AgentService definition that both the server implementation and generated client libraries consume. All message types, service methods, and streaming semantics are centralized here to ensure consistency across language boundaries.

Core Service and Message Structure

The proto file defines a bidirectional streaming architecture that supports real-time conversation flows between clients and the OpenClaude agent.

AgentService Definition

The root service exposes a single streaming RPC method:

service AgentService {
  // Bidirectional streaming RPC.
  //   • Client → Server: stream of `ClientMessage`
  //   • Server → Client: stream of `ServerMessage`
  rpc Chat(stream ClientMessage) returns (stream ServerMessage);
}

Source: lines 6–10 of src/proto/openclaude.proto

This bidirectional streaming design allows the server to push intermediate responses, tool call requests, and cancellation signals while the client maintains an open connection.

Client-to-Server Messages

The ClientMessage type uses a oneof field to represent distinct inbound operations:

• ChatRequest (lines 28–34): Initial request containing model selection parameters and session identifiers
• UserInput (lines 36–39): User replies to server prompts during conversation
• CancelSignal (lines 41–44): Stream termination requests to abort ongoing operations

Server-to-Client Messages

The ServerMessage type handles outbound communication through six distinct variants:

• TextChunk: Streaming text fragments of the agent's response
• ToolCallStart / ToolCallResult (lines 65–78): Tool invocation lifecycle events indicating when external tools begin execution and return results
• ActionRequired (lines 80–89): Server-side prompts requiring user confirmation or additional information
• FinalResponse (lines 91–96): Completion metadata signaling the end of a conversation turn
• ErrorResponse (lines 98–101): Structured error payloads for failure scenarios

How the Proto File Is Loaded in OpenClaude

The OpenClaude runtime dynamically loads the proto definition using @grpc/proto-loader rather than pre-compiled stubs.

Server Implementation

In src/grpc/server.ts, the server resolves the proto path at runtime:

const PROTO_PATH = path.resolve(import.meta.dirname, '../proto/openclaude.proto');

Source: line 13 of src/grpc/server.ts

The loader reads this file to instantiate the AgentService definition and bind the Chat method implementation.

CLI Tooling

For client stub generation and testing, scripts/grpc-cli.ts references the same definition:

const PROTO_PATH = path.resolve(import.meta.dirname, '../src/proto/openclaude.proto');

Source: line 6 of scripts/grpc-cli.ts

Both paths ensure the runtime and development tools remain synchronized with the canonical gRPC proto definition for OpenClaude.

Implementing the gRPC Interface

Below are practical implementations demonstrating how the proto definition drives both server and client code.

Starting the gRPC Server

This TypeScript example loads the proto and implements the bidirectional streaming handler:

import * as grpc from '@grpc/grpc-js';
import * as protoLoader from '@grpc/proto-loader';
import path from 'path';

const PROTO_PATH = path.resolve(import.meta.dirname, '../proto/openclaude.proto');
const packageDef = protoLoader.loadSync(PROTO_PATH, { 
  keepCase: true, 
  longs: String, 
  enums: String, 
  defaults: true, 
  oneofs: true 
});
const openClaude = grpc.loadPackageDefinition(packageDef).openclaude.v1 as any;

// Implement the AgentService.Chat handler
function chatHandler(call: grpc.ServerDuplexStream<any, any>) {
  call.on('data', (msg) => {
    const response = { 
      text_chunk: { 
        text: `Echo: ${msg.request?.message || ''}` 
      } 
    };
    call.write(response);
  });
  call.on('end', () => call.end());
}

const server = new grpc.Server();
server.addService(openClaude.AgentService.service, { Chat: chatHandler });
server.bindAsync('0.0.0.0:50051', grpc.ServerCredentials.createInsecure(), () => server.start());

Simple gRPC Client

This client connects to the AgentService and exchanges messages:

import * as grpc from '@grpc/grpc-js';
import * as protoLoader from '@grpc/proto-loader';
import path from 'path';

const PROTO_PATH = path.resolve(import.meta.dirname, '../src/proto/openclaude.proto');
const pkg = protoLoader.loadSync(PROTO_PATH, { 
  keepCase: true, 
  longs: String, 
  enums: String, 
  defaults: true, 
  oneofs: true 
});
const openClaude = grpc.loadPackageDefinition(pkg).openclaude.v1 as any;

const client = new openClaude.AgentService('localhost:50051', grpc.credentials.createInsecure());
const stream = client.Chat();

stream.on('data', (msg) => {
  if (msg.text_chunk) console.log('Received:', msg.text_chunk.text);
});

stream.write({ request: { message: 'Hello OpenClaude', session_id: 'sess-123' } });

These implementations require no manual protobuf compilation because they load the proto definition dynamically at runtime.

Summary

• The gRPC proto definition for OpenClaude is located at src/proto/openclaude.proto in the Gitlawb/openclaude repository
• The AgentService exposes a single bidirectional streaming RPC called Chat that handles real-time message exchange
• ClientMessage supports ChatRequest, UserInput, and CancelSignal operations from client to server
• ServerMessage delivers TextChunk, ToolCallStart, ToolCallResult, ActionRequired, FinalResponse, and ErrorResponse payloads
• Both server (src/grpc/server.ts) and CLI tools (scripts/grpc-cli.ts) load the proto definition using @grpc/proto-loader with runtime path resolution

Frequently Asked Questions

What is the exact file path for the OpenClaude gRPC proto definition?

The proto definition is located at src/proto/openclaude.proto in the repository root. This path is referenced by both the server implementation and client generation scripts to ensure consistent service contracts across the codebase.

Which RPC methods are defined in the OpenClaude proto file?

The file defines a single service called AgentService containing one bidirectional streaming method: Chat. This method accepts a stream of ClientMessage objects and returns a stream of ServerMessage objects, enabling real-time duplex communication between clients and the AI agent.

How does OpenClaude handle different message types in the Chat stream?

The proto uses Protocol Buffers oneof fields to distinguish message variants. ClientMessage can contain either a ChatRequest, UserInput, or CancelSignal, while ServerMessage variants include text chunks, tool calls, user prompts, and error responses. This design allows the same streaming RPC to multiplex multiple conversation events through a single connection.

Can I generate client libraries from the OpenClaude proto file?

Yes. The proto file at src/proto/openclaude.proto can be used with standard Protocol Buffers compilers (protoc) or the Node.js @grpc/proto-loader package to generate client stubs in languages including TypeScript, Python, Go, and Java. The scripts/grpc-cli.ts file in the repository demonstrates the dynamic loading approach used for testing and CLI tooling.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}