Agentrepl.jl

🚀 AgentREPL.jl

AgentREPL.jl 是一个通过 MCP（模型上下文协议）为 AI 代理提供持久化 Julia REPL 的工具。它有效解决了 Julia 的 “首次执行时间（TTFX）” 问题，避免了每次调用 julia -e "..." 时的启动、包加载和 JIT 编译开销，显著提升了 AI 代理工作流的效率。

🚀 快速开始

选项 A：使用插件（推荐）

使用 AgentREPL 最简单的方法是通过随附的 Claude Code 插件：

claude /plugin add samtalki/AgentREPL.jl

这将提供：

• 自动配置的 MCP 服务器（无需手动设置）
• 斜杠命令：/julia-reset、/julia-info、/julia-pkg、/julia-activate
• Julia 开发的最佳实践技巧

选项 B：手动 MCP 配置

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

使用 AgentREPL

启动一个新的 Claude Code 会话。当 Claude 需要时，Julia MCP 服务器将自动启动。 向 Claude 提出运行 Julia 代码的请求，例如：

"Calculate the first 10 Fibonacci numbers in Julia"

Claude 将使用 eval 工具并显示 REPL 风格的输出：

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

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

第一次调用可能需要几秒钟进行 JIT 编译；后续调用将即时完成。

✨ 主要特性

解决 TTFX 问题

Julia 的 “首次执行时间（TTFX）” 问题严重影响 AI 代理工作流。每次 julia -e "..." 调用都会产生 1 - 2 秒的启动、包加载和 JIT 编译时间。AgentREPL 通过 MCP STDIO 传输提供持久化的 Julia 会话，Julia 进程保持活动状态，因此只需支付一次 TTFX 成本。

与其他工具对比优势

关键优势

• STDIO 传输：不打开网络端口，更安全，可注册到 Julia General。
• 自动启动：Claude Code 在需要时自动启动 AgentREPL。
• 持久化状态：变量、函数和已加载的包在多次调用之间保持有效。
• 真正的硬重置：工作子进程模型允许在不重启 Claude Code 的情况下重新定义类型。
• 现代工作流：内置对 Pkg.test、Pkg.develop 和 Pkg.free 的支持。
• 简单设置：使用插件无需配置，或通过一个命令进行手动设置。

📦 安装指南

正式安装

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

开发安装

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

💻 使用示例

基础用法

# 计算前 10 个斐波那契数
julia> [fibonacci(i) for i in 1:10]

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

高级用法

# 定义斐波那契函数并计算前 10 个斐波那契数
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]

📚 详细文档

工具介绍

eval

在持久化会话中评估 Julia 代码。输出以熟悉的 REPL 风格格式化：

julia> x = 1 + 1

2

julia> x + 10

12

变量持久化！多行代码也适用：

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]

打印输出会显示在结果之前：

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

Computing...
42

错误会被捕获并显示截断的堆栈跟踪：

julia> undefined_var

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

特性：

• 变量和函数在多次调用之间保持有效。
• 一次加载的包保持加载状态。
• 捕获返回值和打印输出。
• 捕获错误并显示堆栈跟踪。

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`

这使得：

• 清除所有变量。
• 卸载所有包。
• 重新定义类型/结构体（软重置无法实现）。
• 以全新的 Julia 状态开始。 激活的环境在重置后保持不变。

info

获取会话信息，包括工作进程 ID。

Julia Version: 1.12.2
Active Project: /home/user/MyProject
User Variables: x, fib, data
Loaded Modules: 42
Worker ID: 3

activate

切换活动的 Julia 项目/环境。

activate(path=".")
# Activated project: /home/user/MyProject
# Use `pkg(action="instantiate")` to install dependencies if needed.

activate(path="/path/to/OtherProject")
# Activated project: /path/to/OtherProject

activate(path="@v1.10")
# Activated shared environment: @v1.10

激活后，使用以下命令安装依赖：

pkg(action="instantiate")

pkg

管理当前环境中的 Julia 包。

pkg(action="status")
# Package Status:
# Project MyProject v0.1.0
# Status `~/MyProject/Project.toml`
#   [682c06a0] JSON3 v1.14.0
#   [a93c6f00] DataFrames v1.6.1

pkg(action="add", packages="CSV, HTTP")
# Package add complete.

pkg(action="test")
# Test Summary: | Pass  Total
# MyProject     |   42     42

pkg(action="develop", packages="./MyLocalPackage")
# Development mode: MyLocalPackage -> ~/MyLocalPackage

pkg(action="free", packages="MyLocalPackage")
# Freed MyLocalPackage from development mode

操作：

log_viewer

打开一个终端，实时显示 Julia 输出。

log_viewer(mode="auto")
# Log viewer enabled.
# Log file: ~/.julia/logs/repl.log
# A terminal window should have opened.

log_viewer(mode="tmux")
# tmux session 'julia-repl' created. Attach with: tmux attach -t julia-repl

log_viewer(mode="file")
# Log file: ~/.julia/logs/repl.log
# Run manually: tail -f ~/.julia/logs/repl.log

log_viewer(mode="off")
# Log viewer disabled.

对于查看实时打印输出非常有用，特别是对于长时间运行的计算。

配置

环境/项目管理

有三种方法可以设置 Julia 环境：

1. 运行时设置（推荐）：使用 activate 动态切换环境：

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

2. 通过环境变量设置：在启动前设置 JULIA_REPL_PROJECT：

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. 在代码中设置：直接传递给服务器：

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

激活的环境在 reset 调用后保持不变。

与其他工具的比较

与 Auton.jl 对比

Auton.jl 为人工参与的工作流提供 LLM 增强的 REPL 模式。

何时使用 Auton.jl：当你在 Julia REPL 中工作时需要 LLM 辅助，例如上下文感知建议、代码生成和迭代优化。

何时使用 AgentREPL：当你希望 Claude Code 在更大的 AI 代理工作流中自主执行 Julia 代码，而无需人工在 REPL 前操作。

与 ClaudeCodeSDK.jl 对比

ClaudeCodeSDK.jl 是一个从 Julia 调用 Claude Code 的 SDK。它与 AgentREPL 的方向相反。

何时使用 ClaudeCodeSDK.jl：当你想从 Julia 脚本或应用程序中以编程方式调用 Claude 时。

何时使用 AgentREPL：当你希望 Claude Code 在持久化会话中执行 Julia 代码时。

与 ModelContextProtocol.jl 对比

ModelContextProtocol.jl 是 AgentREPL 所基于的 MCP 框架。它提供了创建 MCP 服务器的构建块（MCPTool、MCPResource、mcp_server）。

何时使用 ModelContextProtocol.jl：当你想构建超越代码评估的自定义 MCP 工具时。

何时使用 AgentREPL：当你希望在不编写任何 MCP 代码的情况下进行持久化 Julia 评估时。

与 MCPRepl.jl 对比

MCPRepl.jl 是一个启发了 AgentREPL 的优秀包。主要区别如下：

何时使用 MCPRepl.jl：当你想与 AI 代理共享 REPL（可以看到彼此的命令）时。

何时使用 AgentREPL：当你希望自动启动、不使用网络端口或计划通过 Julia 注册表分发时。

与 REPLicant.jl 对比

REPLicant.jl 使用 TCP 套接字和自定义协议（非 MCP）。

何时使用 REPLicant.jl：当你使用 just 进行任务自动化时。

何时使用 AgentREPL：当你希望与 Claude Code 进行标准 MCP 集成时。

与 DaemonMode.jl 对比

DaemonMode.jl 是一个用于更快运行 Julia 脚本的客户端 - 守护进程系统。

何时使用 DaemonMode.jl：对于一般脚本加速（如果使用较旧的 Julia 版本）。

何时使用 AgentREPL：对于现代 Julia 与 AI 代理的集成。

Claude Code 插件

claude-plugin/ 目录包含一个现成的 Claude Code 插件，提供以下功能：

自动配置的 MCP 服务器

无需手动运行 claude mcp add。插件会自动配置 Julia MCP 服务器。

斜杠命令

最佳实践技巧

包含的技巧教会 Claude：

• 在调用 eval 之前始终显示代码（以便显示可读的权限提示）
• 首次环境设置对话
• 何时使用硬重置与继续执行
• 测试和开发工作流
• 错误处理模式

安装

claude /plugin add samtalki/AgentREPL.jl

或者进行本地开发：

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

详情请参阅 claude-plugin/README.md。

🔧 技术细节

架构

AgentREPL 使用 工作子进程模型 通过 Distributed.jl 实现：

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

为什么使用工作子进程？

• reset 可以杀死并重新启动工作进程以实现 真正的硬重置。
• 类型/结构体重定义可行（进程内重置无法实现）。
• 激活的环境在重置后保持不变。
• 工作进程在首次使用时延迟启动，以避免 STDIO 冲突。

API 参考

导出函数

start_server(; project_dir=nothing)

使用 STDIO 传输启动 AgentREPL MCP 服务器。 参数：

• project_dir::Union{String,Nothing}：可选的 Julia 项目路径，用于在工作进程上激活。 示例：

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

环境变量

内部架构

对于扩展 AgentREPL 的开发者： 文件结构：

src/
  AgentREPL.jl           # 主模块（导入、包含、导出）
  types.jl               # 状态结构体（WorkerState, LogViewerState 等）
  formatting.jl          # 结果格式化，堆栈跟踪截断
  worker.jl              # 分布式工作进程生命周期
  packages.jl            # Pkg 操作，项目激活
  logging.jl             # 日志查看器功能
  tools.jl               # MCP 工具定义
  server.jl              # start_server 函数
  deprecated/
    tmux.jl              # 已弃用的 tmux 双向 REPL

关键组件：

📄 许可证

本项目采用 Apache License 2.0 许可协议。详情请参阅 LICENSE。

贡献说明

欢迎贡献代码！请参阅 CONTRIBUTING.md 了解以下方面的指南：

• 设置开发环境
• 代码风格和文档标准
• 拉取请求流程
• 添加新功能

致谢

• ModelContextProtocol.jl - MCP 框架
• MCPRepl.jl - 灵感来源和先前工作
• REPLicant.jl - 替代方法
• Modern Julia Workflows - 最佳实践指南

变更日志

版本历史和发布说明请参阅 CHANGELOG.md。

安全说明

详细的安全考虑请参阅 SECURITY.md。 简而言之：

• STDIO 传输 = 无网络攻击面
• 代码以用户权限运行
• Claude 会话结束时进程终止
• 不防范恶意代码（由 AI 决定运行内容）