AgentREPL.jl CLAUDE.md

CLAUDE.md

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

Project Overview

AgentREPL.jl is a Julia package providing a persistent REPL for AI agents via MCP (Model Context Protocol) STDIO transport. It solves Julia's "Time to First X" (TTFX) problem by maintaining persistent Julia worker subprocesses, avoiding the 1-2 second startup penalty for each command. Supports multiple named sessions and Revise.jl hot-reloading.

Build and Test Commands

# Run all tests (Aqua quality + unit suites; fast, no subprocess spawning)
julia --project=. -e "using Pkg; Pkg.test()"

# Include the MCP protocol integration tests (spawns a server subprocess, ~60s)
AGENTREPL_E2E=true julia --project=. -e "using Pkg; Pkg.test()"

# Run a specific test file directly
julia --project=. test/test_eval.jl

# Start the MCP server manually (for debugging)
julia --project=. -e "using AgentREPL; AgentREPL.start_server()"

# Start server with a specific project activated
JULIA_REPL_PROJECT=/path/to/project julia --project=. bin/julia-repl-server

Architecture

Multi-Session Worker Subprocess Model

AgentREPL uses a multi-session worker subprocess architecture (via Malt.jl):

• The MCP server runs in the main Julia process
• Each named session has its own Malt.Worker process for code evaluation
• Sessions are isolated: separate variables, packages, and project environments
• reset kills a session's worker and spawns a fresh one (true hard reset)
• activate switches a session's active project/environment
• Revise.jl is auto-loaded on workers for hot-reloading support

Why Malt, not Distributed.jl: Malt spawns workers with monitor_stdout=false/monitor_stderr=false, so worker output goes to private pipes (drained to the server's stderr by _start_output_drain!) and can never reach the main process's stdout — which is the MCP JSON-RPC transport. Malt also has no global cluster state (each Worker is an independent object) and provides graceful stop (exit → SIGTERM → SIGKILL), isrunning, and TerminatedWorkerException, replacing hand-rolled lifecycle code. IPC is Malt.remote_eval_fetch(Main, w, expr) via the _remote_eval_fetch helper.