Ctrlk
WebsiteGithub
x-twitter
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Agentic Setup for Circles

Build Circles dApps and miniapps using AI coding assistants grounded in always-fresh, version-aware Circles documentation.

This page is a practical guide for developers (and curious non-developers) who want to vibe-code on Circles using an AI assistant like Claude, Cursor, Windsurf, or VS Code Copilot. By wiring Context7 into your editor, your AI agent pulls live snippets from the official Circles docs and SDK source, so it stops hallucinating outdated APIs and starts writing code that actually compiles.

What is an agentic workflow?

An agentic workflow is one where you describe what you want in plain language and an AI agent does the work — reading docs, writing code, running it, fixing its own errors, and iterating. The catch: large language models are trained on data that's months or years old. Without a grounding layer, an agent confidently writes code that imports packages that don't exist or calls methods that were renamed in v2.

Context7 fixes this. It's an open Model Context Protocol (MCP) server from Upstash that injects up-to-date, version-specific documentation directly into your AI assistant's context window the moment you ask about a library. The Circles team publishes two libraries on Context7:

  • aboutcircles/circles-docs — the full developer documentation, including protocol concepts, configuration, and end-to-end examples.

  • aboutcircles/sdk — the TypeScript SDK reference, including every package (@aboutcircles/sdk, sdk-core, sdk-rpc, sdk-runner, sdk-pathfinder, sdk-profiles, sdk-transfers) with code examples for almost every method.

Together, they give your agent everything it needs to build production-grade Circles apps without you having to copy-paste from docs.

Why Context7 + Circles

Without Context7, ask Claude to "trust an address with the Circles SDK" and you'll get pre-2024 examples using @circles-sdk/sdk and ethers v6. With Context7, the same prompt produces the current @aboutcircles/sdk flow on Gnosis Chain (chainId 100) with viem, a ContractRunner, and the right circlesConfig[100]. The difference is hours of debugging vs. shipping.

The Circles SDK has a layered architecture — Sdk for high-level avatar work, CirclesRpc for read-only queries, Core for raw contract calls, SafeContractRunner / SafeBrowserRunner for Safe-based transactions, and a Pathfinder for multi-hop trust transfers. An AI assistant with the right docs in context can navigate all of these for you.

Prerequisites

Before you start, make sure you have:

  • Node.js 18+ installed (node --version)

  • An MCP-compatible AI assistant: Claude Desktop, Claude Code, Cursor, Windsurf, or VS Code with an MCP extension

Optional (but recommended): A free Context7 API key from context7.com/dashboard for higher rate limits

Step 1: Install Context7 in your AI assistant

Pick the section that matches your editor. The configuration is essentially the same JSON across all clients — Context7 runs as a local MCP server via npx.

Cursor

  • Open Cursor → Settings → Cursor Settings → MCP → Add new global MCP server.

  • Or edit the config file directly:

    • macOS / Linux: ~/.cursor/mcp.json

    • Windows: %USERPROFILE%\.cursor\mcp.json

  1. Add the following:

  1. Restart Cursor.

Claude Desktop

  • Open your config file:

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

    • Windows: %APPDATA%\Claude\claude_desktop_config.json

  • Add the same mcpServers block as above.

  1. Quit and reopen Claude Desktop.

Claude Code

Run a single command in your terminal:

The --scope user flag registers Context7 globally so it's available in every Claude Code session. Verify with /mcp inside a session — you should see context7 with a connected status.

VS Code

Add Context7 under mcp.servers in your settings.json:

Then reload the window (Ctrl/Cmd+Shift+P → "Developer: Reload Window").

Verify it's working

In any of the above clients, send a prompt like:

Using the latest @aboutcircles/sdk, write me a TypeScript snippet that registers a new human avatar on Gnosis Chain. use context7

If Context7 is wired up correctly, the response will include the current packages (@aboutcircles/sdk, @aboutcircles/sdk-core, @aboutcircles/sdk-runner, viem) and use circlesConfig[100] and not the deprecated @circles-sdk/sdk packages.

Step 2: Connect the Circles libraries

Context7 auto-discovers libraries when you reference them in a prompt, but for the most reliable results, point your agent directly at the Circles entries by name or ID.

Library IDs

Library
Context7 ID
What's inside

Circles documentation

aboutcircles/circles-docs

Protocol overview, getting-started guides, every SDK method with runnable TypeScript examples, RPC endpoints, REST API for profiles

Circles SDK v2

aboutcircles/sdk

Per-package API reference: Sdk, HumanAvatar, OrganisationAvatar, BaseGroupAvatar, CirclesRpc, Core, SafeContractRunner, Pathfinder, Profiles, utility helpers

Pin a library in a prompt

You can reference either entry with the slash syntax to make sure the agent looks at the right one:

Or, for documentation-level questions like configuration and protocol concepts:

Step 3: Add a project rule so you don't have to remember

Typing use context7 every time gets old fast. Instead, add a one-time rule so your assistant automatically fetches Circles docs whenever it sees a relevant import or keyword.

For Cursor — .cursorrules

Create a .cursorrules file at the root of your project:

For Claude Code — CLAUDE.md

Drop the same content into a CLAUDE.md at your project root. Claude Code reads it automatically.

Step 4: Vibe-code your first Circles Mini App

A Circles miniapp is a lightweight, focused dApp built with the Circles SDK, usually a single-page web app that reads/writes the Circles graph, mints or transfers CRC, manages a group, or exposes a small piece of functionality that complements Gnosis Wallet.

Here's a starter prompt you can give any Context7-equipped agent. It assumes the rules from Step 3 are already in place:

Build a Vite + React + TypeScript miniapp that:

  1. Connects a Safe via SafeBrowserRunner from @aboutcircles/sdk-runner

  2. Shows the connected avatar's profile, total CRC balance, and a paginated trust list

  3. Has a "Mint" button that calls avatar.personalToken.mint() only when getMintableAmount() returns > 0

  4. Has a "Send" form that uses avatar.transfer.advanced(recipient, amount, { useWrappedBalances: true }) and shows the pathfinder route before submitting

  5. Subscribes to avatar.events and shows a live feed of incoming CrcV2_TransferSingle events

Use Tailwind for styling. Keep state local with React hooks. Don't add a backend.

The agent will fetch the relevant SDK pages from Context7, scaffold the project, and write the code. You then iterate the same way: "the trust list pagination breaks at page 2", "wrap the mint button in a loading state", "add a copy-address button". Each follow-up triggers another targeted Context7 lookup.

Use Mini Apps SDK for building Embedded Mini Apps.

Querying the docs without an editor

If you're building a fully autonomous agent (no editor, no MCP), the Circles docs site itself ships an agent-friendly endpoint. Send an HTTP GET with an ask query parameter:

The response is a structured answer plus relevant excerpts and source links from the documentation. This is useful for:

  • Server-side agents that need to look up Circles concepts on demand

  • CI pipelines that validate generated code against current API shapes

  • Backfill workflows where you want to enrich code comments with doc links

Use it alongside Context7 when you need a quick natural-language answer rather than a code snippet.

Bonus

You can also checkout this Agentic first MiniApps branch for builiding your own applications

LogoGitHub - aboutcircles/CirclesMiniapps at feature/autonomous-agent-build-instructionsGitHub

Troubleshooting

The agent still suggests @circles-sdk/* packages. The deprecation note is on the docs but the agent's pre-training data is loud. Strengthen your project rule (Step 3) with an explicit "never use @circles-sdk/*" line, and prefix one-off prompts with use context7.

use context7 does nothing. Check that the MCP server is actually running: in Claude Code run /mcp; in Cursor open the MCP panel; in Claude Desktop check the gear icon. The most common causes are a JSON syntax error in the config file, missing Node.js in PATH, or forgetting to restart the editor.

Rate limits. Without an API key, Context7 is generous but capped. Grab a free key from context7.com/dashboard and add it under the env block in your MCP config — no other changes needed.

The generated code uses ethers instead of viem. Older Circles SDK examples used ethers. The current @aboutcircles/sdk uses viem. Either pin viem explicitly in your prompt or add it to the project rule.

Pathfinder returns maxFlow: 0. Either there's no trust path between sender and recipient, or both balances need wrapping. Try passing useWrappedBalances: true and inspect rpc.pathfinder.findMaxFlow first to confirm any liquid path exists.

Happy building. The trust economy is yours to extend.

PreviousContribute Mini Apps

Last updated

Was this helpful?