
Echoproof
io.github.est57Published by GitHub account est57v0.4.0Updated Oct 27, 2026
Replay real HTTP traffic against base and changed builds; flag behavior changes the intent omits.
Overview
Echoproof replays recorded HTTP traffic against a base and a changed build, then reports behavior changes an assistant can judge against the intended change.
- What you can do
- Run a behavior check: replay a recorded snapshot against a target build, optionally comparing a base build against the changed one, and get a structured report with a run identifier.
- Compare two existing snapshots and classify each change as breaking, behavior or additive, grouped by endpoint and field.
- Inspect a single exchange from a run to see the full request, both responses and the per-field differences.
- Judge changes against a stated intent, so changes the intent does not explain are flagged as regressions.
- When to use it
- Useful when a coding agent edits an API service and should verify its own work against real recorded traffic before declaring the task done, or when you want a merge gate that catches unintended behavior changes that unit tests and code review miss.
- Requirements
- Runs as a local stdio process started with the echoproof mcp subcommand, so the echoproof binary must be installed first (Homebrew, release archive, or cargo install with Rust 1.85 or newer). A recorded traffic snapshot file and reachable base and target build URLs are needed for checks. ANTHROPIC_API_KEY is only needed when a check is given an intent to judge. Desktop coding agents only; web-based assistants cannot reach local builds.
Installation
In SourceWeft
- Open Echoproof in the dashboard and add it to a workspace.
- Enable the server for the chats that should use its tools.
Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.
Other MCP clients
Follow the launch instructions in the repository.
README
Echoproof
[CI] [crates.io] [Release] [License: MIT OR Apache-2.0]
Bahasa Indonesia | English
Verifikasi perilaku API untuk setiap perubahan kode, berdasarkan traffic nyata.
Echoproof merekam request dan response asli dari service Anda, memutarnya ulang ke build hasil perubahan kode, lalu melaporkan apa yang berubah, di endpoint dan field mana, pada berapa persen request, dan apakah perubahan itu memang diniatkan. Hasilnya bisa dipakai sebagai gate di CI atau langsung oleh coding agent (Claude Code, Cursor, dan sejenisnya) untuk memeriksa pekerjaannya sendiri.
[Echoproof menangkap regresi harga yang tidak dijelaskan oleh niat perubahan]
Daftar isi
- Mengapa Echoproof
- Fitur utama
- Instalasi
- Mulai cepat
- Demo
- Konsep
- Referensi perintah
- Konfigurasi
- Membaca laporan
- Integrasi CI
- Integrasi coding agent (MCP)
- Keamanan dan privasi
- Batasan
- Pengembangan
- Lisensi
Mengapa Echoproof
Saat sebagian besar kode ditulis oleh AI agent, jumlah perubahan naik jauh lebih cepat daripada kemampuan manusia untuk meninjaunya. Tes yang lulus dan diff yang tampak rapi belum menjamin perilaku sistem tetap benar, karena tes ditulis dari asumsi, sedangkan bug sering muncul dari kombinasi data nyata yang tidak terpikirkan.
Echoproof menjawab satu pertanyaan yang tidak dijawab oleh tes unit maupun code review:
Apakah perubahan ini mengubah perilaku sistem terhadap traffic nyata, dan apakah perubahan itu memang yang dimaksud?
Contoh yang ditangkap Echoproof: sebuah PR berniat "menambah field currency di katalog", tetapi tanpa sengaja salah menempatkan satu argumen. Akibatnya harga 3 dari 8 menu berubah, sementara 5 menu lainnya tetap benar. Tes unit lulus dan diff kode terlihat wajar. Echoproof melaporkan products[*].price: 18000 -> 22000 pada setiap request katalog dan menandainya sebagai regresi.
Fitur utama
- Rekam dari traffic nyata. Reverse proxy yang merekam setiap request dan response, dengan data sensitif disamarkan sebelum ditulis ke disk.
- Diff semantik. JSON dibandingkan per field, bukan per baris teks. Perubahan dikelompokkan per endpoint dan field, lalu diklasifikasikan sebagai
breaking,behavior, atauadditive. - Tahan noise. UUID, timestamp, dan nilai acak dikenali otomatis. Field yang berubah sendiri antar-run dipelajari dengan me-replay build lama dua kali.
- Aman terhadap state. Request tulis tidak di-replay kecuali diizinkan per endpoint. Build lama dan baru dibandingkan di atas data yang sama, dengan perintah reset di antara setiap putaran.
- Sadar niat perubahan. Setiap kelompok perubahan bisa dinilai oleh Claude terhadap deskripsi PR atau tugas agent. Perubahan yang tidak dijelaskan oleh niat ditandai sebagai regresi.
- Siap untuk CI dan agent. Exit code untuk gate merge, laporan Markdown untuk komentar PR, JSON untuk otomasi, dan server MCP untuk coding agent.
Instalasi
Homebrew (macOS dan Linux)
Binary siap pakai (disarankan)
Unduh arsip untuk platform Anda dari halaman rilis, atau lewat terminal:
Dengan Cargo
Jika Rust 1.85 atau lebih baru sudah terpasang:
Dari source code
Kebutuhan: Rust 1.85 atau lebih baru. curl diperlukan untuk menjalankan demo.
Binary echoproof dipasang di ~/.cargo/bin. Pastikan folder itu ada di PATH:
Mulai cepat
Langkah berikut memeriksa sebuah perubahan kode pada service yang berjalan di lingkungan uji Anda.
1. Buat file konfigurasi (opsional, semua pengaturan punya nilai default):
2. Rekam traffic. Jalankan proxy di depan service, lalu arahkan aplikasi, Postman, atau tes otomatis ke alamat proxy:
Hentikan dengan Ctrl-C setelah traffic yang representatif terkumpul.
Aplikasi Laravel bisa merekam tanpa proxy dengan echoproof/laravel: jalankan composer require echoproof/laravel, isi ECHOPROOF_RECORD=true di .env, dan traffic ditulis ke storage/echoproof/traffic.jsonl dengan aturan sensor yang sama.
3. Jalankan dua build, versi sebelum perubahan (base) dan sesudahnya (PR), memakai database yang sama.
4. Bandingkan:
5. Baca hasilnya. Exit code 0 berarti tidak ada perubahan yang tidak diharapkan, 1 berarti ada regresi, 2 berarti terjadi error. Lihat Membaca laporan.
Untuk menilai perubahan terhadap niatnya, tambahkan deskripsi PR dan diff kodenya:
Demo
Demo lengkap berjalan sekitar 10 detik dan tidak membutuhkan service Anda sendiri:
Demo memakai backend POS kecil (examples/demo-shop) yang memiliki state, yaitu stok produk yang berkurang setiap ada order. Sebuah "PR dari agent" berniat menambah field currency pada produk, tetapi juga mengubah cara diskon promo dan voucher digabungkan.
Konsep
Snapshot
Snapshot adalah file JSONL berisi satu pasangan request dan response per baris. Header dan field sensitif sudah disamarkan sebelum ditulis. Snapshot yang sama dapat dipakai berulang kali untuk memeriksa banyak PR.
Dua mode perbandingan
Pada mode base vs PR, response hasil rekaman tidak dipakai sebagai acuan. Echoproof memutar traffic yang sama ke kedua build di atas data yang sama:
Alamat server masing-masing build (misalnya http://127.0.0.1:8001 di URL gambar atau link pagination) dinormalkan otomatis, sehingga dua build yang berjalan di port berbeda tetap sebanding.
Mode aman
Secara default, hanya method GET, HEAD, dan OPTIONS yang di-replay. Request tulis dilewati dan tidak dihitung lulus: laporan menyebut jumlahnya dan memperingatkan bahwa perilakunya belum terverifikasi.
Izinkan request tulis per endpoint, hanya terhadap lingkungan yang boleh diubah atau dapat di-reset:
Gunakan --reset (atau replay.reset) untuk mengembalikan state sebelum setiap putaran, misalnya dengan me-restore dump database atau memanggil endpoint reset di lingkungan uji. Echoproof menolak me-replay request tulis tanpa reset bila noise sedang dipelajari, karena perubahan state di antara run akan ikut dianggap noise dan menyembunyikan regresi.
Diff semantik
-
JSON dibandingkan per field.
5dan5.0dianggap sama, dan urutan key diabaikan. -
Setiap perubahan diklasifikasikan:
-
Path dinormalkan:
/products/42menjadiGET /products/{id}, danitems[3].pricemenjadi$.items[*].price. Setiap perubahan dihitung sekali per request. -
UUID, ULID, dan date-time dengan bentuk yang sama dianggap noise. Tanggal saja (misalnya
2026-10-14) tetap dibandingkan.
Niat perubahan
Ada dua cara memberi tahu Echoproof perubahan apa yang diharapkan.
--expect meloloskan semua perubahan di endpoint yang disebut. Jika sebuah PR memang mengubah katalog tetapi tanpa sengaja juga merusak harga di katalog, --expect "GET /catalog" tidak akan menangkapnya.
Dengan --intent, setiap kelompok perubahan dinilai oleh Claude dan diberi verdict intended, regression, atau unclear, beserta alasan yang mengutip nilai contoh. Bahan penilaiannya meliputi niat perubahan, diff kode (opsional), persentase request yang terdampak, contoh request yang berubah beserta nilai sebelum dan sesudah, serta contoh request di endpoint yang sama yang tidak berubah sebagai pembanding. Verdict unclear dan kelompok yang tidak dinilai diperlakukan sebagai regresi (fail closed).
Penilaian niat membutuhkan API key Anthropic. Satu run melakukan satu panggilan API, dan hanya jika ada perubahan. Biaya tipikal sekitar USD 0,01 sampai 0,02 per run dengan model default.
Panggilan ke pihak ketiga
Service yang memanggil payment gateway, layanan pesan, atau API lain tidak boleh benar-benar menghubunginya saat replay. Dengan echoproof/laravel, panggilan itu direkam bersama setiap request, dan build yang dijalankan dengan ECHOPROOF_REPLAY=true menjawabnya dari rekaman serta memblokir semua panggilan lain. Kedua build menerima jawaban pihak ketiga yang identik, lalu Echoproof membandingkan apa yang dikirim setiap build:
Pada contoh ini response checkout identik; hanya nominal yang dikirim ke gateway yang berubah. Panggilan yang tidak pernah terekam dilaporkan sebagai call added dengan tingkat breaking. Kalau sebuah build melaporkan panggilan yang tidak bisa dibaca Echoproof, request itu gagal dalam check, bukan lolos tanpa verifikasi.
Bahasa apa pun: proxy keluar
Untuk service yang bukan Laravel, atau yang memanggil pihak ketiga lewat SDK dengan klien HTTP sendiri, Echoproof dapat menjadi proxy untuk panggilan keluar service:
Pasang setting proxy dan CA hanya pada service yang diuji. Echoproof sendiri mengabaikan variabel proxy dari environment. Saat replay, proxy tidak punya jalur ke tujuan asli. Klien yang mengabaikan setting proxy (Node sebelum 22.21 tanpa NODE_USE_ENV_PROXY=1, atau kode yang menetapkan proxy sendiri) tetap memanggil service asli, tetapi terlihat sebagai call removed, tidak pernah sebagai lulus; bila memungkinkan, jalankan build uji tanpa jalur jaringan ke luar. Nilai rahasia yang dipantulkan pihak ketiga (API key di URL yang dikembalikan, token di header yang dikembalikan) ikut disensor. Perekaman hanya mengatribusikan panggilan dengan tepat selama request datang satu per satu, jadi rekamlah di staging atau dari traffic hasil skrip.
Referensi perintah
Opsi umum:
Pola endpoint: POST /orders, GET /products/* (* cocok dengan satu segmen), /admin/** (** cocok dengan banyak segmen), atau * untuk semua.
Exit code: 0 lulus atau hanya perubahan yang diharapkan, 1 ada regresi, 2 error (konfigurasi, jaringan, reset gagal, atau penilaian niat gagal).
Konfigurasi
Semua pengaturan bersifat opsional. Jalankan echoproof init untuk membuat file berisi seluruh pengaturan beserta penjelasannya.
Pola ignore: nama saja (updated_at) cocok di kedalaman mana pun. Pola yang diawali $ atau mengandung titik ($.meta.trace_id, items[*].etag) dihitung dari akar body.
Variabel lingkungan:
Membaca laporan
Contoh laporan di terminal:
Format lain:
--format markdownmenghasilkan laporan yang siap dipakai sebagai komentar PR.--format jsonmenghasilkan data terstruktur, termasukfindings: satu kalimat per masalah yang siap dikembalikan ke coding agent.
Setelah perubahan ditinjau dan disetujui, jadikan hasilnya baseline baru:
Integrasi CI
Gunakan GitHub Action Echoproof. Action ini memasang binary rilis, menjalankan echoproof check, menulis laporan ke ringkasan job, dan menyediakan verdict sebagai output:
Regresi menggagalkan step dan memblokir merge. Pakai fail-on-regression: false bila hanya ingin melapor. Di sistem CI lain, pasang binary-nya dan jalankan echoproof check langsung; exit code 1 berarti regresi.
Integrasi coding agent (MCP)
Dalam rekaman ini, Claude Code (Sonnet) diminta merapikan nama kasir di service order. Sebelumnya, bug diskon sudah ditanam di file yang sama. Pemeriksaan gagal, agent menelusuri regresi itu sampai ke bug yang bukan buatannya, memperbaikinya, dan baru menyatakan tugas selesai setelah pemeriksaan lulus.
echoproof mcp menjalankan server Model Context Protocol melalui stdio, sehingga coding agent dapat memeriksa perubahan yang dibuatnya sendiri sebelum menyatakan pekerjaan selesai.
Pasang di coding agent Anda
Pasang binary echoproof lebih dulu (brew install est57/tap/echoproof atau cargo install echoproof). Setiap agent di bawah menjalankan echoproof mcp di folder proyek Anda, sehingga dapat menjangkau build lokal dan file snapshot.
Claude Code, sebagai plugin (disarankan). Plugin ini memasang server MCP dan skill verify-behavior yang memberi tahu Claude kapan dan bagaimana memeriksa perubahannya, sehingga tidak perlu instruksi tambahan di CLAUDE.md:
Dari shell: claude plugin marketplace add est57/echoproof dan claude plugin install echoproof@echoproof.
Claude Code, hanya server MCP:
Cursor (.cursor/mcp.json di proyek, atau ~/.cursor/mcp.json), Claude Desktop (claude_desktop_config.json), dan klien lain yang membaca peta mcpServers:
VS Code dengan Copilot agent mode (.vscode/mcp.json):
Codex CLI: codex mcp add echoproof -- echoproof mcp, atau di ~/.codex/config.toml:
Gemini CLI: gemini mcp add echoproof echoproof mcp, yang menulis .gemini/settings.json di proyek.
Integrasi Claude Code sudah diuji dari ujung ke ujung. Klien lain memakai MCP stdio standar yang sama tetapi belum diuji; laporan pemakaian sangat diterima. Asisten berbasis web seperti ChatGPT dan Claude.ai tidak dapat memakai Echoproof, karena berjalan di server penyedianya dan tidak dapat menjangkau build di komputer Anda.
Echoproof terdaftar di MCP Registry resmi dengan nama:
mcp-name: io.github.est57/echoproof
Tool
Alur kerja agent: mengubah kode, menjalankan build, memanggil echoproof_check dengan tugasnya sebagai intent, lalu jika hasilnya regresi, membuka contoh dengan echoproof_exchange, memperbaiki kode, dan memeriksa ulang. Server sengaja tidak menyediakan accept, karena menyetujui baseline baru tetap keputusan manusia.
Keamanan dan privasi
Data yang direkam
- Header dan field yang terdaftar di
[sanitize]disamarkan menjadi[REDACTED]sebelum ditulis ke disk. Tambahkan field yang memuat data pribadi di domain Anda, misalnya nomor telepon, email, atau nomor identitas. - Snapshot berisi data bisnis. Simpan di luar repository publik atau pastikan masuk
.gitignore.
Data yang dikirim ke Anthropic saat memakai --intent
Teks niat, diff kode (jika diberikan), nama endpoint dan field, jumlah request yang terdampak, serta contoh body request dan nilai sebelum dan sesudah, setelah disamarkan. Body contoh di atas 4.000 karakter dipotong. Tidak ada data yang dikirim jika --intent tidak dipakai.
Pengaman bawaan
- Request tulis tidak di-replay tanpa izin eksplisit per endpoint.
- Path dari snapshot divalidasi agar request dan kredensial yang disisipkan tidak dapat diarahkan ke host lain.
- Response dibatasi 32 MB.
- API key hanya dikirim melalui
https, kecuali kelocalhost. - Teks dari luar (niat, diff, traffic) tidak dapat mengubah struktur prompt penilai, dan tidak dapat merusak tabel di laporan Markdown.
Pengaman untuk coding agent (MCP)
targetdanbasehanya bolehlocalhost, kecuali host didaftarkan di[mcp] allowed_hosts. Replay membawa header darireplay.headers, sehingga agent tidak boleh dapat mengirimnya ke host lain.- Path file (
snapshot,save,code_diff_file) harus berada di dalam folder proyek. Symlink ke luar folder ditolak. - Perintah reset hanya dibaca dari
echoproof.toml, tidak pernah dari agent.
Batasan
- Request tulis membutuhkan lingkungan uji yang dapat di-reset. Tanpa itu, gunakan mode aman, yang hanya memverifikasi request baca.
- Panggilan ke pihak ketiga dijawab dari rekaman lewat echoproof/laravel (klien
HttpLaravel) atau proxy keluar (klien apa pun yang mematuhi setting proxy). Klien yang mengabaikan setting proxy dan dependency non-HTTP (SMTP, antrean, gRPC lewat socket mentah) masih dipanggil sungguhan; yang pertama terlihat sebagaicall removed. - ID antar-request: pada replay berurutan (
concurrency = 1), ID yang dibuat replay berbeda dari rekaman (order 9812 di rekaman, order 57 saat replay) dibawa ke request berikutnya untuk entitas yang sama (/orders/9812,order_id). ID data yang sudah ada saat traffic direkam tidak dapat dipetakan; dengan--base, request seperti itu dilaporkan sebagai not reproduced, bukan dihitung tidak berubah. Matikan pemetaan dengan--no-id-mappingatau[replay] map_ids = false. - Urutan request dijaga dengan replay berurutan (
concurrency = 1). Traffic besar bisa lambat, dan replay paralel hanya aman untuk endpoint tanpa state. - Perubahan yang seharusnya terjadi tetapi tidak terjadi sulit dideteksi, karena Echoproof melaporkan request yang berubah.
- Noise yang jarang muncul dapat lolos dari satu run pembelajaran. Naikkan
--noise-runsatau tambahkan polaignorebila perlu.
Pengembangan
Struktur repository
Menjalankan tes
Eval penilai niat
eval/judge berisi 26 skenario PR berlabel (54 kelompok perubahan) yang mengukur seberapa akurat penilai membedakan perubahan yang diniatkan dari regresi. Pada konfigurasi default, penilai mencatat 100% gate benar pada 78 run, tanpa false alarm. Skenario saat ini sudah tidak cukup sulit untuk membedakan konfigurasi yang lebih baik, sehingga kasus dari sistem nyata sedang ditambahkan. Daftar kasus ada di eval/judge/CASES.md.
Runner menolak berjalan sampai harness disetujui sekali dengan --approve-harness, dan meminta persetujuan ulang setiap kali kode runner, kasus, atau penilai berubah.
Lisensi
Echoproof dilisensikan di bawah salah satu dari dua lisensi berikut, sesuai pilihan Anda:
- Apache License, Version 2.0 (LICENSE-APACHE)
- MIT License (LICENSE-MIT)
Kecuali dinyatakan lain, setiap kontribusi yang Anda kirimkan untuk disertakan dalam proyek ini dilisensikan ganda dengan cara yang sama, tanpa syarat tambahan.
Source: README.md at commit 63d2485
Tools
0Version history
4- v0.4.0LatestOct 15, 2026
- v0.2.1Oct 15, 2026
- v0.1.2Oct 14, 2026
- v0.1.1Oct 14, 2026
Score
50% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
- Reached in the last 30 days25 pts
Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.
- Auth declared10 pts
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
- Tools listed15 pts
Answer tools/list without a credential, or ship a package that starts in a sandbox without one.
- DescriptionRequired15 pts
- Logo10 pts
- Documentation15 pts
- License10 pts