Excalidrawなどの実際のアプリケーション上でAIエージェントがタスクを実行し、再現可能なパフォーマンススコアを取得できるローカル練習環境を提供します。
別名 godarg/practonaut
- スター
- 0
- ツール
- —
- ダウンロード数(30日間)
- —
- 最新バージョン
- 0.2.0
- 最終コミット
- 2026年11月10日
- ライセンス
- Apache-2.0
Practonaut MCPとは
Excalidrawなどの実際のアプリケーション上でAIエージェントがタスクを実行し、再現可能なパフォーマンススコアを取得できるローカル練習環境を提供します。
プロジェクトのREADMEから生成された概要
Practonaut MCP server について
Practonautは、AIエージェントが実際のアプリケーションでトレーニングできるように設計されたローカル練習環境を提供します。現在はExcalidrawをサポートしており、ステップの接続や要素の recoloring(再着色)といった特定のタスクをエージェントが実行できます。GUIをピクセル操作でシミュレートするのではなく、エージェントはMCPクライアントを通じてセマンティックなアクションによって操作を行います。この構成により、すべての操作は、セットアップコマンドでインストールされるヘッドレスChromiumシェル内で動作する、実際の固定されたExcalidrawエンジンに対して適用されます。
開発者は、このツールを使用して再現可能なスコアに基づいたエージェントのベンチマークを行うことができます。benchコマンドを実行することで、リファレンスソリューションと比較して、pass@1や効率性などのメトリクスを評価できます。システムは、ゴールが達成されたかどうかを判断するために別のチェッカーを使用するため、結果がエージェント自身の主張に左右されることはありません。これはNode.jsを必要とするローカルファーストなツールであり、VMやDockerを必要としないため、既存の開発ワークフローやCIパイプラインに簡単に統合できます。
できること
- 1エージェントの進捗を視覚的にモニタリングブラウザベースのプレイヤーを通じて、エージェントがタスクを実行する様子をリアルタイムで確認できます。
- 2パフォーマンスの退行を検知2つの異なるベンチマークレポートを比較して、最近の変更がエージェントの能力に悪影響を与えていないかを確認できます。
プロジェクトの README から作成されています。すべてのユースケースは、その引用と照らし合わせて確認されています。
Practonaut MCPのインストール方法
フォーマット検証日 2026年11月10日Cursor に追加Gooseに追加Claude CodeにPractonaut MCPをインストール
$ claude mcp add practonaut -- npx -y practonautCursorにPractonaut MCPをインストール
~/.cursor/mcp.json
{
"mcpServers": {
"practonaut": {
"command": "npx",
"args": [
"-y",
"practonaut"
]
}
}
}VS CodeにPractonaut MCPをインストール
.vscode/mcp.json
{
"servers": {
"practonaut": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"practonaut"
]
}
}
}VS Code CLIにPractonaut MCPをインストール
$ code --add-mcp '{"name":"practonaut","type":"stdio","command":"npx","args":["-y","practonaut"]}'Claude DesktopにPractonaut MCPをインストール
claude_desktop_config.json
{
"mcpServers": {
"practonaut": {
"command": "npx",
"args": [
"-y",
"practonaut"
]
}
}
}CodexにPractonaut MCPをインストール
$ codex mcp add practonaut -- npx -y practonautCodex config.tomlにPractonaut MCPをインストール
~/.codex/config.toml
[mcp_servers.practonaut] command = "npx" args = ["-y", "practonaut"]
Gemini CLIにPractonaut MCPをインストール
$ gemini mcp add -s user practonaut npx -- -y practonautGemini settings.jsonにPractonaut MCPをインストール
~/.gemini/settings.json
{
"mcpServers": {
"practonaut": {
"command": "npx",
"args": [
"-y",
"practonaut"
]
}
}
}自動チェック
実行日 2026年11月14日完全なレポート →自動チェックに合格しました。これはセキュリティ監査ではありません。コードを読み、サーバーに必要最小限のアクセス権を与えてください。 チェックの仕組み
- ソースリポジトリがリンクされており、アクセス可能godarg/practonaut is public and reachablegithub.com/godarg/practonaut ↗合格
- パッケージがこのリポジトリをソースとして指定practonaut names godarg/practonaut as sourcenpmjs.com/package/practonaut ↗合格
- ビルドの来歴 (Sigstore 証明)Sigstore attestation for practonautnpmjs.com/package/practonaut/v/0.2.0#provenance ↗合格
- オープンソースライセンス (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗合格
- 過去1年以内にコミットまたはリリースありLast commit or release 2026-11-10github.com/godarg/practonaut ↗合格
- OpenSSF Scorecard未チェック
- パッケージ名が有名なパッケージに酷似していないNo popular package one edit away from practonaut合格
- パッケージおよびその依存関係に重大な勧告なし7 resolved dependencies checked; no critical advisoryosv.dev ↗合格
- モデルへの隠れた指示がない0 tool descriptions and the README read; no override phrases, credential paths or hidden characters合格
- 破壊的なツールがラベル付けされている未チェック
- リモートエンドポイントが MCP ハンドシェイクに応答未チェック
README
GitHubで見るPractonaut
A local practice gym for AI agents on real apps. Demonstrate a task once, let any MCP agent
practise it, and get an independent, reproducible score — one npx command, no VM, no Docker.
Practonaut turns a real application — today Excalidraw — into a practice environment. A task is a start drawing plus a goal. You, or an agent over MCP, change the diagram one action at a time; each action is applied to a real, pinned Excalidraw engine and read back before it counts. When the attempt ends, a separate checker decides whether the goal is met. People and agents work on the same session at the same time, so you can watch an agent in your browser: the history marks each change as yours or as the agent's (Agent · claude-code).
Quick start in 60 seconds
Requires Node.js 22.18 or newer (macOS, Linux or Windows).
npx practonaut # opens the example task in your browser at once
npx practonaut setup # once: the Chromium headless shell for the real Excalidraw engine (about 105–130 MB)
Watch a demonstration in the Player solves the example task once: actions land on the board,
the real Excalidraw confirms each one, and the result check judges the end. It is never your
result; Stop or Escape ends it. Before setup everything works model-only: actions are not
confirmed in the real app, and a banner says so and names the download.
Let an agent practise (Claude Code shown; any MCP client works):
claude mcp add practonaut -- npx -y practonaut mcp --task excalidraw/connect
On native Windows (not WSL) npx is a .cmd file that an MCP client cannot start directly; add
cmd /c in front: claude mcp add practonaut -- cmd /c npx -y practonaut mcp --task excalidraw/connect.
Score it on a task, with a fresh session per run and an independent check:
npx practonaut bench --agent claude-code --tasks excalidraw/connect
More in getting started.
Create your own task
Draw the start and the goal in Excalidraw, then:
npx practonaut tasks from-scenes start.excalidraw goal.excalidraw --out my-task
npx practonaut play my-task/world
The difference becomes the goal (steps, labels, shapes, colours, frames, groups, arrows). Practonaut only writes the task if the goal passes its own check, the start fails, a generated reference solution passes and generated near misses fail. The same works in the Player under Create, where you can also record a demonstration in the real editor and have the rule confirmed by a second recording. See the authoring guide.
Benchmark your agent
npx practonaut bench --agent oracle --tasks all --seeds 2 # reference solutions: the score's ceiling
npx practonaut bench --agent random --tasks all --max-actions 30 # random actions: the floor
npx practonaut bench --agent claude-code --tasks excalidraw/insert-between --repeats 3
npx practonaut bench --agent "my-agent --mcp {mcp_config} --prompt {prompt}" # any agent
npx practonaut bench --agent claude-code --world my-task/world --oracle my-task/oracle.json # your own task
npx practonaut report ~/.practonaut/bench/<id>/report.json --html report.html
npx practonaut report ~/.practonaut/bench/<id>/report.json --verify # re-judge from the run files
npx practonaut compare before/report.json after/report.json --fail-on-regression # did a change break an instance?
npx practonaut report ~/.practonaut/bench/<id>/report.json --junit runs.xml --card card --badge badge.svg
Each run gets its own session and data folder; the agent reaches the session only through the
Practonaut MCP tools and gets the same public task a person gets. The claude-code preset does not
pass provider keys, tokens or billing switches from your environment to Claude Code (a set
ANTHROPIC_API_KEY would silently switch it to API billing), so Claude Code uses the login it has —
your subscription, if you logged in with one; --keep-env ANTHROPIC_API_KEY passes a key on
purpose. Scores come from the host's history and a
separate checker, never from what the agent says: pass@1, pass^k, actions, efficiency against the
reference solution. The JSON report has a schema. report checks that every pass and every number
follows from the verdicts in the file — consistency, not proof: a file edited consistently still
passes, and report says "consistency-checked, not re-verified". report --verify re-runs the
checker on the session and the real-app export kept in the bench folder, whose SHA-256 the report
records, against the world and reference solutions stored in that folder (so a moved folder still
verifies), re-derives each run's actions and reference length, and refuses any difference by name; host calls and times are marked as reported by the runner. Nothing is
signed: whoever can write the bench folder can replace those files too.
A report says why a run failed, not only that it did: rates as fractions with a 95 % interval, failed
runs first, each unmet goal condition with the action after which it was last lost (judged by the
checker after every action), error classes with their explanation, the trajectory, the final board —
the real Excalidraw's own export, or a schematic labelled as such — beside an example target, the
call log and the tokens, turns and cost the client reports about itself. compare puts two reports
side by side instance by instance: it refuses reports that are not comparable, names instance
regressions (three repeats a side, all passed before, all failed after) and says "not
distinguishable at this n" when an exact McNemar test cannot tell the two apart. Both reports must come
from the same kind of agent: oracle and random mark the ends of the score and compare only with a
built-in, a command template only with a command template; as the baseline for your agent, bench a
configuration of it that you trust.
In CI, examples/ci/practonaut-bench.yml benches your agent with
your own credentials and fails the job on an instance regression against a committed baseline; --junit
gives CI test views one test case per run. --card and --badge draw the header line as a 1280 × 640
card (SVG and PNG, light and dark) and a badge, with n, the interval, the verification status and the
isolation level on them.
The example report is a real run of Claude Code on three tasks, two repeats each (JSON, HTML) — one seed, six runs: it shows the format, it does not rank a model. Details: benchmarks.
Task library
Library, not a challenge tier. These tasks are an example set and a shared smoke test, not a measure of ability: current Claude models solve them, and five harder candidate families found no headroom on Practonaut's own actions in 0.2.0 (gate reports). A family becomes a challenge tier only after it passes a preregistered ladder gate.
16 tasks for Excalidraw 0.18.1, each in English and German with three label variants, a reference
solution and near misses. List them with npx practonaut tasks list; open one with
npx practonaut play <task>; address them as excalidraw/<task> in mcp and bench.
| Task | Level | Reference actions | Goal |
|---|---|---|---|
add-step |
●○○ | 1 | Add a step |
connect |
●○○ | 1 | Connect two steps |
disconnect |
●○○ | 1 | Remove a shortcut arrow |
recolor |
●○○ | 1 | Mark the error step |
remove-step |
●○○ | 1 | Remove a step |
rename-frame |
●○○ | 1 | Name the frame |
rename-step |
●○○ | 1 | Fix a label |
align |
●●○ | 3 | Align a row |
close-chain |
●●○ | 1 | Close the gap in a chain |
group |
●●○ | 2 | Group a sub-process |
insert-between |
●●○ | 4 | Insert a step between two others |
reconnect |
●●○ | 1 | Rewire an arrow |
reorder |
●●○ | 4 | Put the steps in order |
decision |
●●● | 6 | Build a decision with two exits |
restyle-flow |
●●● | 6 | Turn a list into a styled flow |
two-frames |
●●● | 4 | Sort two sub-processes into frames |
How scoring works
- The host keeps the history. Every action goes through one session host. It records each action with a state hash and who made it; agents and people cannot write the state any other way.
- The real engine confirms each action. With Chromium installed, each action is applied to a pinned Excalidraw running headless and read back; an action the real app disagrees with is rejected.
- A separate checker decides. After the attempt, another process replays the history with its own interpreter, reads the real Excalidraw export with its own parser, and evaluates the goal. It first makes sure an empty, an unchanged and a wrong submission all fail.
An agent gets the same task and the same public goal conditions as a person in the Player — one sentence per condition plus its formal form, which is the goal predicate written out — and the same Check button. It acts through Practonaut's semantic actions over MCP, not through the GUI. The reference solution, the near misses and held-out checker data never reach it over MCP.
Limits
- One application. Excalidraw 0.18.1 is the only app so far. The adapter contract is meant for more (adapter guide); none exists yet.
- Semantic actions, not pixels. Agents act through Practonaut's actions (add a step, connect, rename, …), not by clicking a screen. This measures whether an agent can reach a goal in the app's model, not whether it can operate the GUI.
- Not sealed. Agents run as your OS user. An agent with its own file or shell tools could read
the task library on disk, reference solutions included. The
claude-codepreset allows only Practonaut's tools; for other agents that is up to you. - Small evidence so far. The example report has two runs per task. Whether practising here makes people better at the real tool has not been studied.
- Without Chromium Practonaut runs model-only: tasks work, but nothing is checked against the real app, and it says so.
- Screen-reader and 200 % zoom checks by a person: one run so far (VoiceOver on macOS with Chrome, 2026-10-17), no problems found; other screen readers and regular screen-reader users are not tested yet (manual checks).
Requirements
- Node.js ≥ 22.18 and npm.
- Optional:
npx practonaut setupdownloads Playwright's Chromium headless shell once for the real engine. Nothing is downloaded on install; the package has no install script. - Local data lives in
~/.practonaut(orPRACTONAUT_HOME). No telemetry, no account. Practonaut's own process makes no network calls while practising (npxfetches the package andsetupfetches Chromium, each once); an agent you connect talks to its own model provider.
Documentation
Getting started · Agent guide · Benchmarks · Authoring · World format · Architecture · Adapter guide · Session host · Threat model · Glossary · All documents
Contributing
Issues and pull requests are welcome — new tasks, bug fixes, and especially a second application adapter. Start with CONTRIBUTING.md; setup is three commands. Security reports go through SECURITY.md.
License
Apache License 2.0; see NOTICE. The bundled Excalidraw engine and fonts keep their own licenses (shipped with the package). The example world and the task library are CC0-1.0.
Practonaut MCPのよくある質問
Practonaut MCPをClaude Codeに追加するには
ターミナルでclaude mcp add practonaut -- npx -y practonautを実行します。すべてのプロジェクトで利用するには--scope userを追加します。
Practonaut MCPをCursorに追加するには
~/.cursor/mcp.jsonを開き、上記のインストールセクションに示すCursor設定を使ってmcpServersの下にサーバーを追加します。
エージェントのパフォーマンスはどのようにスコア化されますか?
スコアはセッション履歴と、最終状態をゴールと比較して評価する独立したチェッカーから算出されます。エージェント自身の主張に依存することはありません。
仮想マシンやDockerは必要ですか?
いいえ、VMやDockerは不要で、単一のnpxコマンドで実行可能です。