franalgaba__grimoire/README.md

Grimoire

"Verba Volant, Scripta Manent."

Grimoire is a language for agents to express financial intent with readable syntax and deterministic execution. Spells compile to an intermediate representation (IR) and run through protocol adapters, so you can swap venues by changing aliases and configuration instead of rewriting strategy logic.

Examples | Skills

---

Start here

Grimoire has one runtime semantics: preview first, then commit for irreversible actions. The same behavior applies across CLI and library entry points.

For a single onboarding flow for both users and agents, start with:

• docs/tutorials/quickstart-users-and-agents.md

CLI entry point (grimoire)

Use this for reproducible simulation and onchain execution with adapters and state persistence.

npm i -g @grimoirelabs/cli

grimoire simulate spells/compute-only.spell --chain 1

grimoire cast spells/uniswap-swap-execute.spell \
  --dry-run \
  --key-env PRIVATE_KEY \
  --rpc-url <rpc>

When you are ready to execute live:

grimoire cast spells/uniswap-swap-execute.spell --key-env PRIVATE_KEY --rpc-url <rpc>

Want live snapshot params for strategy inputs?

grimoire venue morpho-blue vaults --chain 8453 --asset USDC --min-tvl 5000000 --format spell

Advisory steps (advise) call Pi when a model is configured (spell model, CLI model/provider, or Pi defaults). If no model is available, the runtime uses the spell’s fallback. Record advisory outputs with simulate (or cast --dry-run), then replay deterministically with --advisory-replay for live execution.

Advisory docs:

• docs/how-to/use-advisory-decisions.md
• docs/explanation/advisory-decision-flow.md
• docs/reference/spell-syntax.md#advisory-syntax

See grimoire --help for all CLI commands.

Library entry point (@grimoirelabs/core)

Use this when embedding Grimoire into an app/agent process. The library shares the same compiler/interpreter semantics and preview/commit model as the CLI.

See docs/reference/compiler-runtime.md for compile, preview, commit, execute, and session APIs.

Agent-assisted entry point (skills)

Use skills in skills/ so agents can work immediately with Grimoire:

• install: npx skills add https://github.com/franalgaba/grimoire
• skills/grimoire/ for install, CLI usage, syntax starter, and runbook
• venue skills for snapshot params (skills/grimoire-aave/, skills/grimoire-uniswap/, skills/grimoire-morpho-blue/, skills/grimoire-hyperliquid/)

For Claude Code, run the same install command in the Claude Code terminal and start a new session to load the skills.

---

Example spell

spell YieldOptimizer {

  assets: [USDC, DAI]

  advisors: {
    risk: {
      model: "anthropic:haiku"
    }
  }

  venues: {
    aave_v3: @aave_v3
    morpho_blue: @morpho_blue
  }

  params: {
    amount: 100000
  }

  on hourly: {
    decision = advise risk: "Do gas costs justify rebalancing now?" {
      output: {
        type: boolean
      }
      timeout: 10
      fallback: true
    }

    if decision {
      amount_to_move = to_number(balance(USDC)) * 50%
      aave_v3.withdraw(USDC, amount_to_move)
      morpho_blue.lend(USDC, amount_to_move)
    }
  }
}

Features

• Human-readable DSL with brace-delimited syntax
• Explicit constraints and limits via with and limits
• Adapter-based venues (SDKs live in @grimoirelabs/venues)
• Onchain + offchain actions (EVM + Hyperliquid + Yellow + LI.FI)
• Judgment boundary with explicit advise blocks
• Structured control flow (loops, conditionals, try/catch, atomic)
• State persistence and run history for deterministic execution
• Unified runtime semantics across CLI and programmatic embedding

ENS profile hydration is available on CLI runs via --ens-name and --ens-rpc-url.

Documentation

Documentation follows Diataxis in docs/:

• docs/tutorials/
• docs/how-to/
• docs/reference/
• docs/explanation/

Start at docs/README.md for navigation.

Updating

• Update the CLI: npm i -g @grimoirelabs/cli@latest
• Use npx for latest without install: npx -y @grimoirelabs/cli@latest <command>
• Update packages in your project: npm i @grimoirelabs/core@latest @grimoirelabs/venues@latest

Development

bun install
bun run validate

For onchain tests and advanced workflows, see docs/.

License

MIT