gavel.

Open source · Nouns, ENS & Railgun

Governance
that remembers
how you govern.

Your next decision shouldn’t start from zero. Gavel learns from your voting history, finds your own precedents, and helps you move forward with control.

Install Gavel View on GitHub

Private profiles. Personal precedent. Human judgment.

A decision, with a memoryIllustrative example
GAVEL / REVIEW PACKETPrivate profile
Current proposal

Treasury allocation

Sample proposal Nouns governance

Your precedents03 related votes
Milestone-based fundingOlder precedentFOR
Unrestricted treasury spendRelated structureAGAINST
Open-ended allocationRecent precedentAGAINST
RecommendationAGAINST
72%Heuristic score

Recent related votes favor defined milestones over unrestricted spending.

HUMAN REVIEW REQUIRED

Observed behavior remains advisory.

Action preparationAwaiting your review

Sample data, not a live prediction. A score is not a probability.

01 Remember the record02 Explain the judgment03 Keep the agency

01 / The memory gap

You’ve already built
a record of judgment.

Years of votes. Reasons written. Tradeoffs made. Yet every new proposal asks you to begin again.

Gavel puts that record to work. Your actual decisions become evidence for the next one—without turning yesterday’s vote into tomorrow’s obligation.

Continuity isn’t repetition.
You can change your mind.

02 / How Gavel thinks

Your votes are
the starting point.

A layered decision model, with a clear order of authority. What you explicitly decide takes precedence over what your history suggests.

Evidence layer
  1. 01

    Observed behavior

    Normalized votes and the reasons behind them.

  2. 02

    Recency weighting

    Recent choices carry more influence.

  3. 03

    Relevant precedents

    Related decisions from your own record.

Your explicit direction
Highest authority

Hard rules

Matching constraints you set.

Then

Stated preferences

Your newest applicable preference.

Corrections update policy. They never rewrite your voting history.

The decision path

Recommendation

FORAGAINSTABSTAIN
Human reviewValidation & preparation

Unsigned transaction, only if every required gate passes.

Policy precedenceHard rule > newest matching stated preference > observed behavior

03 / Personal precedent

A throughline.
Not a blank slate.

The relevant question isn’t just “what does this proposal say?” It’s “how have you approached this kind of decision before?”

Gavel compares proposal categories, executable ETH value, recipients, and title signals. It weighs recency separately, so an older, relevant vote still has a voice.

Read the prediction methodology ↗
Memory, with perspective

365-day exponential half-life by default.
Recent evidence matters more. Older evidence remains visible.

Scores are heuristic unless eligible chronological backtest evidence supports calibration. Review is still required.

A personal recordIllustrative history
  1. FOR

    Milestone-based funding

    Reason theme: defined deliverables and staged funding.

    Related category · Older evidence
  2. AGAINST

    Unrestricted treasury spend

    Reason theme: unclear scope and accountability.

    Related structure · More recent
  3. AGAINST

    Open-ended allocation

    Reason theme: milestones before more funding.

    Related structure · Recent evidence
  4. The next decision

    A recommendation you can trace.

    Evidence, explanation, and a draft reason when your record supports one. Always yours to review.

04 / Private by design

Your history
stays yours.

Public votes don’t make your private profile public. Your inferred tendencies, preferences, and rules belong in your own runtime’s private storage.

A private place to remember

A runtime-owned GAVEL_DATA_DIR holds your history, profiles, and policies. Your host controls access, persistence, and backups.

No public agent profile required

Private Gavel data stays out of public Bankr Agent Profiles and project updates. Each voter’s model stays separate.

Your key stays outside the engine

The canonical workflow does not need a private key. Preparing a transaction leaves wallet approval as a separate step.

Read the storage policy ↗

05 / Make it yours

Choose where
Gavel lives.

One governance engine, in the environment you use. Start with history and analysis. Review before preparing an action.

Hermes Start hereBankrYour own harnessCLITUI
Supported · Maintainer-tested

Your personal agent.
Your persistent memory.

The simplest documented setup for Hermes users. Install one skill; its runner bootstraps a pinned Gavel runtime and private data directory on first use.

Best for
A self-hosted conversational agent
Transaction boundary
Unsigned by default; Safe proposer integration available. WaaP requires a separate scoped client.
Hermes runtime guide ↗
01 / Install the skill
hermes skills install https://raw.githubusercontent.com/jgramajo4/gavel/main/integrations/hermes/SKILL.md --yes

Requires Hermes, Git, npm, and Node.js 20+. No manual clone or global install.

02 / Update an existing install
hermes skills check
hermes skills update

Start a new session or use /reset after updating. hermes update updates Hermes itself, not installed skills.

03 / Start the conversation

/gavel-governance Initialize my persistent Gavel profile for Nouns voter 0x...

Updates install a new pinned runtime and do not overwrite GAVEL_DATA_DIR. Container users must persist HERMES_HOME or their private data volume.

Supported · Maintainer-tested

A conversation,
grounded in your record.

Install or update the Gavel skill in Bankr, then start a conversation grounded in your own governance history.

Best for
Conversational governance in Bankr
Transaction boundary
Canonical unsigned preparation. Legacy signing scripts are a separate, explicit path.
Bankr setup and persistence guide ↗
01 / Install or update the skill
Install or update the Gavel skill from:
https://github.com/jgramajo4/gavel/tree/main/nouns-dao

Paste the same instruction into Bankr whenever you want to update. A skill with the same name is replaced; begin a new conversation afterward. View the Gavel skill ↗

Start the conversation

“Sync my Nouns voting history and explain what you learned.”

Updating the skill does not replace Private Files. Sandbox writes alone are not persistent.

Supported · JSON interface

Your harness.
The same judgment engine.

Call the canonical CLI from an agent, scheduler, or application. JSON output and structured errors keep the boundary explicit.

Best for
Custom agents and scheduled CLI jobs
Transaction boundary
Keep recommendation, review, preparation, and submission separate. Nonzero exits and BLOCKED are hard stops.
Read the CLI contract ↗
Repository setup · POSIX shell
git clone --branch main --single-branch https://github.com/jgramajo4/gavel.git gavel
cd gavel
npm ci
export GAVEL_DATA_DIR="$PWD/private/alice"
export GAVEL_STRUCTURED_ERRORS=1
node bin/gavel.js onboard 0xYourVoterAddress --questions

Node.js 20+. Choose an access-controlled data directory. Replace the address placeholder before running onboarding.

Predictable boundaries

Use --stdout for complete JSON artifacts. Safe and WaaP executor APIs require host-supplied clients.

Scheduled CLI jobs are supported. An HTTP server is not yet shipped.

Supported · Canonical entry point

Start in your shell.

Use Gavel directly, without an agent or wallet connection. Ingest history, build a profile, and inspect a proposal before moving to a recommendation.

Best for
Local use and explicit file-based workflows
Transaction boundary
prepare-vote returns unsigned calldata only after review and validation. It never signs or broadcasts.
See the complete CLI workflow ↗
Clone and verify
git clone --branch main --single-branch https://github.com/jgramajo4/gavel.git gavel
cd gavel
npm ci
npm test

Requires Git and Node.js 20+. Chain-backed commands need network access.

A read-only first step

node bin/gavel.js onboard 0xYourVoterAddress --questions

Set a private GAVEL_DATA_DIR before building persistent profiles.

Supported

A seat at the terminal.

Browse proposals and review Gavel recommendations in an interactive terminal, with the same governance engine behind every decision.

Best for
Interactive browsing in a real terminal
Transaction boundary
Recommendations remain advisory. Review before preparing an action; wallet approval is a separate step.
Read the TUI guide ↗
From an existing Gavel clone
npm ci
npm run tui:typecheck
npm run tui

Clone Gavel using the CLI instructions first. Requires Node.js 20+ and an interactive terminal.

One governance engine

The terminal interface uses Gavel’s core. Your runtime choice preserves the same policy and review boundaries.

Review is required before action preparation.

Bankr and BYOH/Hermes have completed maintainer end-to-end testing. Model and transaction launch gates are tracked separately below. Profiles do not automatically sync between runtimes.

06 / Built around one core

One engine.
Many ways in.

Integrations orchestrate the workflow. Core owns the governance reasoning, while the DAO adapter owns chain-specific validation.

HermesBankrCLI / BYOHTUIHTTP server Future

Gavel Core

Profiles · Precedents · Prediction · Policy

ONE CANONICAL ENGINE
NounsToday
ENS GovernorToday
Railgun EthereumToday
Deliberate scope

Clear venue boundaries

  • ENS Snapshot is separate
  • Railgun Polygon / BNB excluded
  • Lobbying agents planned

Bankr, Hermes, the TUI, and compatible harnesses share Gavel’s governance engine. The server package remains a reserved boundary.

07 / Agency, preserved

Recommendation
is not authorization.

Gavel reduces the work around a decision. It keeps the responsibility for that decision visible.

  1. 01

    Recommend

    Evidence and a score.
    Observed behavior is advisory.

  2. 02

    Review

    Explicit prediction review.
    Confirm the support choice.

  3. 03

    Prepare

    Chain validation and simulation.
    Fail closed on uncertainty.

  4. 04

    Approve

    Separate wallet approval.
    Human owners authorize a Safe.

Evidence is never an instruction

Proposal prose is untrusted input. Structured targets, values, and calldata are inspected separately. Unknown actions escalate for review; a “CLEAR” inspection is not proof of economic or contract safety.

A failed gate means no transaction

Preparation checks canonical proposal content and updates, the active voting window, voting power, delegation, duplicate votes, and simulation. Missing review, critical findings, stale content, or RPC uncertainty produce BLOCKED, with no transaction.

Safe approval stays human

The Safe executor passes the exact validated transaction to a host-supplied proposer client. Gavel neither creates a Safe nor holds an owner key. Human Safe owners retain authorization; material transaction changes fail closed.

Autonomy has a narrow, explicit boundary

WaaP is a policy-gated execution scaffold. It requires an autonomy-enabled adapter, an allowlisted action, matching chain and address scope, and a positive policy decision. Observed-behavior recommendations are blocked from autonomy, even after calibration. No live WaaP broadcaster is bundled.

Inspect the preparation gates ↗

08 / The road ahead

Earn the next step.

Useful today. Explicit about what remains. Implementation status and launch readiness are different milestones.

  1. Implemented

    Remember

    Normalized history, private profiles, recency weighting, and explicit policy.

  2. Hardening now

    Recommend

    Precedents and review are implemented. Model quality remains an open gate.

  3. Hardening now

    Prepare

    Unsigned validation is implemented. The pinned mainnet-fork positive path is still open.

  4. Implemented

    Supervise

    A terminal interface and a Safe proposer boundary with human owner approval.

  5. Later

    Expand

    Portable profiles, additional Railgun chains, ENS Snapshot integration, and the reserved HTTP service.

  6. Scoped scaffold

    Scope autonomy

    WaaP gates exist. A live client and eligible explicit policy are required.

An honest baseline

The documented Nouncil evaluation reports 63.69% accuracy against a 64.36% majority baseline. It covers one voter; it is not a general performance claim. Recommendations remain advisory.

Read the launch gates ↗

Your next vote starts with your last.

Less governance work.
Same accountability.

Open source software for participation with memory.
Built to help you decide, with your judgment intact.

Install Gavel Explore GitHub