llm-tools/.grok/context.md

# Grok CLI Context Guide for this Repository (llm-tools)

This document provides persistent context, best practices, and usage patterns for Grok CLI Agent mode when working in this repository. It is automatically included in context (via .grok/context.md convention or explicit inclusion) to keep interactions model-provider agnostic, efficient, and aligned with the tools/skills here.

## Core Principles
- **Provider Agnostic**: All documentation, prompts, and workflows should work for Claude, Grok, or any MCP-compatible LLM. Avoid platform-specific assumptions (e.g., prefer MCP tools over Claude-only skills where possible). Update README.md, SKILL.md, and sub-READMEs accordingly.
- **MCP-First**: Leverage the built-in MCP tools exposed in Grok CLI (prefixed `mcp_dicom-mcp__*`, `mcp_filesystem-mcp__*`, `mcp_playwright-mcp__*`, `mcp_selenium-mcp__*`, `mcp_github__*`, `mcp_us-weather-mcp__*`, etc.). These map directly to the MCP servers in `./mcps/`.
- **Sub-Agent System**: Use the `task` tool proactively:
  - `general`: Multi-step execution, editing, implementation.
  - `explore`: Fast read-only research, reviews, "how does this work?".
  - `verify`: Sandbox-aware builds, tests, validation.
  - `computer`: Desktop interaction (snapshots, clicks, typing, screenshots).
  - Prefer `delegate` for long-running read-only background work.
- **Workflow Priorities** (from system instructions):
  1. Understand the request.
  2. Decide on sub-agent for investigation (default to `task` for review/research/bug triage/verification).
  3. Use `read_file`, `bash` for direct exploration (small tasks).
  4. `bash` with `background=true` for servers/watchers.
  5. `delegate` for parallel read-only work.
  6. `edit_file` (surgical), `write_file` (new/full rewrites).
  7. Verify with reads, tests, builds.
  8. `search_web`/`search_x` for up-to-date info.
- **Tool Preferences**:
  - File ops: Dedicated `read_file`/`write_file`/`edit_file` over bash.
  - Edits: `edit_file` for targeted changes (unique old_string + context); `write_file` only for new files or full overwrites.
  - Background: Use for dev servers; manage with `process_*` tools.
  - Schedules: Use `schedule_*` tools for recurring tasks.
  - Images/Video: `generate_image`/`generate_video`.
  - Payments/Wallet: `wallet_*`, `paid_request`, `fetch_payment_info`.
  - Desktop: `computer_*` tools (snapshot first for stable @e refs).
  - MCP: Call directly (e.g., `mcp_dicom-mcp__dicom_summarize_directory`); see individual MCP READMEs for params.
- **Context Management**: This file + `.grokignore` keep context lean. Avoid loading binaries, large dirs, or node_modules. Explicitly include key files (README.md, SKILL.md, specific MCP docs) when needed.

## Key Directories & When to Use
- **mcps/**: Launch MCP servers via scripts (e.g., `bash mcps/dicom_mcp/run_dicom_mcp_server.sh`). Use corresponding `mcp_*` tools in Grok.
  - dicom_mcp: QA for DICOM (Dixon, SNR, metadata, rendering, validation). Start here for medical imaging tasks. See mcps/dicom_mcp/README.md + docs/.
  - Others: filesystem (ops), open_meteo (weather), playwright/selenium (browser automation/testing).
- **skills/**: Reusable agent instructions. Read `SKILL.md` files for patterns (e.g., mcp-builder for new MCPs, artifacts-builder for UIs, document-skills for Office/PDF). Adapt YAML frontmatter + guidelines into prompts or custom tools. `mcp-builder/SKILL.md` is especially valuable for extending this repo.
- **config/** & **.claude/**: Claude-specific; update paths in claude_desktop_config.json for cross-machine use. Ignore for Grok workflows.
- **.mcp.json**: Registers MCPs for Claude Code; useful reference for tool signatures.

## Best Practices for Grok CLI in this Repo
- **Exploration**: `task` with `explore` agent first for reviews/research ("review this change", "how does MCP X work?"). Follow with `general` for edits.
- **Verification**: Always use `verify` sub-agent for builds/tests/smoke tests before/after changes.
- **Editing**: Quote sufficient unique context in `edit_file`. Verify by re-reading the file.
- **DICOM QA**: Prefer `mcp_dicom-mcp__*` tools (e.g., `dicom_summarize_directory`, `dicom_compute_snr`, `dicom_render_image`). Use `dicom_read_pixels` + `dicom_compute_snr` with ROIs identified via render.
- **Browser Automation**: Choose playwright-mcp for modern snapshots/eval; selenium-mcp for multi-session or specific WebDriver needs. Combine with `computer_*` if testing desktop apps.
- **Avoid**: Loading entire node_modules, large image/DICOM dirs (use .grokignore), or Claude-only phrasing. For long research, `delegate` to `explore`.
- **Extending**: Follow skills/mcp-builder/SKILL.md phases (research/planning → implementation → evaluation). Use mcp_github__* tools for PRs/commits if working on remote repos.
- **Scheduling**: Use `schedule_create` for recurring checks (e.g., daily DICOM validation or security scans).

## Quick MCP Tool Examples (Grok CLI)
- Summarize DICOM dir: `mcp_dicom-mcp__dicom_summarize_directory` (directory=..., recursive=true).
- Filesystem write: `mcp_filesystem-mcp__write_file` (after setting default if needed).
- Browser: `mcp_playwright-mcp__browser_navigate` or `mcp_selenium-mcp__selenium_navigate`.
- Weather: `mcp_uk-weather-mcp__get_forecast` or open-meteo equivalent.

Refer to this file in prompts: "Follow the Grok CLI context in .grok/context.md, the updated README.md, and relevant SKILL.md files. Keep all outputs provider-agnostic."

Update this context.md as the repo evolves (e.g., new MCPs, refined workflows). For full tool list, inspect available tools or run `grep -o 'mcp_[^ ]*' -r . --include="*.py" | sort | uniq`.