This library wraps the Claude Code CLI in a typed OCaml interface with bidirectional JSON streaming. It handles the full conversation protocol: message streaming, permission callbacks, tool execution hooks, and mid-conversation control.

Features#

Message streaming -- Lazy Seq.t-based response streaming
Permission control -- Custom callbacks for tool usage authorization
Hooks -- Intercept and modify tool execution
Tool definitions -- Register custom tools with JSON Schema input
MCP servers -- Integrate Model Context Protocol servers
Structured output -- Request JSON responses matching a schema
Dynamic control -- Change model, permissions, or settings mid-conversation
Server introspection -- Query available tools, models, and capabilities

Installation#

Install with opam:

$ opam install claude

If opam cannot find the package, it may not yet be released in the public opam-repository. Add the overlay repository, then install it:

$ opam repo add samoht https://tangled.org/gazagnaire.org/opam-overlay.git
$ opam update
$ opam install claude

Usage#

Basic query#

let () =
  Eio_main.run @@ fun env ->
  Eio.Switch.run @@ fun sw ->
  let process_mgr = Eio.Stdenv.process_mgr env in
  let clock = Eio.Stdenv.clock env in
  let client = Client.v ~sw ~process_mgr ~clock () in
  Client.query client "What is 2+2?";
  let messages = Client.receive_all client in
  List.iter
    (function
      | Message.Assistant msg ->
          Printf.printf "Claude: %s\n" (Message.Assistant.text msg)
      | _ -> ())
    messages

Streaming responses#

let () =
  Eio_main.run @@ fun env ->
  Eio.Switch.run @@ fun sw ->
  let process_mgr = Eio.Stdenv.process_mgr env in
  let clock = Eio.Stdenv.clock env in
  let client = Client.v ~sw ~process_mgr ~clock () in
  Client.query client "Explain OCaml modules";
  Client.receive client
  |> Seq.iter (function
       | Message.Assistant a -> print_string (Message.Assistant.text a)
       | _ -> ())

With custom handler#

let () =
  Eio_main.run @@ fun env ->
  Eio.Switch.run @@ fun sw ->
  let process_mgr = Eio.Stdenv.process_mgr env in
  let clock = Eio.Stdenv.clock env in
  let handler =
    Handler.default
      ~on_text:(fun _client text -> print_string text)
      ~on_tool_use:(fun _client tool ->
        Fmt.pr "Tool: %s\n" (Response.Tool_use.name tool))
      ()
  in
  let client = Client.v ~sw ~process_mgr ~clock () in
  Client.run client ~handler "Summarize this project"

Requirements#

OCaml >= 5.1
Eio, Jsont, Cmdliner, Bytesrw
Claude Code CLI installed and configured

Licence#

ISC

Configure Feed