CLAUDE.md

1# CLAUDE.md
2 
3## Project
4Agent Reach — Python CLI + library that gives AI agents read/search access to 13 internet platforms.
5Positioning: installer + doctor + config tool. NOT a wrapper — after install, agents call upstream tools directly.
6Repo: github.com/Panniantong/Agent-Reach | License: MIT | Version: 1.5.0
7 
8## Commands
9- `pip install -e .` — Dev install
10- `pytest tests/ -v` — All tests
11- `pytest tests/test_cli.py -v` — CLI tests only
12- `bash test.sh` — Full integration test (creates venv, installs, runs doctor + channel tests)
13- `python -m agent_reach.cli doctor` — Run diagnostics
14- `python -m agent_reach.cli install --env=auto` — Auto-configure
15 
16## Structure
17- `agent_reach/cli.py` — CLI entry point (argparse)
18- `agent_reach/core.py` — Core read/search routing logic
19- `agent_reach/config.py` — Config management (YAML, env vars)
20- `agent_reach/doctor.py` — Diagnostics engine
21- `agent_reach/channels/` — One file per platform (twitter.py, reddit.py, youtube.py, etc.)
22- `agent_reach/channels/base.py` — Base channel class (all channels inherit from this)
23- `agent_reach/integrations/mcp_server.py` — MCP server integration
24- `agent_reach/skill/` — OpenClaw skill files
25- `agent_reach/guides/` — Usage guides
26- `tests/` — pytest tests
27- `config/mcporter.json` — MCP tool config
28 
29## Conventions
30- Python 3.10+ with type hints
31- Each channel is a single file in `channels/`, inherits from `BaseChannel`
32- Channel contract: must implement `can_handle(url)`, `read(url)`, `search(query)`, `check()` methods
33- Use `loguru` for logging, `rich` for CLI output
34- Commit format: `type(scope): message` (one commit = one thing)
35- All upstream tool calls go through public API/CLI, never hack internals
36 
37## Rules
38- NEVER modify upstream open source projects' source code
39- Agent Reach is a "glue layer" — only route and call, don't reimagine
40- Version in THREE places must match: `pyproject.toml`, `__init__.py`, `tests/test_cli.py`
41- Always new branch for changes, PR to main, never push to main directly
42- Run `pytest tests/ -v` before committing — all tests must pass
43- Cookie-based auth (Twitter, XHS): use Cookie-Editor export method only, no QR scan
44- XHS login: Cookie-Editor browser export only (QR will hang)
45