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

> Locate the OpenClaude gRPC proto definition at src/proto/openclaude.proto. Discover the AgentService interface and Chat RPC for real-time agent communication.

- Repository: [Gitlawb/openclaude](https://github.com/Gitlawb/openclaude)
- Tags: api-reference
- Published: 2026-09-05

---

**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:

```proto
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`](https://github.com/Gitlawb/openclaude/blob/main/src/grpc/server.ts), the server resolves the proto path at runtime:

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

```

*Source: line 13 of [`src/grpc/server.ts`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/scripts/grpc-cli.ts) references the same definition:

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

```

*Source: line 6 of [`scripts/grpc-cli.ts`](https://github.com/Gitlawb/openclaude/blob/main/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:

```typescript
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:

```typescript
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`](https://github.com/Gitlawb/openclaude/blob/main/src/grpc/server.ts)) and CLI tools ([`scripts/grpc-cli.ts`](https://github.com/Gitlawb/openclaude/blob/main/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`](https://github.com/Gitlawb/openclaude/blob/main/scripts/grpc-cli.ts) file in the repository demonstrates the dynamic loading approach used for testing and CLI tooling.