Agentrepl.jl

🚀 AgentREPL.jl

AIエージェント用の永続的なJulia REPLをMCP（Model Context Protocol）経由で提供します。

このプロジェクトは、Juliaの「Time to First X」（TTFX）問題がAIエージェントのワークフローに深刻な影響を与えるという問題を解決します。各 julia -e "..." の呼び出しには、1 - 2秒の起動時間、パッケージの読み込み、JITコンパイルが必要です。Claude CodeなどのAIエージェントは、コマンドごとに新しいJuliaプロセスを生成するため、計算時間が数分も無駄になります。

AgentREPLは、MCP STDIOトランスポートを介して永続的なJuliaセッションを提供します。Juliaプロセスは常に生き続けるため、TTFXのコストは一度だけ支払えば済みます。

🚀 クイックスタート

オプション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コンパイルに数秒かかる場合がありますが、それ以降の呼び出しは即座に実行されます。

✨ 主な機能

なぜAgentREPLなのか？

主な利点

• STDIOトランスポート：ネットワークポートを開かないため、より安全で、Julia Generalに登録できます。
• 自動起動：Claude Codeが必要なときに自動的にAgentREPLを起動します。
• 永続的な状態：変数、関数、および読み込まれたパッケージは、呼び出し間で保持されます。
• 完全なハードリセット：ワーカーサブプロセスモデルにより、Claude Codeを再起動することなく型の再定義が可能です。
• 最新のワークフロー：Pkg.test、Pkg.develop、および Pkg.free をサポートしています。
• 簡単なセットアップ：プラグインを使用するとゼロコンフィグですし、手動設定も1つのコマンドで可能です。

📦 インストール

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]

高度な使用法

# 複数行のコードを実行する例
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

アクション：

packages パラメータは、スペースまたはカンマ区切りの名前を受け付けます。

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環境を設定する方法は3つあります。 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 呼び出し間で保持されます。

他のツールとの比較

vs Auton.jl

Auton.jl は、人間が関与するワークフローのためのLLM拡張REPLモードを提供します。

Auton.jlを使用する場合：あなたがJulia REPLで作業しているときにLLMの支援が必要な場合。コンテキストを考慮した提案、コード生成、およびあなたが制御する反復的な改良が可能です。

AgentREPLを使用する場合：Claude Codeがより大きなAIエージェントのワークフローの一部としてJuliaコードを自律的に実行する必要がある場合。REPLで人間が存在する必要はありません。

vs ClaudeCodeSDK.jl

ClaudeCodeSDK.jl は、JuliaからClaude Codeを呼び出すためのSDKです。これはAgentREPLとは逆の方向です。

ClaudeCodeSDK.jlを使用する場合：JuliaスクリプトまたはアプリケーションからClaudeをプログラム的に呼び出したい場合。

AgentREPLを使用する場合：Claude Codeが永続的なセッションでJuliaコードを実行する必要がある場合。

vs ModelContextProtocol.jl

ModelContextProtocol.jl は、AgentREPLが構築されているMCPフレームワークです。MCPサーバーを作成するためのビルディングブロック（MCPTool、MCPResource、mcp_server）を提供します。

ModelContextProtocol.jlを使用する場合：コード評価以外のカスタムMCPツールを構築したい場合。

AgentREPLを使用する場合：MCPコードを書かずに永続的なJulia評価が必要な場合。

vs MCPRepl.jl

MCPRepl.jl は、AgentREPLにインスピレーションを与えた優れたパッケージです。主な違いは次のとおりです。

MCPRepl.jlを使用する場合：AIエージェントとREPLを共有したい場合（お互いのコマンドを見ることができます）。

AgentREPLを使用する場合：自動起動、ネットワークポート不要、またはJuliaレジストリを介して配布する予定の場合。

vs REPLicant.jl

REPLicant.jl は、カスタムプロトコル（MCPではない）を使用したTCPソケットを使用します。

REPLicant.jlを使用する場合：just を使用してタスクを自動化する場合。

AgentREPLを使用する場合：Claude Codeとの標準的なMCP統合が必要な場合。

vs 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")

環境変数

視覚的な出力のために、JULIA_REPL_VIEWER=auto を設定すると、リアルタイムでJuliaの出力を表示するターミナルが開きます。

内部アーキテクチャ

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

主要なコンポーネント：

すべての関数には、Julia REPLで ?function_name を使用してアクセスできるドキュメント文字列があります。

📄 ライセンス

Apache License 2.0 - 詳細は LICENSE を参照してください。

開発

テストの実行

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

ローカルテスト

using AgentREPL
AgentREPL.start_server()  # 標準入力でMCPメッセージを待機する

詳細な貢献ガイドラインは CONTRIBUTING.md を参照してください。

謝辞

• ModelContextProtocol.jl - MCPフレームワーク
• MCPRepl.jl - インスピレーションと先行技術
• REPLicant.jl - 別のアプローチ
• Modern Julia Workflows - ベストプラクティスガイド