coinhunter/CLAUDE.md

CLAUDE.md

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

Development commands

• Install (dev): pip install -e ".[dev]" or conda env create -f environment.yml && conda activate coinhunter
• Run CLI locally: python -m coinhunter --help
• Run tests: pytest or python -m pytest tests/
• Run single test file: pytest tests/test_cli.py -v
• Lint: ruff check src tests
• Format: ruff format src tests
• Type-check: mypy src

Architecture

CoinHunter is a lightweight data-layer CLI designed to pair with the coinbuddy AI Skill for crypto trading on Binance. The philosophy is layered screening: the CLI handles cheap rule-based filtering and monitoring, while the AI Skill handles expensive deep analysis on a small set of curated candidates.

CLI layer (data + execution)

• src/coinhunter/cli.py — Single entrypoint (main()). Uses argparse to parse commands and directly dispatches to service functions. Core commands: init, config, account, market, buy, sell, portfolio, scan, analyze, watch, upgrade, catlog, completion.
• src/coinhunter/services/ — Domain logic:
  • account_service.py — balances, positions
  • market_service.py — tickers, klines, scan universe, symbol normalization
  • signal_service.py — shared market signal scoring (rule-based, zero token cost)
  • portfolio_service.py — held-position review (analyze_portfolio) and lightweight anomaly monitoring (watch_portfolio)
  • trade_service.py — spot order execution only
  • opportunity_service.py — market scanning (scan_opportunities) returning top-N candidates
  • analyze_service.py — multi-timeframe deep technical analysis for AI consumption
• src/coinhunter/binance/spot_client.py — Thin wrapper around binance.spot.Spot. Normalizes request errors into RuntimeError.
• src/coinhunter/config.py — load_config(), get_binance_credentials(), ensure_init_files().
• src/coinhunter/runtime.py — RuntimePaths, get_runtime_paths(), print_json(), TUI rendering.
• src/coinhunter/audit.py — Writes JSONL audit events to dated files.

AI layer (decision)

• coinbuddy Skill — Lives at ~/.claude/skills/coinbuddy/SKILL.md. Governs how the AI interacts with the CLI:
  • Discovery flow: scan → analyze → AI synthesis → user confirm → trade
  • Portfolio flow: watch → flag NEED_REVIEW → analyze → AI synthesis → user confirm → trade
  • The Skill always uses --agent for structured JSON consumption.

Runtime and environment

User data lives in ~/.coinhunter/ by default (override with COINHUNTER_HOME):

• config.toml — runtime, binance, trading, signal, opportunity, portfolio, and watch settings
• .env — BINANCE_API_KEY and BINANCE_API_SECRET
• logs/audit_YYYYMMDD.jsonl — structured audit log
• logs/dry-run/audit_YYYYMMDD.jsonl — dry-run audit log

Run coinhunter init to generate the config and env templates.

Key conventions

• Symbol normalization: market_service.normalize_symbol() strips /, -, _, and uppercases the symbol. CLI inputs like ETH/USDT, eth-usdt, and ETHUSDT are all normalized to ETHUSDT.
• Dry-run behavior: Trade commands support --dry-run. If omitted, the default falls back to trading.dry_run_default in config.toml.
• Client injection: Service functions accept spot_client as a keyword argument for easy unit testing with mocks.
• Error handling: spot_client.py catches requests.exceptions.SSLError and RequestException and re-raises as human-readable RuntimeError. The CLI catches all exceptions in main() and prints error: {message} to stderr with exit code 1.
• Ticker API fallback: spot_client.ticker_stats() uses rolling_window_ticker for symbol-specific queries and ticker_24hr for full-market scans (no symbols).
• Output modes: All commands support --agent for JSON output and --doc to print the command's output schema.
• Watch rules: portfolio_service.watch_portfolio() monitors held positions for anomalies (1h/24h drawdowns, spikes, concentration risk, technical score deterioration). This is pure rule-based and costs zero tokens.
• Analyze design: analyze_service.analyze_symbols() fetches multi-timeframe klines (1h, 4h, 1d) and produces an AI-friendly output with summary, timeframes, key_levels, alerts, and signal_score. It is designed for LLM consumption.

CLI command reference

Command	Purpose	Token cost
coin scan	Rule-based market scan, returns top-N candidates	0
coin analyze <sym>	Multi-timeframe deep technical analysis	0
coin watch	Portfolio anomaly monitoring	0
coin portfolio	Full portfolio scoring	0
coin account	Balances	0
coin buy/sell	Trade execution	0

Testing

Tests live in tests/ and use unittest.TestCase with unittest.mock.patch. The test suite covers CLI parser smoke tests, config loading, service logic with mocked clients, and trade execution paths.

Notes

• AGENTS.md in this repo is stale and describes a prior V1 architecture (commands/, smart executor, precheck, review engine). Do not rely on it.
• Removed in the V2 simplification: backtest, strategy, opportunity dataset/evaluate/optimize, research_service (CoinGecko). These were over-engineered for the AI-assisted trading flow and have been archived out of the core codebase.