Starknet Agentic

Infrastructure for the Starknet agent economy: contracts, runtimes, and skills to run self-custodial AI agents with on-chain identity, policy-enforced execution, and composable tool access.

Why This Exists

Most agent stacks treat wallets as add-ons. starknet-agentic treats wallets, identity, and execution policy as first-class system boundaries.

This repo gives you:

• account-level control rails (session keys, spending policy, revoke paths)
• ERC-8004 identity, reputation, and validation registries on Starknet
• MCP and A2A integration packages for agent runtimes
• reusable skills and end-to-end examples

Fastest Path

If you just want Starknet agent capabilities now:

npx create-starknet-agent@latest

Sanity check (npm availability):

npm view create-starknet-agent version

The scaffolder detects your environment (OpenClaw/MoltBook, Claude Code, Cursor, or standalone) and wires Starknet integration automatically.

Install & Use

Use the path that matches your runtime:

# Full project scaffold
npx create-starknet-agent@latest

# Codex (built-in installer, cairo-auditor)
CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
python3 "$CODEX_HOME/skills/.system/skill-installer/scripts/install-skill-from-github.py" \
  --repo keep-starknet-strange/starknet-agentic \
  --path skills/cairo-auditor \
  --ref main
# Restart Codex, then run /skills and invoke cairo-auditor

# Codex (frozen install)
# Replace <commit-sha> with the exact immutable revision you want to pin.
CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
python3 "$CODEX_HOME/skills/.system/skill-installer/scripts/install-skill-from-github.py" \
  --repo keep-starknet-strange/starknet-agentic \
  --path skills/cairo-auditor \
  --ref <commit-sha>

# Claude Code marketplace
/plugin marketplace add keep-starknet-strange/starknet-agentic
/plugin install starknet-agentic-skills@starknet-agentic-skills --scope user
/reload-plugins
/plugin menu
/starknet-agentic-skills:cairo-auditor

# Individual skill install via Agent Skills CLI
npx skills add keep-starknet-strange/starknet-agentic/skills/cairo-auditor

For deterministic install/usage guidance, see:

• skills/QUICKSTART_2MIN.md
• skills/TROUBLESHOOTING.md
• docs/CLAUDE_MARKETPLACE_SUBMISSION.md

For the full skill catalog and Cairo migration notes, see skills/README.md and docs/CAIRO_SKILLS_MIGRATION.md.

Flagship Skills

System Requirements

• CLI users (npx create-starknet-agent@latest): Node.js >=18.0.0
• Contributors from source (this monorepo):
  • Node.js >=20.9.0
  • pnpm >=10.28.2 (workspace package manager)
  • Scarb >=2.14.0 + Starknet Foundry (snforge) >=0.54.1 (for Cairo builds/tests)

Choose Your Path

Architecture

flowchart TB
  A["Agent Runtime<br/>(OpenClaw, Claude Code, custom app)"] --> B["MCP / A2A Layer<br/>starknet-mcp-server, starknet-a2a, skills"]
  B --> C["Signer Boundary<br/>direct (dev) or proxy (prod)"]
  C --> D["Starknet Contracts"]
  D --> D1["Agent-account stack<br/>owner controls + spending policy enforcement"]
  D --> D2["ERC-8004 Registries<br/>Identity, Reputation, Validation"]
  D --> D3["Session-account primitives<br/>session-key account modules"]

No-Backend Trust Model (Recommended Launch Profile)

Default launch profile is self-custodial and no-backend:

• users run agent runtime locally or on their own infra
• transaction policy is enforced on-chain by account contracts
• no central signer or shared custody by this project

For production environments, use MCP proxy signer mode rather than raw in-process private keys.

Core Components

Contracts

Packages

Skills

Skill packs live in skills/. Browse full catalog and install flows in skills/README.md.
Cairo migration notes and legacy mapping live in docs/CAIRO_SKILLS_MIGRATION.md.

Install one skill:

npx skills add keep-starknet-strange/starknet-agentic/skills/starknet-wallet

Standards and Interop

Parity and Starknet-specific behavior for ERC-8004 is documented in docs/ERC8004-PARITY.md.

Quickstart From Source (Contributors)

1) Install

pnpm install

2) Build and test JS/TS workspace (packages, examples, website)

# full workspace
pnpm build
pnpm test

# packages only (faster path when you do not need example/website checks)
pnpm -r --filter "./packages/*" build
pnpm -r --filter "./packages/*" test

3) Run Cairo checks

failed=0
for dir in contracts/erc8004-cairo contracts/huginn-registry contracts/agent-account contracts/session-account; do
  if ! (cd "$dir" && scarb build && snforge test); then
    echo "Cairo checks failed in $dir"
    failed=1
    break
  fi
done
[ "$failed" -eq 0 ]

4) Run a minimal E2E demo

Before running, configure the required environment in:
examples/hello-agent/README.md

# from repo root (after configuring examples/hello-agent/.env)
pnpm demo:hello-agent

Example Gallery

Security and Release Integrity

• read security policy: SECURITY.md
• hardened signer setup: use proxy signer mode in packages/starknet-mcp-server
• GitHub Actions quality gates: ci.yml, codeql.yml, dependency-review.yml
• publish pipeline uses provenance + attestations: publish.yml

Release artifact verification (recommended):

gh attestation verify <artifact-file> --repo keep-starknet-strange/starknet-agentic

Repository Layout

starknet-agentic/
├── .agents/          # Codex discovery entrypoints (symlinks to skills/*)
├── contracts/        # Cairo contracts (account, ERC-8004, session-account)
├── packages/         # MCP/A2A/CLI and supporting libraries
├── skills/           # Agent skill packs
├── examples/         # End-to-end demos and reference flows
├── docs/             # Specs, roadmap, troubleshooting, launch material
└── website/          # Documentation website

Documentation

• getting started: docs/GETTING_STARTED.md
• roadmap: docs/ROADMAP.md
• specification: docs/SPECIFICATION.md
• troubleshooting: docs/TROUBLESHOOTING.md
• good first tasks: docs/GOOD_FIRST_ISSUES.md

Contributing

See CONTRIBUTING.md.

License

MIT (LICENSE)