Tacit Lab
c07b9c1ae5
- 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
115 lines
6.3 KiB
Markdown
115 lines
6.3 KiB
Markdown
# 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.
|