coinhunter/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Repository purpose

This is a cross-platform skill package for a short-term crypto trading framework called Coin Hunter. It runs on Hermes, OpenClaw, and compatible cron-based runtimes. It contains the skill specification, reference playbooks, and runtime shim templates.

The actual trading CLI is an external dependency: the coinhunter package on PyPI. All execution flows through the installed coinhunter command. This repository does not contain the CLI source code or a build system.

Repository structure

• SKILL.md — The canonical behavior specification. This is the source of truth for the trading framework, including the scientific checklist, execution workflow, review workflow, auto-trading architecture, low-cost gate design, production hardening rules, and troubleshooting notes.
• README.md — User-facing quick-start and overview.
• references/ — Trading playbooks and templates:
  • short-term-trading-framework.md — Hybrid strategy (70% mainstream scalping / 30% meme rotation) and position-sizing rules.
  • provider-playbook.md — Data source hierarchy (Bybit → DexScreener → Birdeye → CoinGecko) and token identity hygiene.
  • user-data-layout.md — Schema for private runtime state under ~/.coinhunter/.
  • review-template.md — Hourly review report structure.
  • scam-signals.md — Red flags and classification guidance for meme-coin evaluation.
  • auto-trading-guide.md — Legacy-oriented guide for deploying auto_trader.py and Binance API setup.
• scripts/ — Thin shim scripts meant to be copied to your platform's scripts directory (e.g. ~/.hermes/scripts/ or ~/.openclaw/scripts/). Currently contains:
  • coinhunter_shim.py — Unified cross-platform shim that runs any coinhunter subcommand (pre, gate, review, rotate-log).

There is no pyproject.toml, Makefile, or test suite in this repository.

Key architectural concepts

Skill vs runtime separation

• Skill code/docs live in this repository.
• Private user state lives under ~/.coinhunter/ (positions, balances, logs, reviews, cache, gate state). Never commit user data into this repo.
• Platform cron scripts are copied from scripts/ to your runtime's scripts directory (e.g. ~/.hermes/scripts/ or ~/.openclaw/scripts/) and invoke the installed coinhunter CLI.

Low-cost trigger architecture

The framework is designed to minimize LLM invocations:

1. A lightweight local Python precheck script decides whether market conditions have changed materially.
2. If should_analyze=false, the cron job emits [SILENT] and exits.
3. If should_analyze=true, the LLM performs deep analysis and may execute trades.
4. An optional external gate (system crontab) can run the precheck every 5 minutes and trigger the platform cron only on true events.

See SKILL.md (sections "Low-cost cron architecture" and "Building your own gate") for the full pseudocode, file layout, state schema, and troubleshooting.

Trading workflow

1. Portfolio-first rule — Always read ~/.coinhunter/positions.json, accounts.json, and recent logs before giving trade advice.
2. Scientific checklist (mandatory before every decision) — trend posture, volume-price fit, key levels, BTC/ETH context, opportunity cost, time window.
3. Execution — Decide HOLD / SELL_ALL / REBALANCE / BUY. Use coinhunter exec for order execution.
4. Review — Run coinhunter recap hourly to analyze decision quality and tune parameters.

Production hardening requirements

When modifying or adding trading scripts, these safeguards from SKILL.md must be respected:

• Idempotency — every decision carries a decision_id; check ~/.coinhunter/executions.json before submitting orders.
• Exchange reconciliation — pull real balances before every run; do not trust local state alone.
• Atomic writes — update positions.json and executions.json under a file lock with temp-file + rename.
• Order precision validation — read exchange lotSize, stepSize, and minNotional filters via ccxt before any order.
• Fee buffer — keep 2%–5% USDT unallocated.
• Structured logging — write JSONL under ~/.coinhunter/logs/ with schema_version and decision_id.
• Platform config atomic writes — if you create or modify ~/.coinhunter/platform.json, write to a temp file and rename it into place, just like positions.json and executions.json.

Safety rules

• No leverage/futures when capital < $200.
• When capital < $50, concentrate into 1 position only.
• Blacklist updates should be driven by review findings.

Common commands

• Install the CLI tool:

  pipx install coinhunter
  # verify
  coinhunter --version
  

• Validate the shim after editing:

  python3 -m py_compile scripts/coinhunter_shim.py
  

• Copy the shim to your platform's scripts directory:

  cp scripts/coinhunter_shim.py ~/.hermes/scripts/coinhunter_shim.py
  # or: cp scripts/coinhunter_shim.py ~/.openclaw/scripts/coinhunter_shim.py
  

• Inspect user state:

  cat ~/.coinhunter/positions.json
  cat ~/.coinhunter/accounts.json
  ls ~/.coinhunter/logs/
  ls ~/.coinhunter/reviews/
  

• Common trading CLI commands:

  coinhunter pre
  coinhunter exec
  coinhunter recap
  coinhunter review
  coinhunter probe bybit-ticker
  

Reference routing

When working on Coin Hunter, read the relevant reference file at the right moment:

Task context	File to read
Active trade decision (mainstream coin)	references/short-term-trading-framework.md
Active trade decision (meme coin)	references/short-term-trading-framework.md + references/scam-signals.md
Data source conflict / ambiguity	references/provider-playbook.md
Hourly review formatting	references/review-template.md
Runtime state / log schema questions	references/user-data-layout.md
Binance API / auto-trading setup	references/auto-trading-guide.md
Output format / report templates	references/output-templates.md
Proactive discovery scan workflow	references/search-workflow.md

When making changes

• If you change SKILL.md, check whether README.md needs corresponding updates.
• If you change shim templates, validate them with python3 -m py_compile before copying to your platform's scripts directory.
• Keep the separation between this repo and ~/.coinhunter/ — never write personal account data or logs into the skill directory.