claudetools/.grok/README.md

Grok + ClaudeTools coexistence

This directory holds Grok-specific configuration and hooks for when the ClaudeTools harness is driven by the xAI Grok TUI/CLI instead of (or in addition to) Anthropic Claude Code.

Why it exists

The core value of ClaudeTools (coord API for locks/messages/todos/components, SOPS vault, shared .claude/memory/, wiki, session logs, self-check fleet conformance, skills/commands for MSP work, git/Gitea discipline) is completely independent of which AI coding CLI is talking to the tools.

Grok has first-class compatibility for many Claude Code artifacts:

• Loads CLAUDE.md (and friends) as project rules.
• Scans .claude/settings.json for hooks (configurable).
• Scans ~/.claude/skills/ etc.

We add this .grok/ tree so Grok can participate fully in the dynamic parts of the harness (per-prompt coord injection, safety blocks, memory sync, recovery) without forking the bash scripts that are the single source of truth.

Hooks

.grok/hooks/claudetools.json wires:

• SessionStart → .claude/scripts/sync-memory.sh (keeps profile memory in sync with the git-tracked repo store)
• UserPromptSubmit → .claude/scripts/check-messages.sh (injects unread coord messages + dev-mode active locks; output appears in hook annotations / scrollback)
• PreToolUse (for terminal) → .claude/hooks/block-backslash-winpath.sh (the famous "don't write D:\path with backslashes in Git Bash" guard)

The JSON sets GROK_WORKSPACE_ROOT and CLAUDE_PROJECT_DIR so the existing scripts "just work" under either driver.

After adding/changing hooks:

• In a Grok session: /hooks-trust (first time for the project), then /hooks or Ctrl+L to inspect/reload.

Recovery

.claude/scripts/recover_grok_session.py (MVP) + updates to recover.md let you turn a crashed/unsaved Grok session (the UUID dirs under ~/.grok/sessions/<slug>/) back into a standard ClaudeTools session log that /save, wiki tools, etc. understand.

The Claude recover script remains for Claude Code transcripts. Dispatcher logic can be unified later.

Vault, Gitea, Coord, everything else

All accessed the same way:

• Vault: .claude/scripts/vault.sh (reads vault_path from .claude/identity.json)
• Gitea: normal git (remote set during onboarding) + any API calls via tokens from vault/1Password
• Coord: the same no-auth HTTP calls from the bash scripts and from model instructions in CLAUDE.md

When you run tools from Grok (run_terminal_command etc.), you are in a normal shell context and can invoke the full harness.

Session IDs

We continue to use HOSTNAME/claude-main (or the value in identity + check-messages) as the conventional "primary interactive session" id on this host for the coord API. This has already been used successfully by Grok sessions. It keeps locks and messages unified across driver switches on the same machine.

If you run Claude Code and Grok concurrently for different work, consider the implications for lock visibility.

Slash Commands (Skills)

The ClaudeTools slash commands live in .claude/commands/*.md (e.g. /save, /checkpoint, /sync, /rmm, /self-check, /remediation-tool, etc.). These are prompt + workflow definitions that extend the AI with MSP-specific capabilities (session logging, remote execution, wiki, PSA integration, etc.).

They are fully transferrable to Grok.

We have created native Grok skills at .grok/skills/<name>/SKILL.md for every command:

• Each has proper frontmatter (name:, description: with trigger phrases like "Use when the user says /save...").
• This makes them appear automatically as first-class Grok slash commands (/save, /rmm, etc.) via Grok's project skill discovery (.grok/skills/ at repo root is scanned).
• The body delegates to the authoritative source: "Read .claude/commands/<name>.md using the read_file tool and follow it, adapting for Grok tools (run_terminal_command instead of Bash, spawn_subagent for delegation, etc.)."
• Grok's description field drives auto-invocation and the /name shorthand, exactly like the original Claude Code custom commands.

This keeps the single source of truth in .claude/commands/ (and the detailed skills in .claude/skills/ where applicable, e.g. self-check, remediation-tool). The .grok/skills/ versions are thin, compatible adapters + discovery enablers.

After changes:

• In a Grok session, the skills should be picked up on load/restart (use /skills to list, or just type /save etc.).
• The launcher/system prompt may still inject the originals for now; the .grok/ versions take precedence for native Grok behavior.
• Test with /skills save or directly /save.

See the individual SKILL.md files for examples (they all follow the same "read the .claude source + adapt tools + obey CLAUDE.md" pattern).

Making Grok Remember Things (Like Claude's Memory)

In Claude Code, you "tell it to remember" via project docs, memory features, or session context that gets saved.

Grok equivalents (hybrid with ClaudeTools):

• Project Rules (always loaded): Edit CLAUDE.md (Grok scans it for compatibility, along with AGENTS.md etc.). Instructions here apply to every session in the repo/tree. We added the Windows bash fix details there. Deeper subdir rules override.

• Grok Native Memory (if enabled):

  • Enable persistently: [memory] enabled = true in ~/.grok/config.toml (we did this).
  • In chat: Say "remember that [fact]" — it saves to ~/.grok/memory/<workspace-slug>/MEMORY.md (or global).
  • Commands: /memory (browse/edit), /flush (save rich summary), "what do you remember?", "forget X".
  • Auto-saves session summaries.
  • We seeded global and workspace memory with the bash mapping note.

• Skills: Create .grok/skills/<topic>/SKILL.md with name: and descriptive description:. Becomes /name command and auto-triggers on matching prompts. We created .grok/skills/windows-bash/SKILL.md specifically for the bash issue (and it appears in the skills list).

• ClaudeTools Shared Memory (recommended for team/repo): The primary persistent knowledge is in .claude/memory/ (index in MEMORY.md, individual .md files like feedback_*.md), CLAUDE.md, wiki/, session-logs/, and the ensure-git-bash.ps1 + profile. Grok is instructed (via CLAUDE.md and skills) to check these first. The .claude/scripts/sync-memory.sh keeps things in sync. Add "remember" style notes by editing/creating files there, then reference in CLAUDE.md or a skill.

• For this bash fix: It's now "remembered" at multiple layers:

  • OS level: Profile + helper script.
  • Docs: CLAUDE.md, .claude/memory/feedback_windows_bash_mapping.md (indexed), .grok/README.md.
  • Grok native: .grok/skills/windows-bash/SKILL.md + seeded MEMORY.md entries.
  • Future sessions (Grok or Claude) will see the fix via context loading rules in CLAUDE.md.

To "tell Grok" in future: Describe the fact, and we (or you via /memory if on) will persist it to the appropriate file/skill. Restart Grok session after edits to rules/memory for full effect (or use /reload if available).

See also: .claude/CLAUDE.md (Automatic Context Loading, memory sections), Grok user-guide 12-project-rules.md and 13-memory.md, and the new windows-bash skill.

MCP Servers (GrepAI and others)

Grok has first-class native MCP support (see ~/.grok/docs/user-guide/07-mcp-servers.md).

MCP servers (including the GrepAI semantic search server) are configured in:

• Global: ~/.grok/config.toml under [mcp_servers.<name>]
• Project-scoped (this repo): .grok/config.toml (higher priority for Grok than global; only [mcp_servers] section is used here)

Grok also loads for compatibility (lower priority):

• .mcp.json (the vendor-neutral file used by Claude Code)
• Claude/Cursor formats

For GrepAI specifically (semantic code + context searches):

We added .grok/config.toml (native Grok TOML) with the grepai server entry:

[mcp_servers.grepai]
command = "D:\\claudetools\\grepai.exe"
args = ["mcp-serve"]
enabled = true

This is the exact equivalent of the entry in .mcp.json, but expressed in Grok's preferred native config format. It lives only in .grok/ so Claude's .mcp.json (and its MCP loading) is untouched and continues to work exactly as before.

Using GrepAI for context searches in Grok:

• Tools are exposed as grepai__grepai_search, grepai__grepai_trace_callers, grepai__grepai_trace_callees, grepai__grepai_index_status, grepai__grepai_stats, etc.
• Discovery + invocation: use the built-in search_tool (to list/find by keyword/desc) then use_tool with the fully-qualified name and exact schema params.
• MANDATORY per harness (CLAUDE.md + .claude/standards/context-lookup/grepai-first.md, which Grok loads): For any context lookup, "what did we do with X", "how is Y configured", semantic search over code/session-logs/wiki/skills, or before read_file / grep / list_dir on source files — call grepai__grepai_search (or trace tools) first. Only fall back to direct file tools when you need the full verbatim content for editing.
• CLI fallback (if MCP not handy): D:/claudetools/grepai.exe search "query" --json -c -n 5
• The index covers the full repo + session logs with boosts for .claude/, session-logs/, clients/, etc. (see .claude/OLLAMA.md for the exact overrides applied on this machine).
• In /mcps modal (or Ctrl+L) you can toggle, inspect status, see tools.

This gives Grok the same (or better, native) access to GrepAI for context that Claude gets, with zero changes to Claude's working config.

See also: .grok/skills/context/SKILL.md (updated to enforce), .claude/standards/context-lookup/grepai-first.md, the grepai watcher task, and grepai.exe status.

Automatic Context Loading for Grok (same ability as Claude)

Grok has the exact same automatic context loading as Claude because:

• Grok natively loads CLAUDE.md (and AGENTS.md etc.) as always-in project rules (deeper subdirs win).
• We have mirrored/enforced the GrepAI-first rule everywhere (.grok/config.toml for native MCP, .grok/skills/context/SKILL.md with full trigger table + MSP example, .grok/README.md, all skills/agents, .grok/standards/README.md pointing to grepai-first standard).
• .grok/ pointers for memory history (.grok/memory/README.md for .claude/memory/ feedback files), references, standards, etc.
• Native GrepAI MCP (higher prio via .grok/config.toml) + CLI for semantic searches before any read_file/grep.
• Context skill + deep-explore agent + backup agent for discovery.
• Full delegation to shared wiki/clients/, projects/, systems/, session-logs/, CONTEXT.md, coord, B2 skill, etc.

When you say something like "Go ahead and remove that machine from MSP backups" (with implied glaztech + SBS):

Grok will (via the enhanced context skill + rules):

1. Detect triggers: "mspbackups" (B2/MSP storage + RMM backup status), client "glaztech" (or machine name), "remove machine" (SBS).
2. GrepAI-first: search_tool + use_tool (grepai__grepai_search "SBS glaztech mspbackups backup machine remove B2 key prefix") to find relevant chunks in code, logs, memory, wiki.
3. Load wiki/clients/glaztech.md FIRST, then clients/glaztech/ (session-logs, backup docs, README, DEPLOYMENT etc.).
4. Load mspbackups context: .grok/skills/b2/SKILL.md (Grok mirror of .claude/skills/b2/), RMM migrations for mspbackups_integration + multi_provider_backup, .claude/agents/backup.md , .claude/memory/ references to mspbackups/B2 rate, account structure (MSPBackups20200311 bucket etc.).
5. Find the specific machine: Search for SBS in glaztech files, RMM agents, backup prefixes (e.g. in MSP360/CloudBerry destinations or glaztech bucket). Use GrepAI + RMM /rmm skill if needed.
6. For the removal action: Use b2 skill (Grok version) to list buckets/keys/files for the machine's backup prefix/key, then gated delete-key / delete-prefix / delete-bucket --confirm (as per b2 safety). Update RMM backup status if applicable.
7. Update context: Append to clients/glaztech/session-logs/ (new dated file or existing), update wiki/clients/glaztech.md if infrastructure changes, add feedback to .claude/memory/ if new lesson (or .grok/memory/), claim coord lock if significant, use /save or checkpoint.
8. Never ask for info already in wiki/CONTEXT.md/logs/memory/coord.

This is explicitly documented in the updated .grok/skills/context/SKILL.md (full trigger table + MSP example) and .grok/README.md.

See CLAUDE.md "Automatic Context Loading (CRITICAL)" for the source table (Grok loads it). Use GrepAI MCP for "mspbackups" + client + machine in any such request.

Full Grok Equivalents / Mirroring (without touching originals)

Following the GrepAI/MCP native config pattern, we have created thin .grok/ equivalents for all other commands, references, memory history, skills, agents, standards, docs, etc. that Claude Code uses. All additive in .grok/ tree; originals in .claude/ (and shared scripts/hooks/memory/wiki/etc.) untouched.

Commands

• .grok/skills/<all 25+ from .claude/commands/>/SKILL.md (already present from initial coexistence setup + updates): thin adapters. Read .claude/commands/.md + adapt tools (run_terminal_command etc.), obey CLAUDE.md + GrepAI-first.

Skills (the advanced .claude/skills/ ones)

• Created .grok/skills/ thin SKILL.md for all that lacked them: b2, bitdefender, frontend-design, gc-audit, impeccable, memory-dream, packetdial, rmm-audit, skill-creator, stop-slop, theme-factory (self-check and remediation-tool already had mirrors).
• Pattern: copy frontmatter, "Read the .claude/skills//SKILL.md (GrepAI MCP first), follow adapting for Grok tools (run_terminal_command with bash mapping, spawn_subagent, search_tool/use_tool for MCP/grepai, etc.)."

Agents (subagent personas)

• Created .grok/agents/README.md + thin .md for key ones (deep-explore, coding, code-review, backup, gitea, database, documentation-squire, testing) + pointers for the rest (video-analysis, photo, dos-coding, code-fixer, the ST_ enhancements, quick ref, DB info).
• "See .claude/agents/.md ; adapt for Grok tools and GrepAI-first."

References, Memory History, Standards, Docs

• Created .grok/ thin pointers: REFERENCE.md, RECOVERY.md, OLLAMA.md, MCP_SERVERS.md, HOOKS.md, ONBOARDING.md .
• .grok/memory/README.md : points to .claude/memory/ (the "memory history" feedback_*.md , MEMORY.md etc. — use GrepAI for them, sync-memory bridges to Grok native ~/.grok/memory/).
• .grok/standards/README.md : points to .claude/standards/ (including the critical context-lookup/grepai-first.md); use via inject-standards skill (which has .grok/ mirror) + GrepAI.
• Machines/ and other fleet docs: referenced via identity + CLAUDE.md context loading + GrepAI; .claude/machines/ are the source.

Other

• .grok/config.toml : native MCP (grepai and future) — higher prio for Grok than .mcp.json compat layer.
• .grok/skills/self-check/SKILL.md : enhanced to call out .grok/ artifacts (config, agents, skills mirrors, pointer docs, memory) for Grok machine census/baseline.
• All new/updated files mandate GrepAI MCP (search_tool + use_tool for grepai__*) + the full harness rules (CLAUDE.md, git-bash, vault, coord "each time", no emojis, additive only, etc.).
• .grok/hooks/ already provided the hook equivalents.

This gives Grok native first-class access to the entire harness (commands via /name skills, skills via auto / , agents via spawn_subagent with .grok/ personas, references/memory via GrepAI + pointers + CLAUDE.md loading, MCP via native config + /mcps) exactly parallel to Claude, but without any changes to Claude's files or behavior.

See the individual files for details. Restart Grok TUI / reload skills/hooks after changes. Use /self-check to validate the new .grok/ pieces are seen on this machine.

Future / polish