refactor: decouple Coin Hunter from Hermes for cross-platform usage
- Add unified coinhunter_shim.py that accepts subcommands (pre/gate/review/rotate-log) - Update SKILL.md gate pseudocode to read optional ~/.coinhunter/platform.json - Split cron/setup examples into Hermes and OpenClaw variants across docs - Introduce platform.json schema in user-data-layout.md - Remove stale auto_trader.py/run_trader.sh references from auto-trading-guide.md - Keep legacy shims as backward-compatible wrappers
This commit is contained in:
114
CLAUDE.md
Normal file
114
CLAUDE.md
Normal file
@@ -0,0 +1,114 @@
|
||||
# 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.
|
||||
- `templates/` — Thin shim scripts meant to be copied to your platform's scripts directory (e.g. `~/.hermes/scripts/` or `~/.openclaw/scripts/`). Each shim invokes the installed `coinhunter` CLI:
|
||||
- `coinhunter_precheck_shim.py` — Runs `coinhunter pre`.
|
||||
- `coinhunter_external_gate_shim.py` — Runs `coinhunter gate`.
|
||||
- `coinhunter_review_context_shim.py` — Runs `coinhunter review`.
|
||||
- `rotate_external_gate_log_shim.py` — Runs `coinhunter 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 `templates/` 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 Hermes 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:**
|
||||
```bash
|
||||
pipx install coinhunter
|
||||
# verify
|
||||
coinhunter --version
|
||||
```
|
||||
|
||||
- **Validate a shim after editing:**
|
||||
```bash
|
||||
python3 -m py_compile templates/coinhunter_precheck_shim.py
|
||||
```
|
||||
|
||||
- **Copy shims to your platform's scripts directory:**
|
||||
```bash
|
||||
# Unified shim (recommended)
|
||||
cp templates/coinhunter_shim.py ~/.hermes/scripts/coinhunter_shim.py
|
||||
# or: cp templates/coinhunter_shim.py ~/.openclaw/scripts/coinhunter_shim.py
|
||||
|
||||
# Legacy individual shims (Hermes backward compatibility)
|
||||
cp templates/coinhunter_precheck_shim.py ~/.hermes/scripts/coinhunter_precheck.py
|
||||
cp templates/coinhunter_external_gate_shim.py ~/.hermes/scripts/coinhunter_external_gate.py
|
||||
cp templates/coinhunter_review_context_shim.py ~/.hermes/scripts/coinhunter_review_context.py
|
||||
```
|
||||
|
||||
- **Inspect user state:**
|
||||
```bash
|
||||
cat ~/.coinhunter/positions.json
|
||||
cat ~/.coinhunter/accounts.json
|
||||
ls ~/.coinhunter/logs/
|
||||
ls ~/.coinhunter/reviews/
|
||||
```
|
||||
|
||||
- **Common trading CLI commands:**
|
||||
```bash
|
||||
coinhunter pre
|
||||
coinhunter exec
|
||||
coinhunter recap
|
||||
coinhunter review
|
||||
coinhunter probe bybit-ticker
|
||||
```
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user