Agent - Autonomous Claude Code agent for OCaml projects#

A CLI tool that runs Claude Code autonomously in a Docker container, looping until a command succeeds.

Installation#

opam install agent

Quick Start#

# Initialize (creates Dockerfile and preset prompts)
agent init

# Authenticate with Claude (one-time setup)
agent login

# Run until tests pass
agent run --preset fix

# Run with worktree isolation (recommended)
agent run -w --preset fix

Usage#

Basic Commands#

# Single run (no loop)
agent run "Add unit tests for the parser module"

# Loop until command succeeds
agent run --until "dune test" "Fix all test failures"

# Use a preset prompt
agent run --preset fix        # Run tests, fix failures
agent run --preset tidy       # Apply /ocaml-dev:tidy skill
agent run --preset security   # Apply /ocaml-security skill
agent run --preset lint       # Fix merlint warnings

Worktree Isolation#

Use --worktree (or -w) to run in a git worktree. Changes stay isolated until you review and merge them:

agent run -w --preset fix

On completion, use agent merge to review and merge:

# List available worktrees
agent merge

# Review changes
cd ~/.cache/agent/worktrees/myproject-1706985432 && git diff

# Merge into main repo (agent resolves conflicts automatically)
agent merge myproject-1706985432

# Or discard without merging
agent merge --discard myproject-1706985432

Focus on Specific Paths#

Use --path to restrict the agent to specific directories:

agent run --preset tidy --path lib/parser
agent run --preset security --path lib/crypto --path lib/auth

Prompt Sources#

# Positional argument
agent run --until "dune test" "Fix the parser bug"

# From file
agent run --until "dune test" -p prompt.txt

# From stdin
echo "Fix the bug" | agent run --until "dune test" -p -

Other Commands#

agent init      # Create Dockerfile and preset prompts
agent login     # Authenticate with Claude
agent merge     # List worktrees or merge one into main repo
agent shell     # Debug shell in the container
agent todo      # Show TODO list
agent todo --check  # Exit 0 if all TODOs complete (for --until)

Configuration#

Presets#

Presets are stored in ~/.config/agent/prompts/ and can be customized:

• fix.txt - Test fixing with /ocaml and /ocaml-testing skills
• tidy.txt - Code cleanup with /ocaml-dev:tidy skill
• security.txt - Security hardening with /ocaml-security, /fuzz skills
• lint.txt - Merlint warnings with /ocaml skill

Each preset has a default --until command:

Docker Container#

The Dockerfile is stored in ~/.local/share/agent/Dockerfile and includes:

• OCaml 5.4 + dune, merlin, LSP, ocamlformat, utop
• Claude Code
• merlint, prune, crund
• memtrace
• perf, valgrind, gdb, strace, ltrace
• alcotest, crowbar (testing)

Directories#

Options Reference#

agent run [OPTIONS] [PROMPT]

OPTIONS:
  --until COMMAND       Loop until COMMAND succeeds (exit 0)
  --preset NAME         Use preset (fix, tidy, security, lint)
  --path PATH           Focus on specific paths (repeatable)
  -w, --worktree        Run in isolated git worktree
  -p, --prompt FILE     Read prompt from file (use '-' for stdin)
  -C, --directory DIR   Working directory
  --privileged          Run without Docker sandbox
  --max-iterations N    Limit iterations (default: unlimited)
  --show-tools          Show tool usage during conversation
  -v, -vv, -vvv         Increase verbosity