# 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:**
  ```bash
  pipx install coinhunter
  # verify
  coinhunter --version
  ```

- **Validate the shim after editing:**
  ```bash
  python3 -m py_compile scripts/coinhunter_shim.py
  ```

- **Copy the shim to your platform's scripts directory:**
  ```bash
  cp scripts/coinhunter_shim.py ~/.hermes/scripts/coinhunter_shim.py
  # or: cp scripts/coinhunter_shim.py ~/.openclaw/scripts/coinhunter_shim.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
  ```

## 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.