docs(claude): update commands and add test instructions

Author: lzwjava

CLAUDE.md

@@ -5,32 +5,67 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ## Commands
 
 ```bash
-pip install -e .              # Install package in editable mode (dev)
-iclaw-login            # Authenticate with GitHub via device flow (saves token to ~/.config/iclaw/config.json)
-iclaw                  # Start the interactive CLI REPL
-ruff check .                  # Lint code
-ruff format .                 # Format code
+pip install -e .                    # Install package in editable mode
+iclaw-login                         # Authenticate via GitHub device flow
+iclaw                               # Start the interactive CLI REPL
+ruff check .                        # Lint
+ruff format .                       # Format (also runs on pre-commit)
 ```
 
-Pre-commit hooks run automatically on commit: ruff format.
+### Running Tests
 
-## Architecture
+```bash
+# Unit tests (no credentials needed)
+export PYTHONPATH=$PYTHONPATH:.
+python3 -m unittest discover tests
+
+# Single test file
+python3 -m unittest tests/test_main.py
+
+# Single test case
+python3 -m unittest tests/test_main.py::TestMain::test_main_chat
+
+# With coverage
+pip install coverage
+python3 -m coverage run -m unittest discover tests
+python3 -m coverage report -m iclaw/*.py iclaw/commands/*.py iclaw/tools/*.py
+
+# Integration tests (require GITHUB_TOKEN_INTEGRATION env var)
+GITHUB_TOKEN_INTEGRATION=<token> python3 -m unittest discover integration_tests
+```
 
-This is a Python CLI package (iclaw) that provides an interactive terminal REPL for chatting with GitHub Copilot.
+### GitHub Actions
+
+- **`.github/workflows/test.yaml`** — Runs on push/PR touching `iclaw/**` or `tests/**`. Runs unit tests with `coverage` against `iclaw/*.py`, `iclaw/commands/*.py`, `iclaw/tools/*.py`.
+- **`.github/workflows/integration.yaml`** — Runs on push/PR touching `mini_copilot/**` or `integration_tests/**`. Skips silently if `GITHUB_TOKEN_INTEGRATION` secret is not set.
+
+## Architecture
 
 **Authentication flow:**
-1. `iclaw-login` runs GitHub OAuth Device Flow, saves the GitHub token to `~/.config/iclaw/config.json`
-2. On startup, `iclaw` reads the GitHub token from `~/.config/iclaw/config.json`, then exchanges it for a short-lived Copilot token via `https://api.github.com/copilot_internal/v2/token`
-3. The Copilot token is refreshed every ~24 minutes during the session
+1. `iclaw-login` runs GitHub OAuth Device Flow → saves `github_token` to `~/.config/iclaw/config.json`
+2. `iclaw` startup reads the token via `iclaw/config.py:load_github_token()`, then exchanges it for a short-lived Copilot token (`iclaw/github_api.py:get_copilot_token()`)
+3. The Copilot token is refreshed every `TOKEN_REFRESH_INTERVAL` seconds (24 min) during the session
+
+**REPL loop (`iclaw/main.py:main()`):**
+- Uses `prompt_toolkit.PromptSession` with `IclawCompleter` for tab-completion
+- Commands (`/model`, `/copy`, etc.) are handled before messages reach the API
+- User input passes through `resolve_at_mentions()` to expand `@filepath` references into `<file>` XML tags prepended to the message
+- Calls `github_api.chat()` with the full message history and `TOOLS`
+- Handles agentic tool-call loops: the model may return `tool_calls` for `web_search`, `exec`, or `edit`; results are appended as `role: tool` messages and the API is called again until a plain text reply is returned
+
+**Tool definitions (`iclaw/tools/defs.py`):**
+- `web_search` — delegates to `iclaw/web_search.py` (DuckDuckGo or Tavily based on `search_provider`)
+- `exec` — delegates to `iclaw/exec_tool.py` (runs shell commands locally)
+- `edit` — delegates to `iclaw/tools/edit_tool.py` (applies unified diffs to files)
+
+**Key modules:**
+- `iclaw/completer.py` — `IclawCompleter`: `@`-mention file completion (via `git ls-files`) and `/`-command completion
+- `iclaw/at_mention.py` — `resolve_at_mentions()`: expands `@path` tokens into file content XML
+- `iclaw/github_api.py` — `get_copilot_token()`, `get_models()`, `chat()`
+- `iclaw/commands/` — handlers for `/model_provider`, `/model`, `/search_provider`, `/copy`
+- `iclaw/config.py` — `CONFIG_PATH`, `TOKEN_REFRESH_INTERVAL`, `load_github_token()`
 
 **API endpoints:**
-- `https://github.com/login/device/code` — Device authorization
-- `https://github.com/login/oauth/access_token` — Token polling
 - `https://api.github.com/copilot_internal/v2/token` — Copilot token exchange
-- `https://api.githubcopilot.com/chat/completions` — Chat completions (GPT-4o model)
-
-**Key files:**
-- `iclaw/main.py` — Interactive REPL: loads token, maintains conversation history, calls Copilot API
-- `iclaw/login.py` — CLI login utility
-- `pyproject.toml` — Package metadata and entry points
-- `~/.config/iclaw/config.json` — Generated by login, not in repo; contains `{ github_token, created_at }`
+- `https://api.githubcopilot.com/chat/completions` — Chat completions
+- `https://api.githubcopilot.com/models` — Available model list

iclaw/at_mention.py

@@ -0,0 +1,21 @@
+import os
+import re
+from pathlib import Path
+
+
+def resolve_at_mentions(text):
+    """Extract @file references, return augmented text with file contents prepended."""
+    mentions = re.findall(r"@(\S+)", text)
+    if not mentions:
+        return text
+    parts = []
+    for path in mentions:
+        if os.path.isfile(path):
+            try:
+                contents = Path(path).read_text()
+                parts.append(f'<file path="{path}">\n{contents}\n</file>')
+            except OSError:
+                pass
+    if parts:
+        return "\n".join(parts) + "\n\n" + text
+    return text

iclaw/completer.py

@@ -0,0 +1,68 @@
+import os
+import subprocess
+
+from prompt_toolkit.completion import Completer, Completion
+
+COMMANDS = [
+    "/model_provider",
+    "/model",
+    "/search_provider",
+    "/copy",
+    "/help",
+    ".exit",
+]
+
+
+def _get_git_files():
+    """Return files from git ls-files, natively respecting .gitignore."""
+    try:
+        result = subprocess.run(
+            ["git", "ls-files", "--cached", "--others", "--exclude-standard"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if result.returncode == 0:
+            return result.stdout.splitlines()
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        pass
+    return []
+
+
+class IclawCompleter(Completer):
+    """Handles both / command completion and @ file mention completion."""
+
+    def get_completions(self, document, complete_event):
+        text = document.text_before_cursor
+
+        # @ file mention: find the last @ not followed by a space
+        at_pos = text.rfind("@")
+        if at_pos != -1:
+            prefix = text[at_pos + 1 :]
+            if " " not in prefix:
+                all_files = _get_git_files()
+                matches = [f for f in all_files if prefix.lower() in f.lower()]
+                count = 0
+                for path in sorted(matches):
+                    if count >= 20:
+                        break
+                    count += 1
+                    meta = "dir" if os.path.isdir(path) else "file"
+                    yield Completion(
+                        path,
+                        start_position=-len(prefix),
+                        display=path,
+                        display_meta=meta,
+                    )
+                return
+
+        # / command completion at start of input
+        stripped = text.lstrip()
+        if stripped.startswith("/") or stripped == ".":
+            for cmd in COMMANDS:
+                if cmd.startswith(stripped):
+                    yield Completion(
+                        cmd,
+                        start_position=-len(stripped),
+                        display=cmd,
+                    )

iclaw/config.py

@@ -0,0 +1,15 @@
+import json
+from pathlib import Path
+
+CONFIG_PATH = Path.home() / ".config" / "iclaw" / "config.json"
+TOKEN_REFRESH_INTERVAL = 24 * 60  # seconds
+
+
+def load_github_token():
+    if not CONFIG_PATH.exists():
+        return None
+    try:
+        config = json.loads(CONFIG_PATH.read_text())
+        return config.get("github_token")
+    except json.JSONDecodeError:
+        return None