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.

Docs | Examples | Skills

---

Start here

Grimoire runs in two execution environments. The spell syntax is the same; the guarantees are different.

VM mode (in-agent, best-effort)

Use this when you want to run inside an agent session for prototyping and reviews. VM mode does not bundle adapters, but it can use real venue data when the agent is allowed to run tools (for example, grimoire venue ...).

Install the VM skill:

npx skills add https://github.com/franalgaba/grimoire

Or copy it manually:

SKILLS_DIR="$HOME/.config/agents/skills"
mkdir -p "$SKILLS_DIR"
cp -R skills/grimoire-vm "$SKILLS_DIR/grimoire-vm"

Copy/paste demo (agent prompts):

Create a Grimoire VM spell named MorphoYieldOptimizer and save it to spells/morpho-yield-optimizer-vm.spell.
Use a snapshot params block, ignore markets with TVL < 5,000,000, and recommend switching when the spread over the current market is > 0.5%. Include a demo snapshot with 3 Morpho USDC markets and emit candidate + recommendation/hold events. No side effects.

Run it in VM mode:

Run spells/morpho-yield-optimizer-vm.spell in the Grimoire VM with trigger manual. Use defaults and no side effects.

Want real data? Replace the params: block with live snapshots:

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

For quick protocol prototyping, use the venue CLI to fetch metadata or snapshot params: blocks for VM runs. Execution still happens inside the agent session.

Next steps: run-grimoire-vm.md, vm-quickstart.md

Deterministic runtime (CLI)

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

Suggested flow: explore in VM → record advisory in CLI simulate → replay deterministically in cast.

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>

Advisory steps (**...** and 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.

Next steps: cli-cast.md, transition-to-deterministic.md

---

Example spell

spell YieldOptimizer {

  assets: [USDC, DAI]

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

  params: {
    amount: 100000
  }

  on hourly: {
    if **gas costs justify the move** {
      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 **...** and advise
• Structured control flow (loops, conditionals, try/catch, atomic)
• State persistence and run history for deterministic execution
• Two execution environments: in-agent VM and deterministic runtime

DefiHack Multi-Track

The spells/defihack/ folder provides one coherent flow that maps to multiple tracks:

Track	Integration	Spell path
Yellow Network	yellow offchain app-session lifecycle	spells/defihack/yellow-session-track.spell
Uniswap Foundation (v4) + LI.FI	unified liquidity flow with shared skill	spells/defihack/liquidity-mesh-track.spell
Prompt-first E2E	VM creation prompts + deterministic CLI validation	spells/defihack/README.md

Primary end-to-end runbook:

cd packages/cli
bun run --filter @grimoirelabs/cli dev compile-all ../../spells/defihack --json
bun run --filter @grimoirelabs/cli dev simulate ../../spells/defihack/yellow-session-track.spell --no-state --json
bun run --filter @grimoirelabs/cli dev simulate ../../spells/defihack/liquidity-mesh-track.spell --no-state --json
bun run --filter @grimoirelabs/cli dev cast ../../spells/defihack/yellow-session-track.spell --dry-run --no-state --json
bun run --filter @grimoirelabs/cli dev cast ../../spells/defihack/liquidity-mesh-track.spell --dry-run --no-state --json

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

Documentation

• Start here: docs/README.md
• Spell syntax: docs/reference/spell-syntax.md
• CLI: docs/reference/cli.md
• VM spec: docs/reference/grimoire-vm.md

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
• Update the VM skill: re-install with npx skills add https://github.com/franalgaba/grimoire (or copy skills/grimoire-vm into your agent skills directory again)

Development

bun install
bun run validate

For onchain tests and advanced workflows, see docs/how-to/run-tests.md.

License

MIT