SKILL.md that drops into agent runtimes such as Claude Code, Cursor, and Codex-style loops, covering every command, flag, and what to do on each error code, so an agent can drive gasless, self-custodial swaps unattended.
Set up with one prompt
The fastest start is to let your coding agent do the setup. Paste this into Claude Code, Cursor, or any assistant that can run commands:geodesics CLI, and guides you through the credentials and first swap end to end, pausing only when it needs a value from you, such as the signer key from the Virtuals dashboard. The manual equivalent is the Quickstart.
The packaged skill
geodesics init asks which AI tools you use and installs the skill in the right place and format for each:
The skill only needs installing once per machine, or once per project for project-level installs. When
geodesics init finds the skill already installed, for example when you re-run it to configure another agent’s credentials, the install step defaults to skip; pick a location anyway to overwrite an outdated copy with the packaged version.
The skill gives the agent the full playbook: every command and flag, the one-time onboarding steps, and an error table with the exact action to take on each code, so a swap that hits NEEDS_DELEGATION or NEEDS_SOL_TOPUP recovers without a human in the loop.
Setup is a one-time user action:
geodesics init is interactive, so a headless agent cannot
run it. Agents read the credentials as environment variables; if a command returns an auth
error, the fix is for the owner to run geodesics init once in their own terminal.Machine-readable output
All commands support--json: a single JSON object on stdout, no progress lines. A --json swap result may carry a warnings array of non-fatal notices the agent should read and act on, for example a chain-onboarding step to run before swapping back out. Interactive prompts never appear in --json mode; the manual alternative is reported as a warning instead.
Errors and what the agent should do
Exit codes:
0 is success; 1 is an error, with the reason in JSON error.code; 2 means the swap ended failed or refunded. Refunds return the input to the origin wallet.