Cap'n Proto — 18 Operations for AI Agents
Cap'n Proto schemas define the wire contracts of latency-obsessed systems. act101 maps structs, interfaces, and fields as structure, so agents evolve serialization schemas with full sight of what's defined where.
This page is the canonical reference an AI coding agent uses to refactor, query, and analyze Cap'n Proto code through the act MCP server. 18 operations available: 0 refactor, 18 query, 0 analysis. Each operation is callable from Claude Code, Cursor, Codex, OpenCode, or any MCP-compatible agent host. Click any operation for a stable anchor link suitable for citation.
Worked Cap'n Proto examples
act101 reads a Cap'n Proto schema's struct, interface, and enum declarations as their own kinds, named for the declared type. symbols covers the same three top-level declarations plus every member nested inside them: an interface's methods and their parameters, a struct's fields, and an enum's members — the method's return values come back as parameter too, since a capnp return list is shaped identically to a parameter list. The unit of structure skeleton exposes is the top-level type; the unit symbols exposes is the individual member, down to one entry per method parameter. Each example below is the verbatim output of the command shown, run against the file shown. Query outputs are pretty-printed with the timing block omitted.
Read the interface, struct, and enum as a skeleton
scheduler.capnp defines a job-queue RPC: a Scheduler interface with enqueue/cancel methods, the Job struct they operate on, and a JobStatus enum for tracking job state.
$ act query skeleton scheduler.capnpBefore
@0x9c6a71a3f2e4b8d1;
interface Scheduler {
enqueue @0 (job :Job) -> (id :UInt64);
cancel @1 (id :UInt64) -> (cancelled :Bool);
}
struct Job {
id @0 :UInt64;
priority @1 :UInt8;
payload @2 :Data;
retries @3 :UInt8 = 3;
}
enum JobStatus {
pending @0;
running @1;
done @2;
failed @3;
}Output
{
"type": "Skeleton",
"declarations": [
{
"kind": "interface",
"name": "Scheduler",
"range": {
"start": {
"file": "scheduler.capnp",
"line": 3,
"column": 1,
"byte_offset": 22
},
"end": {
"file": "scheduler.capnp",
"line": 6,
"column": 2,
"byte_offset": 133
}
},
"name_range": {
"start": {
"file": "scheduler.capnp",
"line": 3,
"column": 11,
"byte_offset": 32
},
"end": {
"file": "scheduler.capnp",
"line": 3,
"column": 20,
"byte_offset": 41
}
}
},
{
"kind": "struct",
"name": "Job",
"range": {
"start": {
"file": "scheduler.capnp",
"line": 8,
"column": 1,
"byte_offset": 135
},
"end": {
"file": "scheduler.capnp",
"line": 13,
"column": 2,
"byte_offset": 233
}
},
"name_range": {
"start": {
"file": "scheduler.capnp",
"line": 8,
"column": 8,
"byte_offset": 142
},
"end": {
"file": "scheduler.capnp",
"line": 8,
"column": 11,
"byte_offset": 145
}
}
},
{
"kind": "enum",
"name": "JobStatus",
"range": {
"start": {
"file": "scheduler.capnp",
"line": 15,
"column": 1,
"byte_offset": 235
},
"end": {
"file": "scheduler.capnp",
"line": 20,
"column": 2,
"byte_offset": 305
}
},
"name_range": {
"start": {
"file": "scheduler.capnp",
"line": 15,
"column": 6,
"byte_offset": 240
},
"end": {
"file": "scheduler.capnp",
"line": 15,
"column": 15,
"byte_offset": 249
}
}
}
]
}The skeleton reports exactly three declarations: Scheduler as interface, Job as struct, and JobStatus as enum — the methods, fields, and enum members inside each are not read.
List the methods, fields, and enum members as symbols
enqueue takes a job parameter and returns an id; Job carries a retries field defaulted to 3.
$ act query symbols scheduler.capnpBefore
@0x9c6a71a3f2e4b8d1;
interface Scheduler {
enqueue @0 (job :Job) -> (id :UInt64);
cancel @1 (id :UInt64) -> (cancelled :Bool);
}
struct Job {
id @0 :UInt64;
priority @1 :UInt8;
payload @2 :Data;
retries @3 :UInt8 = 3;
}
enum JobStatus {
pending @0;
running @1;
done @2;
failed @3;
}Output
{
"type": "Symbols",
"symbols": [
{
"name": "Scheduler",
"kind": "interface",
"range": {
"start": {
"file": "scheduler.capnp",
"line": 3,
"column": 11,
"byte_offset": 32
},
"end": {
"file": "scheduler.capnp",
"line": 3,
"column": 20,
"byte_offset": 41
}
},
"visibility": "unknown"
},
{
"name": "enqueue",
"kind": "method",
"range": {
"start": {
"file": "scheduler.capnp",
"line": 4,
"column": 3,
"byte_offset": 46
},
"end": {
"file": "scheduler.capnp",
"line": 4,
"column": 10,
"byte_offset": 53
}
},
"visibility": "unknown"
},
{
"name": "job",
"kind": "parameter",
"range": {
"start": {
"file": "scheduler.capnp",
"line": 4,
"column": 15,
"byte_offset": 58
},
"end": {
"file": "scheduler.capnp",
"line": 4,
"column": 18,
"byte_offset": 61
}
},
"visibility": "unknown"
},
{
"name": "id",
"kind": "parameter",
"range": {
"start": {
"file": "scheduler.capnp",
"line": 4,
"column": 29,
"byte_offset": 72
},
"end": {
"file": "scheduler.capnp",
"line": 4,
"column": 31,
"byte_offset": 74
}
},
"visibility": "unknown"
},
{
"name": "cancel",
"kind": "method",
"range": {
"start": {
"file": "scheduler.capnp",
"line": 5,
"column": 3,
"byte_offset": 87
},
"end": {
"file": "scheduler.capnp",
"line": 5,
"column": 9,
"byte_offset": 93
}
},
"visibility": "unknown"
},
{
"name": "id",
"kind": "parameter",
"range": {
"start": {
"file": "scheduler.capnp",
"line": 5,
"column": 14,
"byte_offset": 98
},
"end": {
"file": "scheduler.capnp",
"line": 5,
"column": 16,
"byte_offset": 100
}
},
"visibility": "unknown"
},
{
"name": "cancelled",
"kind": "parameter",
"range": {
"start": {
"file": "scheduler.capnp",
"line": 5,
"column": 30,
"byte_offset": 114
},
"end": {
"file": "scheduler.capnp",
"line": 5,
"column": 39,
"byte_offset": 123
}
},
"visibility": "unknown"
},
{
"name": "Job",
"kind": "struct",
"range": {
"start": {
"file": "scheduler.capnp",
"line": 8,
"column": 8,
"byte_offset": 142
},
"end": {
"file": "scheduler.capnp",
"line": 8,
"column": 11,
"byte_offset": 145
}
},
"visibility": "unknown"
},
{
"name": "id",
"kind": "field",
"range": {
"start": {
"file": "scheduler.capnp",
"line": 9,
"column": 3,
"byte_offset": 150
},
"end": {
"file": "scheduler.capnp",
"line": 9,
"column": 5,
"byte_offset": 152
}
},
"visibility": "unknown"
},
{
"name": "priority",
"kind": "field",
"range": {
"start": {
"file": "scheduler.capnp",
"line": 10,
"column": 3,
"byte_offset": 167
},
"end": {
"file": "scheduler.capnp",
"line": 10,
"column": 11,
"byte_offset": 175
}
},
"visibility": "unknown"
},
{
"name": "payload",
"kind": "field",
"range": {
"start": {
"file": "scheduler.capnp",
"line": 11,
"column": 3,
"byte_offset": 189
},
"end": {
"file": "scheduler.capnp",
"line": 11,
"column": 10,
"byte_offset": 196
}
},
"visibility": "unknown"
},
{
"name": "retries",
"kind": "field",
"range": {
"start": {
"file": "scheduler.capnp",
"line": 12,
"column": 3,
"byte_offset": 209
},
"end": {
"file": "scheduler.capnp",
"line": 12,
"column": 10,
"byte_offset": 216
}
},
"visibility": "unknown"
},
{
"name": "JobStatus",
"kind": "enum",
"range": {
"start": {
"file": "scheduler.capnp",
"line": 15,
"column": 6,
"byte_offset": 240
},
"end": {
"file": "scheduler.capnp",
"line": 15,
"column": 15,
"byte_offset": 249
}
},
"visibility": "unknown"
},
{
"name": "pending",
"kind": "constant",
"range": {
"start": {
"file": "scheduler.capnp",
"line": 16,
"column": 3,
"byte_offset": 254
},
"end": {
"file": "scheduler.capnp",
"line": 16,
"column": 10,
"byte_offset": 261
}
},
"visibility": "unknown"
},
{
"name": "running",
"kind": "constant",
"range": {
"start": {
"file": "scheduler.capnp",
"line": 17,
"column": 3,
"byte_offset": 268
},
"end": {
"file": "scheduler.capnp",
"line": 17,
"column": 10,
"byte_offset": 275
}
},
"visibility": "unknown"
},
{
"name": "done",
"kind": "constant",
"range": {
"start": {
"file": "scheduler.capnp",
"line": 18,
"column": 3,
"byte_offset": 282
},
"end": {
"file": "scheduler.capnp",
"line": 18,
"column": 7,
"byte_offset": 286
}
},
"visibility": "unknown"
},
{
"name": "failed",
"kind": "constant",
"range": {
"start": {
"file": "scheduler.capnp",
"line": 19,
"column": 3,
"byte_offset": 293
},
"end": {
"file": "scheduler.capnp",
"line": 19,
"column": 9,
"byte_offset": 299
}
},
"visibility": "unknown"
}
]
}symbols reports seventeen entries: Scheduler's two method declarations with their parameter entries — including id and cancelled, both returned rather than passed in — Job's four field declarations, and JobStatus's four members as constant.
Query
18 query tools, the same on every supported language. Descriptions live in the shared reference: /docs/query-tools.
callers control_flow data_flow definition diagnostics effect_closure effect_summary fix_auto get_type graph import_organize interface mutations references repo_outline skeleton symbols symbols_batch