@kleros/agentkit

A CLI and toolkit for AI agents and humans to interact with the Kleros decentralized arbitration protocol.

Built with incur — the CLI framework for agents and humans — and viem for on-chain interactions.

Status

0.1.1 — first public release. (0.1.0 was published then found broken on fresh installs due to a transitive dependency resolution issue and is deprecated on the registry — use >=0.1.1.) Read-only command surface: courts, disputes, evidence, dispute/court policy, arbitrable classification, composite dispute brief, and juror stake/leaderboard queries across Ethereum, Gnosis, and Arbitrum Sepolia (devnet). Pre-1.0 — the API may change between minor versions. Write operations (staking, voting, dispute creation, appeals) are not yet available — see Roadmap.

A programmatic import/require API is also exported from this package (see exports in package.json), but it is undocumented and unstable pre-1.0 — the CLI/MCP/HTTP surface documented here is the supported interface, with no semver stability guarantees on internals.

Quickstart

No installation required — run directly with npx:

npx -y @kleros/agentkit court list --chain ethereum
npx -y @kleros/agentkit dispute get 797 --chain gnosis --format json

For repeated use, install globally instead:

npm i -g @kleros/agentkit
kleros court list --chain ethereum

What is this?

Kleros is a decentralized dispute resolution protocol deployed on Arbitrum, Gnosis, and Ethereum. @kleros/agentkit gives agents and developers a single, token-efficient interface to:

• Browse courts, disputes, and juror activity
• Resolve court and dispute policy (what jurors are asked to apply when ruling)
• Walk evidence submissions, including IPFS-hosted attachments
• Classify arbitrable contracts and pull a composite dispute brief in one call
• Rank jurors by staked PNK

Every command works from the terminal, as an MCP server, or as an HTTP API — with zero extra configuration. Write operations (staking, voting, creating disputes, submitting evidence, interacting with Curate/escrow/Reality.eth, ERC-8183 evaluators) are planned but not yet shipped — see Roadmap.

Features

• Agent-first: TOON output by default (40% fewer tokens than JSON), call-to-actions, token pagination, --llms manifest
• Human-friendly: readable table output, interactive fallbacks, shell completions
• MCP built-in: kleros --mcp starts an MCP stdio server. cli.fetch exposes an HTTP MCP endpoint at /mcp
• Multi-chain reads: Arbitrum Sepolia devnet (v2), Gnosis (v1), Ethereum (v1) with automatic version routing

Architecture

+--------------------------------------------------+
|            Kleros Skills (SKILL.md)               |  Agent-facing docs, examples,
|  Wraps CLI with context, explains when and why     |  progressive disclosure
|  to use each command                               |
+------------+--------------+----------------------+
|  CLI       |  MCP Server  |  HTTP API            |  incur surfaces
|  kleros .. |  --mcp       |  cli.fetch           |  TOON output, CTAs,
|            |              |                      |  token pagination
+------------+--------------+----------------------+
|              Middleware (incur)                    |  Chain resolution
|  cli.use() -- chain resolution (read-only;         |  (no wallet middleware
|  no wallet middleware shipped yet)                 |  shipped yet)
+--------------------------------------------------+
|            Core Functions (TypeScript)             |  Pure business logic,
|  disputes, courts, evidence, policy, arbitrable    |  read-only,
|                                                     |  framework-agnostic
+--------------------------------------------------+
|  viem (on-chain reads) + subgraph (The Graph) +    |  Multi-chain
|  IPFS (cdn.kleros.link)                            |
+--------------------------------------------------+
|           Kleros Contracts (read paths)            |  Arbitrum Sepolia (v2),
|  KlerosCore/KlerosLiquid, SortitionModule,         |  Gnosis (v1),
|  DisputeKitClassic, EvidenceModule                 |  Ethereum (v1)
+--------------------------------------------------+

Write-path components (wallet providers, staking, voting, dispute creation, Curate/escrow/Reality.eth integration) are planned but not part of this diagram — see Roadmap.

Agent Usage

In-Repo Skill

AgentKit ships a Claude Code skill at skills/agentkit/SKILL.md. Loading this skill gives agents the full command surface, peer-MCP composition guidance (markitdown-mcp for binary evidence), policy intersection rules, and common gotchas — all from the repo itself without network fetches.

To install in your project: copy or reference skills/agentkit/SKILL.md in your Claude Code configuration.

MCP Server (Claude Code, Cursor, Amp)

Register kleros as an MCP tool server so AI agents can call dispute queries directly. No installation required — the one-liner uses npx:

claude mcp add kleros -- npx -y @kleros/agentkit --mcp

Already installed the binary globally? Register it directly instead:

npx -y @kleros/agentkit mcp add   # registers for Claude Code and Cursor by default
kleros --mcp                       # or start manually (stdio transport)

Chain configuration: MCP clients cannot switch chain per-call — set it at server-start time:

KLEROS_CHAIN=gnosis npx -y @kleros/agentkit --mcp
# Or persist: kleros config set chain gnosis

Tool Discovery (--llms)

kleros --llms                    # compact table -- best for agents
kleros --llms-full               # full docs with args, options, output schemas
kleros --llms --format json      # JSON for structured parsing

Example MCP Tool Call (JSON-RPC)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "dispute_list",
    "arguments": { "court": "1", "limit": 10 }
  }
}

Tool names follow the pattern group_command (e.g., dispute_list, court_get, juror_info).

Context-Aware Suggestions (CTAs)

Every response includes a cta block with the next logical command:

{
  "data": { "id": "42", "status": "Vote", "court": "1" },
  "cta": {
    "description": "Voting period -- review evidence and court policy",
    "commands": [
      { "command": "evidence list", "description": "Review evidence before voting" },
      { "command": "court policy", "description": "Read court policy for this ruling" }
    ]
  }
}

For full MCP configuration options, see the incur documentation.

Configuration

Persist defaults with config set to avoid passing flags on every command. Configuration is stored in ~/.kleros/config.json.

Supported keys

| Key | Type | Values | Description | |-----|------|--------|-------------| | chain | string | ethereum, gnosis, arbitrum-sepolia | Default chain for all commands. Overridden by --chain flag per-command. |

Commands

kleros config set chain gnosis    # Persist default chain
kleros config get chain           # Read current value
kleros config unset chain         # Remove persisted value (revert to flag/env resolution)
kleros config list                # Show all persisted keys

Unknown keys are rejected with INVALID_CONFIG_KEY — only the keys listed above are supported.

Environment Variables

| Variable | Purpose | |----------|---------| | KLEROS_RPC_URL_ETHEREUM | Override the default public Ethereum RPC. Required for Reality handler integration tests on Ethereum (disputes 1650, 1651) — must be an Infura or Alchemy endpoint (public RPCs do not support historical eth_getLogs). Also required for pnpm update-deployment-blocks. | | KLEROS_RPC_URL_GNOSIS | Override the default public Gnosis RPC (e.g. https://rpc.gnosischain.com). A public Gnosis RPC is accepted by default since Gnosis archives eth_getLogs broadly. | | KLEROS_RPC_URL_SEPOLIA | Override the default public Ethereum Sepolia RPC (unrelated to the v2 Arbitrum Sepolia devnet — see KLEROS_RPC_URL_ARBITRUM_SEPOLIA below). Required for Reality handler integration tests on Sepolia (disputes 111, 112) — must be an Infura or Alchemy endpoint. Also required for pnpm update-deployment-blocks. | | KLEROS_RPC_URL_ARBITRUM_SEPOLIA | Override the default public Arbitrum Sepolia RPC — this is the v2 devnet chain described throughout this README as "Arbitrum Sepolia (devnet)". | | KLEROS_INTEGRATION_TESTS | Set to true to enable integration tests that hit live subgraph and IPFS endpoints. | | KLEROS_CHAIN | Default chain for the MCP server. Use kleros config set chain <id> for persistent config. |

Default RPCs are free public endpoints — fine for light use, but may rate-limit under real traffic. Set the KLEROS_RPC_URL_* overrides above to a dedicated provider (Infura, Alchemy, or any RPC you trust) for reliable production use, especially right after this package's public launch.

Feedback

kleros report-issue create writes a local .md report by default. kleros report-issue create --submit posts it as a GitHub issue — by default to the public kleros/kleros-skills repository (requires $GITHUB_TOKEN). This repository (kleros/agentkit) stays private for now and would reject non-collaborator issue submissions, which is why report-issue targets kleros/kleros-skills instead.

Development

Setup

Requires Node.js >=22.

pnpm install
pnpm build
pnpm test

Testing the MCP server against live source

The installed kleros binary is dist/cli.js, so code changes need a rebuild before the MCP server sees them. Three loops, fastest first:

1. Raw stdio (no client, no rebuild) — iterate on tools and handshake logic:

pnpm dev -- --mcp                    # runs tsx src/cli.ts --mcp
# pipe JSON-RPC frames in to exercise tools/list, tools/call, etc.

2. tsx-shimmed registration (live source, restart per change) — iterate from inside Claude Code, Cursor, or any MCP client without rebuilding:

# Edit ~/.claude.json -> mcpServers.kleros:
#   "command": "tsx",
#   "args": ["/absolute/path/to/agentkit/src/cli.ts", "--mcp"]

Restart the MCP client after each code change. No pnpm build needed — tsx reads src/*.ts directly.

3. Globally linked binary (closest to production) — test the real install flow end-to-end:

pnpm build
pnpm link --global                   # symlinks `kleros` -> this repo's dist/cli.js
which kleros                         # verify it points at your pnpm global bin
kleros mcp add                       # registers `kleros --mcp` in ~/.claude.json

Iteration loop: pnpm build after each change, then restart the MCP client.

Teardown:

pnpm unlink --global @kleros/agentkit
# then re-run `kleros mcp add` against the published version, or edit ~/.claude.json manually

Gotchas

• Tool list is cached at session start — adding a new command requires both rebuild AND client restart before it appears in tools/list.
• Chain is pinned at server-start — MCP clients start the server once per session. To switch chains, pass chain inside tool arguments, or set KLEROS_CHAIN and restart the client.
• Empty dist/cli.js after a pull — the kleros shebang will fail silently. Run pnpm build first.
• Multiple local checkouts — pnpm link --global only tracks the most-recently-linked one.

Release Process

Releases are gated for security: only repository admins can publish, and release tags must be GPG-signed by a trusted key.

1. Bump version in package.json on master (PR + merge as normal).
2. As a repo admin, create a signed annotated tag:

   git tag -s vX.Y.Z -m "Release vX.Y.Z"

   (requires a GPG signing key configured via git config user.signingkey, registered with your GitHub account).
3. Push the tag:

   git push origin vX.Y.Z

.github/workflows/release.yml's publish job enforces this at two levels before any build/install/publish step runs:

• Admin gate — the actor who pushed the tag must currently hold admin permission on this repo (checked live via the GitHub API; fails closed if the check itself errors).
• Signature gate — the tag must be annotated, GPG-signed, and the signature must verify against a key listed in .github/release-signers.asc.

A repository ruleset (release-tags-admin-only, Settings -> Rules -> Rulesets) independently blocks non-admins from creating, updating, or deleting v* tags at the git level — defense-in-depth alongside the workflow-level checks above.

Adding a new trusted signer: see .github/release-signers.README.md.

Roadmap

Planned, not yet shipped:

• Write operations — staking PNK, casting votes, creating disputes, submitting evidence, appealing rulings (requires wallet middleware)
• Wallet-agnostic signing — plug in any EVM wallet (raw private key, Coinbase CDP, Privy, or any viem-compatible signer)
• Curate, escrow, and Reality.eth integration — registry entries, escrow payouts, oracle question resolution
• ERC-8183 evaluator registration and invocation
• v2 beta support — Arbitrum One reads, dispute policy via DisputeTemplate/@kleros/sdk, then v2 dispute creation (Arbitrum Sepolia testnet is not planned — only Arbitrum One beta and the existing devnet)

Not yet scheduled to a specific release. Tracked internally; file a feedback report if there's a specific capability you need.