claudetools/.grok

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.

Future / polish

• Make the hook JSON more robust across PATH/bash resolution (full exe path or a small finder launcher).
• Full parity in recover_grok_session.py (chat turns, exact file edits via search_replace equivalents, Ollama prose).
• Self-check updates to explicitly verify .grok/hooks/ and .grok/skills/ presence (or treat as capability).
• Consider a small generator script or "grokify" command to keep the thin wrappers in sync if command docs change significantly.
• Optional deeper .grok/agents/ mirrors if you want Grok-specific subagent personas for the coding agents defined in .claude/agents/.

All changes here are additive and keep the single source of truth in .claude/.

See also: CLAUDE.md (the behavioral contract, loaded by both drivers), the self-check skill, and .claude/HOOKS.md.