Skip to content

CLAUDE.md

Latest commit

 

History

History
70 lines (49 loc) · 3.09 KB

CLAUDE.md

File metadata and controls

70 lines (49 loc) · 3.09 KB
Raw

CLAUDE.md

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

Read AGENTS.md and PRD.md first. This file is intentionally short — it points at the canonical sources and adds Claude-specific notes only.

What this project is

etorotui is a copy-trading–first Textual TUI for analysing personal eToro investments. It replaces the single-file Rich script at ~/madpin/uvility/cli/etoro/portfolio.py with a multi-panel app backed by local SQLite history.

  • Vision, panels, schema, roadmap → PRD.md
  • Coding rules, layering, conventions → AGENTS.md

Non-negotiables (the short list)

  1. PRD is the source of truth. Conflicts with the PRD must be raised before coding.
  2. Read-only against eToro in MVP. Trading actions are placeholders only.
  3. Never persist or log credentials. Headers only.
  4. UI → services → (api | db). UI must not import httpx or sqlite3 directly.
  5. Manual refresh only. No background tasks or WebSocket in MVP.
  6. Always from __future__ import annotations. Python 3.12+, type hints required in api/, services/, db/.
  7. Reuse the math from the legacy script (monthly_realized, current_unrealized, compound_monthly_pct, _money, _pct) — port into src/etorotui/utils/, do not rewrite.

Running locally

# venv (the user rule: always activate before running Python)
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"

etorotui                 # default: real account, ./etorotui.toml, ./.env
etorotui --mode demo
uv run etorotui          # alternative

Lint/format/test:

ruff check .
ruff format .
pytest -q

Claude-specific tips

  • Use the TodoWrite tool for any task touching ≥3 files or panels. Each panel in PRD.md §10/§11 is naturally one or two todos (service wiring + UI).
  • Prefer the Read/Grep/Glob tools over shell for file inspection. Don't cat, don't find.
  • Parallel tool calls are encouraged when reading independent files (e.g. app.py + panels/stocks.py + services/portfolio.py).
  • Never run git commit or git push without an explicit ask — even when changes look "obviously commit-worthy".
  • Do not generate mock JSON fixtures; the user has a working --json dump from the legacy script. If you need fixtures, ask which path on disk to read from.
  • Mirror look-through is the differentiator (PRD.md §10.5). When uncertain whether a feature aggregates "self vs copies", check there.
  • No emojis in code, commits, or UI text unless explicitly requested.

When you're stuck

  • API endpoint catalog: https://api-portal.etoro.com/llms.txt
  • eToro skill (if MCP is configured): use the etoro-skill reference in the docs portal.
  • Schema disagreements: db/schema.sql is canonical, not the dataclasses.
  • Keybinding disagreements: [keybindings] in etorotui.toml overrides; defaults in app.py.