Agentrepl.jl

🚀 AgentREPL.jl

AgentREPL.jl offers a persistent Julia REPL for AI agents through the MCP (Model Context Protocol), effectively addressing Julia's "Time to First X" (TTFX) issue. Each julia -e "..." call typically incurs 1 - 2 seconds for startup, package loading, and JIT compilation. AI agents like Claude Code, which spawn new Julia processes for each command, end up wasting significant compute time. AgentREPL solves this by maintaining a persistent Julia session using MCP STDIO transport, ensuring that the TTFX cost is only paid once.

🚀 Quick Start

Option A: Use the Plugin (Recommended)

The simplest way to use AgentREPL is via the included Claude Code plugin:

claude /plugin add samtalki/AgentREPL.jl

This provides:

• An auto - configured MCP server (no manual setup required).
• Slash commands: /julia - reset, /julia - info, /julia - pkg, /julia - activate.
• Best practices skill for Julia development.

Option B: Manual MCP Configuration

claude mcp add julia - repl -- julia --project=/path/to/AgentREPL.jl /path/to/AgentREPL.jl/bin/julia - repl - server

Using AgentREPL

Start a new Claude Code session. The Julia MCP server will start automatically when Claude needs it. Ask Claude to run Julia code, for example:

"Calculate the first 10 Fibonacci numbers in Julia" Claude will use the eval tool and display REPL - style output:

julia> [fibonacci(i) for i in 1:10]

[1, 1, 2, 3, 5, 8, 13, 21, 34, 55]

The first call may take a few seconds for JIT compilation; subsequent calls are instant.

✨ Features

Why AgentREPL?

Key Advantages

• STDIO Transport: No network port is opened, providing higher security and eligibility for registration in the Julia General registry.
• Auto - spawns: Claude Code starts AgentREPL automatically when necessary.
• Persistent State: Variables, functions, and loaded packages remain available across calls.
• True Hard Reset: The worker subprocess model allows type redefinitions without restarting Claude Code.
• Modern Workflows: Built - in support for Pkg.test, Pkg.develop, and Pkg.free.
• Simple Setup: Use the plugin for zero - config, or a single command for manual setup.

📦 Installation

using Pkg
Pkg.add(url="https://github.com/samtalki/AgentREPL.jl")

Or for development:

Pkg.dev("https://github.com/samtalki/AgentREPL.jl")

💻 Usage Examples

Basic Usage

julia> x = 1 + 1

2

julia> x + 10

12

Variables persist! Multi - line code works too:

julia> function fib(n)
           n <= 1 && return n
           fib(n - 1) + fib(n - 2)
       end
       [fib(i) for i in 1:10]

[1, 1, 2, 3, 5, 8, 13, 21, 34, 55]

Printed output appears before the result:

julia> println("Computing..."); 42

Computing...
42

Errors are caught with truncated stacktraces:

julia> undefined_var

UndefVarError: `undefined_var` not defined
Stacktrace:
 [1] top - level scope
  ... (truncated)

Features:

• Variables and functions persist across calls.
• Packages loaded once stay loaded.
• Both return values and printed output are captured.
• Errors are caught and reported with backtraces.

Advanced Usage

# Hard reset
reset()

Session reset complete.
- Old worker (ID: 2) terminated
- New worker (ID: 3) spawned
- All variables, functions, and types cleared
- Packages will need to be reloaded with `using`

This enables:

• Clearing all variables.
• Unloading all packages.
• Redefining types/structs (impossible with soft resets).
• Starting with a completely fresh Julia state. The activated environment persists across resets.

📚 Documentation

Tools Provided

eval

Evaluate Julia code in a persistent session. Output is formatted in familiar REPL style.

reset

Hard reset: Kills the worker process and spawns a fresh one.

info

Get session information including worker process ID.

activate

Switch the active Julia project/environment.

pkg

Manage Julia packages in the current environment.

log_viewer

Open a terminal showing Julia output in real - time.

Configuration

Environment/Project Management

There are three ways to set the Julia environment:

1. At runtime (recommended): Use activate to switch environments dynamically:

activate(path="/path/to/your/project")
pkg(action="instantiate")

2. Via environment variable: Set JULIA_REPL_PROJECT before starting:

JULIA_REPL_PROJECT=/path/to/your/project claude mcp add julia - repl -- julia --project=/path/to/AgentREPL.jl -e "using AgentREPL; AgentREPL.start_server()"

3. In code: Pass directly to the server:

AgentREPL.start_server(project_dir="/path/to/your/project")

The activated environment persists across reset calls.

Comparison with Alternatives

vs Auton.jl

Auton.jl provides LLM - augmented REPL modes for human - in - the - loop workflows.

vs ClaudeCodeSDK.jl

ClaudeCodeSDK.jl is an SDK for calling Claude Code from Julia. It's the opposite direction of AgentREPL.

vs ModelContextProtocol.jl

ModelContextProtocol.jl is the MCP framework that AgentREPL is built on. It provides the building blocks (MCPTool, MCPResource, mcp_server) for creating MCP servers.

vs MCPRepl.jl

MCPRepl.jl is an excellent package that inspired AgentREPL.

vs REPLicant.jl

REPLicant.jl uses TCP sockets with a custom protocol (not MCP).

vs DaemonMode.jl

DaemonMode.jl is a client - daemon system for running Julia scripts faster.

Claude Code Plugin

The claude - plugin/ directory contains a ready - to - use Claude Code plugin that provides:

• Auto - configured MCP Server: No need to manually run claude mcp add. The plugin configures the Julia MCP server automatically.
• Slash Commands: | Command | Description | |---------|-------------| | /julia - reset | Kill and respawn the Julia worker (hard reset) | | /julia - info | Show session information | | /julia - pkg <action> [packages] | Package management | | /julia - activate <path> | Activate a project/environment |
• Best Practices Skill: The included skill teaches Claude various best practices.

Installation

claude /plugin add samtalki/AgentREPL.jl

Or for local development:

claude --plugin - dir /path/to/AgentREPL.jl/claude - plugin

See [claude - plugin/README.md](claude - plugin/README.md) for details.

Security

See SECURITY.md for detailed security considerations. TL;DR:

• STDIO transport = no network attack surface.
• Code runs with user permissions.
• Process terminates when Claude session ends.
• No protection against malicious code (AI decides what to run).

Development

Running Tests

julia --project=. -e "using Pkg; Pkg.test()"

Local Testing

using AgentREPL
AgentREPL.start_server()  # Blocks, waiting for MCP messages on stdin

See CONTRIBUTING.md for detailed contribution guidelines.

🔧 Technical Details

Architecture

AgentREPL uses a worker subprocess model via Distributed.jl:

┌─────────────────────────────────────────────────────┐
│ Claude Code                                          │
│   ↕ STDIO (MCP)                                      │
│ ┌─────────────────────────────────────────────────┐ │
│ │ AgentREPL MCP Server (Main Process)             │ │
│ │   ↕ Distributed.jl                              │ │
│ │ ┌─────────────────────────────────────────────┐ │ │
│ │ │ Worker Process (code evaluation happens here)│ │ │
│ │ └─────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘

Why a worker subprocess?

• reset can kill and respawn the worker for a true hard reset.
• Type/struct redefinitions work (impossible with in - process reset).
• The activated environment persists across resets.
• Worker is spawned lazily on first use to avoid STDIO conflicts.

API Reference

Exported Functions

start_server(; project_dir=nothing)

Start the AgentREPL MCP server using STDIO transport. Arguments:

• project_dir::Union{String,Nothing}: Optional path to a Julia project to activate on the worker Example:

using AgentREPL
AgentREPL.start_server(project_dir="/path/to/myproject")

Environment Variables

For visual output, set JULIA_REPL_VIEWER = auto to open a terminal showing real - time Julia output.

Internal Architecture

File Structure:

src/
  AgentREPL.jl           # Main module (imports, includes, exports)
  types.jl               # State structs (WorkerState, LogViewerState, etc.)
  formatting.jl          # Result formatting, stacktrace truncation
  worker.jl              # Distributed worker lifecycle
  packages.jl            # Pkg actions, project activation
  logging.jl             # Log viewer functionality
  tools.jl               # MCP tool definitions
  server.jl              # start_server function
  deprecated/
    tmux.jl              # Deprecated tmux bidirectional REPL

Key Components:

All functions have docstrings accessible via ?function_name in the Julia REPL.

📄 License

Apache License 2.0 - See LICENSE for details.

Acknowledgments

• ModelContextProtocol.jl - MCP framework
• MCPRepl.jl - Inspiration and prior art
• REPLicant.jl - Alternative approach
• Modern Julia Workflows - Best practices guide

Changelog

See CHANGELOG.md for version history and release notes.

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines on:

• Setting up the development environment
• Code style and documentation standards
• Pull request process
• Adding new features