{"id":44054256,"url":"https://github.com/franalgaba/grimoire","last_synced_at":"2026-04-06T16:01:01.833Z","repository":{"id":336271545,"uuid":"1145100773","full_name":"franalgaba/grimoire","owner":"franalgaba","description":"Grimoire is a language for agents to express financial intent with readable syntax and deterministic execution.","archived":false,"fork":false,"pushed_at":"2026-03-31T11:11:33.000Z","size":1251,"stargazers_count":3,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T01:09:43.531Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://grimoirelabs.xyz","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/franalgaba.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-29T12:29:48.000Z","updated_at":"2026-04-01T10:24:58.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/franalgaba/grimoire","commit_stats":null,"previous_names":["franalgaba/grimoire"],"tags_count":99,"template":false,"template_full_name":null,"purl":"pkg:github/franalgaba/grimoire","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/franalgaba%2Fgrimoire","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/franalgaba%2Fgrimoire/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/franalgaba%2Fgrimoire/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/franalgaba%2Fgrimoire/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/franalgaba","download_url":"https://codeload.github.com/franalgaba/grimoire/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/franalgaba%2Fgrimoire/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31479006,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-06T14:34:32.243Z","status":"ssl_error","status_checked_at":"2026-04-06T14:34:31.723Z","response_time":112,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-08T00:04:20.215Z","updated_at":"2026-04-06T16:01:01.814Z","avatar_url":"https://github.com/franalgaba.png","language":"TypeScript","funding_links":[],"categories":["Skills Catalog"],"sub_categories":["Workflow (110)"],"readme":"# Grimoire\n\n\u003cp align=\"center\"\u003e\u003cem\u003e\"Verba Volant, Scripta Manent.\"\u003c/em\u003e\u003c/p\u003e\n\n[![CI](https://github.com/franalgaba/grimoire/actions/workflows/ci.yml/badge.svg)](https://github.com/your-org/grimoire/actions/workflows/ci.yml)\n\nGrimoire 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.\n\n[Examples](./spells) | [Skills](./skills)\n\n---\n\n## Start here\n\nGrimoire has one runtime semantics: preview first, then commit for irreversible actions. The same behavior applies across CLI and library entry points.\n\nFor a single onboarding flow for both users and agents, start with:\n\n- `docs/tutorials/quickstart-users-and-agents.md`\n\n### CLI entry point (`grimoire`)\n\nUse this for reproducible simulation and onchain execution with adapters and state persistence.\n\n```bash\nnpm i -g @grimoirelabs/cli\n\ngrimoire setup\n\ngrimoire simulate spells/compute-only.spell --chain 1\n\ngrimoire cast spells/uniswap-swap-execute.spell \\\n  --dry-run \\\n  --key-env PRIVATE_KEY \\\n  --rpc-url \u003crpc\u003e\n```\n\n`grimoire setup` notes:\n\n- setup is always execute-mode onboarding\n- guided mode prompts for required values (chain, RPC, wallet source, doctor checks)\n- blank RPC input falls back to public chain RPC\n- setup runs a smoke preview and `venue doctor` by default\n- when password is entered interactively, setup writes `.grimoire/setup.env` (can disable with `--no-save-password-env`)\n- CLI auto-loads nearest `.grimoire/setup.env` on startup and does not override already-set env vars\n- set `GRIMOIRE_SETUP_ENV_FILE` to point to an explicit env file when running outside the project tree\n- `.grimoire/setup.env` contains plaintext secrets; keep it local-only and rotate/delete when not needed\n\n`simulate` also supports `--rpc-url \u003crpc\u003e` with resolution order:\n`--rpc-url` -\u003e `RPC_URL_\u003cchainId\u003e` -\u003e `RPC_URL`.\n\nWhen you are ready to execute live:\n\n```bash\ngrimoire cast spells/uniswap-swap-execute.spell --key-env PRIVATE_KEY --rpc-url \u003crpc\u003e\n```\n\nWant live snapshot params for strategy inputs?\n\n```bash\ngrimoire venue morpho-blue vaults --chain 8453 --asset USDC --min-tvl 5000000 --format spell\ngrimoire venue pendle chains\n```\n\nBefore running venue actions in a new environment, validate adapter/env/RPC readiness:\n\n```bash\ngrimoire venue doctor --chain 1 --adapter uniswap --rpc-url \u003crpc\u003e --json\n```\n\nIf this command errors with `Unknown venue adapter \"doctor\"`, your installed CLI is outdated.\nUse one of:\n\n- `npm i -g @grimoirelabs/cli@latest`\n- `npx -y @grimoirelabs/cli@latest venue doctor --chain 1 --adapter uniswap --rpc-url \u003crpc\u003e --json`\n- `bun run packages/cli/src/index.ts venue doctor --chain 1 --adapter uniswap --rpc-url \u003crpc\u003e --json`\n\nAdvisory 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.\n\nAdvisory docs:\n\n- `docs/how-to/use-advisory-decisions.md`\n- `docs/explanation/advisory-decision-flow.md`\n- `docs/reference/spell-syntax.md#advisory-syntax`\n\nSee `grimoire --help` for all CLI commands.\n\n### Library entry point (`@grimoirelabs/core`)\n\nUse this when embedding Grimoire into an app/agent process. The library shares the same compiler/interpreter semantics and preview/commit model as the CLI.\n\nSee `docs/reference/compiler-runtime.md` for `compile`, `preview`, `commit`, `execute`, and session APIs.\n\n### Agent-assisted entry point (skills)\n\nUse skills in `skills/` so agents can work immediately with Grimoire:\n\n- install: `npx skills add https://github.com/franalgaba/grimoire`\n- `skills/grimoire/` for install, CLI usage, syntax starter, and runbook\n- venue skills for snapshot params (`skills/grimoire-aave/`, `skills/grimoire-uniswap/`, `skills/grimoire-morpho-blue/`, `skills/grimoire-across/`, `skills/grimoire-hyperliquid/`, `skills/grimoire-pendle/`, `skills/grimoire-polymarket/`)\n\nFor Claude Code, run the same install command in the Claude Code terminal and start a new session to load the skills.\n\n---\n\n## Example spell\n\n```spell\nspell YieldOptimizer {\n\n  assets: [USDC, DAI]\n\n  advisors: {\n    risk: {\n      model: \"anthropic:haiku\"\n    }\n  }\n\n  venues: {\n    aave_v3: @aave_v3\n    morpho_blue: @morpho_blue\n  }\n\n  params: {\n    amount: 100000\n  }\n\n  on hourly: {\n    decision = advise risk: \"Do gas costs justify rebalancing now?\" {\n      output: {\n        type: boolean\n      }\n      timeout: 10\n      fallback: true\n    }\n\n    if decision {\n      amount_to_move = to_number(balance(USDC)) * 50%\n      aave_v3.withdraw(USDC, amount_to_move)\n      morpho_blue.lend(USDC, amount_to_move)\n    }\n  }\n}\n```\n\n## Features\n\n- **Human-readable DSL** with brace-delimited syntax\n- **Explicit constraints** and limits via `with` and `limits`\n- **Adapter-based venues** (SDKs live in `@grimoirelabs/venues`)\n- **Official adapters** include Aave V3, Uniswap V3/V4, Morpho Blue, Across, Hyperliquid, Pendle, and Polymarket\n- **Onchain + offchain** actions (EVM + Hyperliquid)\n- **Judgment boundary** with explicit `advise` blocks\n- **Structured control flow** (loops, conditionals, try/catch, atomic)\n- **State persistence** and run history for deterministic execution\n- **Unified runtime semantics** across CLI and programmatic embedding\n\nENS profile hydration is available on CLI runs via `--ens-name` and `--ens-rpc-url`.\n\n## Documentation\n\nDocumentation follows [Diataxis](https://diataxis.fr/) in `docs/`:\n\n- `docs/tutorials/`\n- `docs/how-to/`\n- `docs/reference/`\n- `docs/explanation/`\n\nStart at `docs/README.md` for navigation.\n\n## Updating\n\n- Update the CLI: `npm i -g @grimoirelabs/cli@latest`\n- Use `npx` for latest without install: `npx -y @grimoirelabs/cli@latest \u003ccommand\u003e`\n- Update packages in your project: `npm i @grimoirelabs/core@latest @grimoirelabs/venues@latest`\n\n## Development\n\n```bash\nbun install\nbun run validate\n```\n\nFor onchain tests and advanced workflows, see `docs/`.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffranalgaba%2Fgrimoire","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffranalgaba%2Fgrimoire","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffranalgaba%2Fgrimoire/lists"}