Just a fun project, not be taken seriously and not financial guidance.

Meteora Claw Operating Guide

This repository is an operations workspace for a Codex-run Meteora DLMM LP agent.
It is built around three control planes:

1. Skills (capability routing)
2. Governance files (risk and behavior contracts)
3. Non-interactive heartbeat execution (codex exec every 30 minutes)

This guide focuses on repository operation and structure, not application/business code internals.

1) Guidance Stack (What Controls Behavior)

1.1 Core Guidance Files

• AGENTS.md: primary bot charter (mission, memory loop, open-position tracking, heartbeat policy, escalation policy, skill catalog references).
• RISK.md: binding risk limits and execution gates; no action is allowed if it violates this file.
• heartbeat.prompt.md: recurring heartbeat prompt used for scheduled runs.
• heartbeat.first-run.prompt.md: bootstrap / first-after-close prompt for fresh or reset context.
• .codex/config.toml: execution harness defaults (model, approvals, sandbox, multi-agent feature toggle, MCP server configuration).

1.2 Instruction Flow (ASCII)

TEXT
User/System Task  
   |  
   v  
Codex Runtime Rules (system + developer)  
   |  
   v  
Repo Governance (AGENTS.md + RISK.md)  
   |  
   v  
Heartbeat Prompt Mode  
   |  (heartbeat.prompt.md OR heartbeat.first-run.prompt.md)  
   v  
Skill Router  
   |  
   v  
Execution (open/rebalance/close/no-op) + file updates  

1.3 Why This Matters

• AGENTS.md defines what the agent is.
• RISK.md defines what the agent is allowed to do.
• Heartbeat prompts define what each scheduled run must produce now.
• Skills define how the agent executes specialized tasks.

2) Skills System (Primary Capability Layer)

2.1 Skill Sources

• Repo-local skills: .agents/skills/...
• Runtime-injected external skills: user/system skill directories (for example $HOME/.agents/skills, $HOME/.codex/skills)

2.2 Repo-Local Skill Inventory

• agent-browser: browser automation and web extraction
• binance-spot-api: read-only Binance market intelligence workflows
• codex-self-aware: Codex mode/tooling/self-update workflows
• jupiter-swap: Jupiter Ultra swap flow (order -> sign -> execute -> verify)
• meteora-lp: Meteora LP fundamentals
• meteora-strategies: DLMM strategy playbooks and tactical routing
• meteora-typescript-sdk-actions: Meteora DLMM TypeScript SDK method/script routing
• solana-kit: Solana Kit transaction/RPC patterns

2.3 Skill Trigger and Usage Rules

Runtime policy requires:

1. If a skill is explicitly named, use it.
2. If intent matches a skill description, use it.
3. Use the minimal set of skills needed.
4. Load only needed references/scripts (progressive loading).
5. Prefer skill-owned scripts/templates over ad-hoc rewrites.

2.4 Skill File Anatomy

TEXT
.agents/skills/<skill>/  
|-- SKILL.md                  # scope, triggers, workflow, safety boundaries  
|-- references/               # source material  
|-- scripts/                  # executable helpers  
|-- examples/                 # usage examples  
|-- templates/                # reusable templates  
`-- agents/openai.yaml        # optional skill metadata/default behavior  

Typical SKILL.md structure in this repo:

• YAML frontmatter (name, description, optional allowed-tools)
• "Use this skill when..." scope statement
• Decision flow / mandatory workflow
• Safety and correctness rules
• Output contract and reference loading guidance

2.5 Skill Creation / Evolution Workflow

TEXT
Need detected  
   |  
   v  
Define narrow capability boundary  
   |  
   v  
Create/Update SKILL.md  
   |  
   +--> add minimal references  
   +--> add scripts/examples/templates only if needed  
   |  
   v  
Use in heartbeat/manual runs  
   |  
   v  
Refine from outcomes (keep lean, deterministic, auditable)  

3) Heartbeat Engine (codex exec Non-Interactive)

Heartbeat runs every 30 minutes and is the core autonomous loop.

3.1 Script Topology

• scripts/start-heartbeat.sh: main entrypoint (bootstrap + scheduler selection)
• scripts/heartbeat-bootstrap-worker.sh: starts a fresh codex exec session and pins session id
• scripts/heartbeat-run.sh: executes one run (resume if possible, otherwise new)
• scripts/heartbeat-watchdog.sh: triggers catch-up run when stale
• scripts/install-heartbeat-cron.sh: installs cron scheduler (+ watchdog)
• scripts/install-heartbeat-launchd.sh: installs launchd fallback scheduler
• scripts/heartbeat-loop-worker.sh: internal sleep-loop scheduler fallback

3.2 Actual Execution Patterns

• New run:
  • codex exec --dangerously-bypass-approvals-and-sandbox -C <repo> --skip-git-repo-check --output-last-message <file> -
• Resume run:
  • codex exec resume --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check --output-last-message <file> <session_id> -

Session control:

• .heartbeat/session.id present: resume mode
• Resume failure: clear session id and start fresh session
• Session id discovery: parsed from Codex session files/log output and persisted

3.3 Prompt Mode Switching

heartbeat-run.sh chooses prompt file at runtime:

• Default recurring mode: heartbeat.prompt.md
• First-after-close mode: heartbeat.first-run.prompt.md (queued via .heartbeat/force-first-prompt.once)

Close detection uses a signature of | CLOSED | rows in OpenPositions.md.

3.4 Scheduler Modes

start-heartbeat.sh scheduler selection:

• cron preferred: */30 run + */5 watchdog
• launchd fallback: StartInterval=1800
• internal loop fallback: sleep 1800

Detached scheduler runtime directory:

• ~/.codex-heartbeat/meteora-claw/

This detached state stores copied scripts/prompts/logs/session pinning so background execution does not depend on an attached shell.

3.5 Heartbeat Lifecycle (ASCII)

TEXT
Trigger (cron | launchd | loop | watchdog | manual)  
   |  
   v  
heartbeat-run.sh  
   |  
   +--> acquire lock (.heartbeat/run.lock)  
   +--> load prompt mode (normal or first-after-close)  
   +--> build prompt payload (with heartbeat note context)  
   +--> run codex exec / codex exec resume  
   +--> persist outputs (session.id, last_message.md, last_run.meta)  
   +--> update closed-position signature state  
   `--> release lock  

3.6 Heartbeat Runtime State Files

Under .heartbeat/:

• session.id: pinned session continuity id
• last_run.meta: timestamp, trigger source, prompt mode, close-signature info
• last_message.md: last Codex message from run
• last-closed.sig: signature snapshot of closed rows in OpenPositions.md
• heartbeat.prompt.md, heartbeat.first-run.prompt.md: local runtime prompt copies
• cron.log, bootstrap.log, launchd.log, loop.log: execution logs

4) Risk Governance (RISK.md) Deep Summary

RISK.md is binding. If a candidate action fails these gates, the action is rejected.

4.1 Hard Quantitative Limits

• Max concurrent open DLMM positions: 3
• Min wallet reserve: 0.1 SOL
• Max slippage (liquid pairs): 0.50%
• Max slippage (volatile/thin pairs): 1.00%
• Rebalance cost guard: total rebalance cost should stay <= 30% of expected 24h fee recovery (unless urgent risk reduction)

4.2 Mandatory Due Diligence Sequence

1. Discover candidate pools on Meteora.
2. Screen liquidity, fee behavior, recent activity, volatility fit, range-management burden.
3. Shortlist viable candidates.
4. Run Binance Spot due diligence on shortlisted token set.
5. Use those due-diligence outputs in final entry/rebalance decision.

4.3 Control Logic

• Prefer no action over low-conviction action.
• Require expected net-positive outcome after swap/rebalance costs.
• Evaluate short-tail and long-tail opportunities each run.
• Avoid duplicate pool exposure when adding positions.
• Pause new risk-taking during disorderly volatility or degraded data/routing quality.

5) State Files and Ownership Model

5.1 Canonical Files

• OpenPositions.md: single source of truth for active and closed positions
• memory.md: distilled learnings only (high-signal, reusable)
• heartbeat.md: concise run handoff/scratchpad
• user_request.md: blocker escalation to user

5.2 Update Contracts

• Every open/resize/rebalance/partial exit/full close must be reflected in OpenPositions.md.
• memory.md is updated with distilled insights from trade outcomes (not raw logs).
• heartbeat.md must remain short, actionable, and aligned with latest state.
• user_request.md must be written when autonomous progress is blocked.

5.3 Distillation Memory Loop (ASCII)

TEXT
Execution actions  
   |  
   v  
trade-logs/* artifacts (raw evidence)  
   |  
   v  
Distillation step (after closes / heartbeat review)  
   |  
   v  
memory.md (concise, reusable lessons)  
   |  
   v  
Next run planning context (read first)  

Distillation policy from guidance files:

• Trade logs are source artifacts.
• memory.md should store concise abstractions, not raw log dumps.

6) Heartbeat Prompt Contracts

6.1 Recurring Prompt (heartbeat.prompt.md)

Requires each run to:

• read current state (OpenPositions.md, heartbeat.md)
• distill closed-trade learnings into memory.md when relevant
• take one concrete action now: open/rebalance/close/no-op with quantified reason
• avoid deferring actionable OOR decisions without blocker
• use listed skills actively for discovery, strategy, execution, and due diligence

6.2 First-Run Prompt (heartbeat.first-run.prompt.md)

Bootstraps from full context and emphasizes:

• read order including AGENTS.md, RISK.md, memory.md, OpenPositions.md, heartbeat.md
• find best pools under risk profile
• create positions when qualified
• update state files immediately
• escalate blockers to user_request.md

7) Auditability and Evidence

Primary evidence locations:

• trade-logs/: pool scans, due diligence outputs, open/close/swap artifacts
• .heartbeat/*.log: scheduler and runner logs
• .heartbeat/last_run.meta: per-run metadata and continuity markers

This structure enables replay of: why a run acted, what constraints were applied, and what changed in state files.

8) Operator Commands

BASH
# Start heartbeat with auto scheduler selection  
bash scripts/start-heartbeat.sh

# Force scheduler mode  
bash scripts/start-heartbeat.sh --scheduler=cron  
bash scripts/start-heartbeat.sh --scheduler=launchd  
bash scripts/start-heartbeat.sh --scheduler=loop

# Configure scheduler only (no new bootstrap session)  
bash scripts/start-heartbeat.sh --scheduler-only

# Run one manual heartbeat pass  
HEARTBEAT_TRIGGER=manual-oneoff bash scripts/heartbeat-run.sh

# Run watchdog check manually  
bash scripts/heartbeat-watchdog.sh  

9) Repository Structure (Skills + Governance + Heartbeat)

TEXT
.
|-- AGENTS.md  
|-- RISK.md  
|-- memory.md  
|-- OpenPositions.md  
|-- heartbeat.md  
|-- heartbeat.prompt.md  
|-- heartbeat.first-run.prompt.md  
|-- user_request.md  
|-- .codex/config.toml  
|-- .agents/skills/  
|   |-- agent-browser/  
|   |-- binance-spot-api/  
|   |-- codex-self-aware/  
|   |-- jupiter-swap/  
|   |-- meteora-lp/  
|   |-- meteora-strategies/  
|   |-- meteora-typescript-sdk/  
|   `-- solana-kit/  
|-- scripts/  
|   |-- start-heartbeat.sh  
|   |-- heartbeat-bootstrap-worker.sh  
|   |-- heartbeat-run.sh  
|   |-- heartbeat-watchdog.sh  
|   |-- heartbeat-loop-worker.sh  
|   |-- install-heartbeat-cron.sh  
|   `-- install-heartbeat-launchd.sh  
|-- .heartbeat/  
|   `-- runtime state and logs  
`-- trade-logs/  
    `-- execution and due-diligence artifacts  

10) One-View Mental Model

TEXT
Skills tell the agent HOW to do work.  
AGENTS.md tells the agent WHAT role to play.  
RISK.md tells the agent WHAT it is allowed to do.  
heartbeat prompts tell the agent WHAT must be done this run.  
heartbeat scripts ensure this happens every 30 minutes via codex exec.  
state files preserve continuity, auditability, and learning.  

Source: https://github.com/UjjwalGupta49/met-claw