claude_code: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is the ClaudeCode Elixir SDK - an idiomatic Elixir interface to the Claude Code CLI. The SDK spawns the claude command as a subprocess and communicates via streaming JSON over stdout.

Common Development Commands

Quality Checks

mix quality          # Run all code quality checks (compile, format, credo, dialyzer)
mix format           # Format code with Styler
mix credo --strict   # Run Credo analysis
mix dialyzer         # Run Dialyzer type checking

Testing

mix test                        # Run all tests
mix test test/path/to_test.exs # Run specific test file
mix test.all                    # Run tests with coverage report
mix coveralls.html              # Generate HTML coverage report

# Distributed tests (Adapter.Node) require a named BEAM node:
elixir --sname test -S mix test --include distributed

Development

mix deps.get              # Install dependencies
mix claude_code.install   # Install CLI binary to priv/bin/
mix claude_code.uninstall # Remove bundled CLI binary
mix claude_code.path      # Print resolved CLI binary path
iex -S mix                # Start interactive shell with project loaded
mix docs                  # Generate documentation

Architecture

The SDK is organized in three layers:

1. Adapter-agnostic — Session, Stream, Options (validation), Types, Message/Content structs
2. CLI protocol — CLI.Command (flags), CLI.Input (stdin), CLI.Parser (JSON parsing)
3. Adapters — Adapter.Port (local CLI via Port), Adapter.Node (distributed via BEAM), Adapter.Test (in-memory stubs)

Key modules:

• ClaudeCode.Session - Public API for session operations (lifecycle, runtime config, MCP, introspection, execute)
• ClaudeCode.Session.Server - GenServer that manages the adapter subprocess lifecycle
• ClaudeCode.Adapter.Port - Port-based adapter that spawns the CLI as a local subprocess
• ClaudeCode.Adapter.Node - Distributed adapter that runs Adapter.Port on a remote BEAM node via Erlang distribution
• ClaudeCode.CLI - Thin facade: binary resolution + command building (delegates to Resolver + Command)
• ClaudeCode.CLI.Command - Converts Elixir options to CLI flags and builds argument lists
• ClaudeCode.CLI.Parser - Parses newline-delimited JSON from CLI output into structs
• ClaudeCode.Adapter.Port.Installer - CLI binary download and version management
• ClaudeCode.Plugin - Plugin management (list, install, uninstall, enable, disable, update)
• ClaudeCode.Plugin.Marketplace - Marketplace management (list, add, remove, update)