My agentic slop goes here. Not intended for anyone else!
anil.recoil.org
1(** OCaml Eio library for Claude Code CLI.
2
3 This library provides an interface to the Claude Code command-line interface
4 using OCaml's Eio concurrency library. It wraps Claude CLI invocations with
5 JSON streaming for asynchronous communication.
6
7 {1 Overview}
8
9 The Claude library enables you to:
10 - Send messages to Claude and receive streaming responses
11 - Control tool permissions and execution
12 - Configure system prompts and model parameters
13 - Handle content blocks including text, tool use, and thinking blocks
14 - Manage sessions with proper resource cleanup
15
16 {1 Architecture}
17
18 The library is structured into several focused modules:
19
20 - {!Content_block}: Defines content blocks (text, tool use, tool results, thinking)
21 - {!Message}: Messages exchanged with Claude (user, assistant, system, result)
22 - {!Control}: Control flow messages for session management
23 - {!Permissions}: Fine-grained permission system for tool usage
24 - {!Options}: Configuration options for Claude sessions
25 - {!Transport}: Low-level transport layer for CLI communication
26 - {!Client}: High-level client interface for interacting with Claude
27
28 {1 Basic Usage}
29
30 {[
31 open Claude
32
33 (* Create a simple query *)
34 let query_claude ~sw env prompt =
35 let options = Options.default in
36 Client.query ~sw env ~options prompt
37
38 (* Process streaming responses *)
39 let process_response messages =
40 Seq.iter (function
41 | Message.Assistant msg ->
42 List.iter (function
43 | Content_block.Text t ->
44 print_endline (Content_block.Text.text t)
45 | _ -> ()
46 ) (Message.Assistant.content msg)
47 | _ -> ()
48 ) messages
49 ]}
50
51 {1 Advanced Features}
52
53 {2 Tool Permissions}
54
55 Control which tools Claude can use and how:
56
57 {[
58 let options =
59 Options.default
60 |> Options.with_allowed_tools ["Read"; "Write"; "Bash"]
61 |> Options.with_permission_mode Permissions.Mode.Accept_edits
62 ]}
63
64 {2 Custom Permission Callbacks}
65
66 Implement custom logic for tool approval:
67
68 {[
69 let my_callback ~tool_name ~input ~context =
70 if tool_name = "Bash" then
71 Permissions.Result.deny ~message:"Bash not allowed" ~interrupt:false
72 else
73 Permissions.Result.allow ()
74
75 let options = Options.default |> Options.with_permission_callback my_callback
76 ]}
77
78 {2 System Prompts}
79
80 Customize Claude's behavior with system prompts:
81
82 {[
83 let options =
84 Options.default
85 |> Options.with_system_prompt "You are a helpful OCaml programming assistant."
86 |> Options.with_append_system_prompt "Always use Jane Street style."
87 ]}
88
89 {1 Logging}
90
91 The library uses the Logs library for structured logging. Each module has its
92 own log source (e.g., "claude.message", "claude.transport") allowing fine-grained
93 control over logging verbosity:
94
95 {[
96 (* Enable debug logging for message handling *)
97 Logs.Src.set_level Message.src (Some Logs.Debug);
98
99 (* Enable info logging for transport layer *)
100 Logs.Src.set_level Transport.src (Some Logs.Info);
101 ]}
102
103 {1 Error Handling}
104
105 The library uses exceptions for error handling. Common exceptions include:
106 - [Invalid_argument]: For malformed JSON or invalid parameters
107 - [Transport.Transport_error]: For CLI communication failures
108 - [Message.Message_parse_error]: For message parsing failures
109
110 {1 Example: Complete Session}
111
112 {[
113 let run_claude_session ~sw env =
114 let options =
115 Options.create
116 ~allowed_tools:["Read"; "Write"]
117 ~permission_mode:Permissions.Mode.Accept_edits
118 ~system_prompt:"You are an OCaml expert."
119 ~max_thinking_tokens:10000
120 ()
121 in
122
123 let prompt = "Write a function to calculate fibonacci numbers" in
124 let messages = Client.query ~sw env ~options prompt in
125
126 Seq.iter (fun msg ->
127 Message.log_received msg;
128 match msg with
129 | Message.Assistant assistant ->
130 Printf.printf "Claude: %s\n"
131 (Message.Assistant.model assistant);
132 List.iter (function
133 | Content_block.Text t ->
134 print_endline (Content_block.Text.text t)
135 | Content_block.Tool_use t ->
136 Printf.printf "Using tool: %s\n"
137 (Content_block.Tool_use.name t)
138 | _ -> ()
139 ) (Message.Assistant.content assistant)
140 | Message.Result result ->
141 Printf.printf "Session complete. Duration: %dms\n"
142 (Message.Result.duration_ms result)
143 | _ -> ()
144 ) messages
145 ]}
146*)
147
148(** {1 Modules} *)
149
150module Client = Client
151(** High-level client interface for Claude interactions. *)
152
153module Options = Options
154(** Configuration options for Claude sessions. *)
155
156module Model = Model
157(** Claude AI model identifiers with type-safe variants. *)
158
159module Content_block = Content_block
160(** Content blocks for messages (text, tool use, tool results, thinking). *)
161
162module Message = Message
163(** Messages exchanged with Claude (user, assistant, system, result). *)
164
165module Control = Control
166(** Control messages for session management. *)
167
168module Permissions = Permissions
169(** Permission system for tool invocations. *)
170
171module Hooks = Hooks
172(** Hooks system for event interception. *)
173
174module Sdk_control = Sdk_control
175(** SDK control protocol for dynamic configuration. *)
176
177module Incoming = Incoming
178(** Discriminated union of all incoming message types from Claude CLI. *)
179
180module Structured_output = Structured_output
181(** Structured output support using JSON Schema. *)
182
183module Transport = Transport
184(** Low-level transport layer for CLI communication. *)