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#

open Claude

let run () =
  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 responses = Client.receive_all client in
  List.iter
    (function
      | Response.Text t -> Fmt.pr "Claude: %s@." (Response.Text.content t)
      | _ -> ())
    responses

Streaming responses#

open Claude

let run () =
  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
       | Response.Text t -> Fmt.pr "%s" (Response.Text.content t)
       | _ -> ())

With custom handler#

Override the methods you care about by inheriting from Handler.default:

open Claude

let handler =
  object
    inherit Handler.default
    method! on_text t = Fmt.pr "%s" (Response.Text.content t)
    method! on_tool_use t = Fmt.pr "Tool: %s@." (Response.Tool_use.name t)
  end

let run () =
  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 "Summarize this project";
  Client.receive client |> Seq.iter (Handler.dispatch handler)

Requirements#

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

Licence#

ISC

Configure Feed