coinhunter-cli/CLAUDE.md

CLAUDE.md

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

Development commands

• Editable install: pip install -e .
• Run the CLI locally: python -m coinhunter --help
• Install for end users: ./scripts/install_local.sh (standard pip install -e . wrapper)
• Tests: There is no test suite yet. The README lists next priorities as adding pytest coverage for runtime paths, state manager, and trigger analyzer.
• Lint / type-check: Not configured yet.

CLI command routing

src/coinhunter/cli.py is the single entrypoint. It resolves aliases to canonical commands, maps canonical commands to Python modules via MODULE_MAP, then imports the module and calls module.main() after mutating sys.argv to match the display name.

Active commands live in src/coinhunter/commands/ and are thin adapters that delegate to src/coinhunter/services/. Root-level backward-compat facades (e.g., precheck.py, smart_executor.py, review_engine.py, review_context.py) re-export the moved commands.

Architecture

Layer responsibilities

• CLI (cli.py) — argument parsing, alias resolution, module dispatch.
• Commands (commands/) — thin, stateless adapters that call into services.
• Services (services/) — orchestration, domain logic, and exchange interaction.
• Runtime (runtime.py) — path resolution, env loading, hermes binary discovery.
• Logger (logger.py) — structured JSONL logging to ~/.coinhunter/logs/.

Runtime and environment

runtime.py defines RuntimePaths and get_runtime_paths(). User data lives in ~/.coinhunter/ by default (override with COINHUNTER_HOME). Credentials are loaded from ~/.hermes/.env by default (override with COINHUNTER_ENV_FILE). Modules should call get_runtime_paths() at function scope rather than eagerly at import time.

Smart executor (exec)

commands/smart_executor.py → services/smart_executor_service.py → services/trade_execution.py.

Supported verbs: bal, overview, hold, buy SYMBOL USDT, flat SYMBOL, rotate FROM TO.

• smart_executor_parser.py normalizes legacy argv and exposes parse_cli_args().
• trade_common.py holds a global dry-run flag (set_dry_run / is_dry_run).
• execution_state.py tracks decision IDs in JSON to prevent duplicate executions.
• exchange_service.py wraps ccxt.binance and handles symbol normalization.
• portfolio_service.py manages positions.json load/save/reconcile.

Precheck

commands/precheck.py → services/precheck_service.py.

The precheck workflow:

1. Load and sanitize state (precheck_state.py — clears stale triggers and run requests).
2. Build a market snapshot (precheck_snapshot.py → snapshot_builder.py).
3. Analyze whether to trigger deep analysis (precheck_analysis.py → trigger_analyzer.py).
4. Update and save state (precheck_state.update_state_after_observation).

State is stored in ~/.coinhunter/state/precheck_state.json.

Review commands

• review N (commands/review_context.py → services/review_service.py) — generates review context for the last N hours.
• recap N (commands/review_engine.py → services/review_service.py) — generates a full review report by reading JSONL decision/trade/error logs, computing PnL estimates, missed opportunities, and saving a report to ~/.coinhunter/reviews/.

Logging model

logger.py writes JSONL to dated files in ~/.coinhunter/logs/:

• decisions_YYYYMMDD.jsonl
• trades_YYYYMMDD.jsonl
• errors_YYYYMMDD.jsonl
• snapshots_YYYYMMDD.jsonl

Use get_logs_last_n_hours(log_type, hours) to query recent entries.

Common command reference

# Diagnostics
python -m coinhunter diag
python -m coinhunter paths
python -m coinhunter api-check

# Execution (dry-run)
python -m coinhunter exec bal
python -m coinhunter exec overview
python -m coinhunter exec buy ENJUSDT 50 --dry-run
python -m coinhunter exec flat ENJUSDT --dry-run

# Precheck
python -m coinhunter precheck
python -m coinhunter precheck --ack "analysis completed"
python -m coinhunter precheck --mark-run-requested "reason"

# Review
python -m coinhunter review 12
python -m coinhunter recap 12

Skill routing

When the user's request matches an available skill, ALWAYS invoke it using the Skill tool as your FIRST action. Do NOT answer directly, do NOT use other tools first. The skill has specialized workflows that produce better results than ad-hoc answers.

Key routing rules:

• Product ideas, "is this worth building", brainstorming → invoke office-hours
• Bugs, errors, "why is this broken", 500 errors → invoke investigate
• Ship, deploy, push, create PR → invoke ship
• QA, test the site, find bugs → invoke qa
• Code review, check my diff → invoke review
• Update docs after shipping → invoke document-release
• Weekly retro → invoke retro
• Design system, brand → invoke design-consultation
• Visual audit, design polish → invoke design-review
• Architecture review → invoke plan-eng-review
• Save progress, checkpoint, resume → invoke checkpoint
• Code quality, health check → invoke health