# Set up Claude Code + "check with Claude" (brief for Grok Bot)

> **For the human:** Send this file to your Grok Bot and say: **"set this up for me."**
> Your bot will ask you a few questions along the way (a go-ahead to install, confirming your Claude plan, signing in). This is a DIY workflow, not an official Grok Bot or Anthropic integration.

---

## 0. Instructions to the bot (read first)

You are the Grok Bot. Follow this brief step by step. Do the checks and steps in order. **Skip any step already done** (each step has a check). At every **🛑 STOP-AND-ASK**, stop and ask the human in chat, then wait for their answer. Do not assume consent. Obey the **Hard safety rules** (section 9) at all times.

Official docs this brief is based on (cite them when you explain things):
- Setup / install: https://code.claude.com/docs/en/setup
- CLI reference (`-p`, `--remote-control`, `claude auth`): https://code.claude.com/docs/en/cli-reference
- Remote Control: https://code.claude.com/docs/en/remote-control

Anything marked **[unverified]** is not confirmed by those docs. Tell the human it is unconfirmed and prefer the safe fallback.

---

## 1. Goal and success criteria

**Goal:** Install and sign in to Claude Code on your own Linux computer, add a small wrapper script, and save a reusable skill so that when the human says **"check with Claude"** you can (a) get a quick answer, or (b) start a live Claude Code session and give the human a link to continue it on claude.ai/code or the Claude mobile app.

**Done when ALL of these are true:**
1. `claude --version` prints a version number.
2. `claude auth status` shows the human is logged in (exit code 0) with the `claude.ai` auth method.
3. `claude -p "Reply with the single word: ready"` returns a reply.
4. `~/.local/bin/gb-claude` exists, is executable, and matches section 5, Step 4.
5. A test session started with the wrapper shows Remote Control active, and you have a session link to give the human.
6. A skill named `check with Claude` is saved (section 7).
7. You told the human what was done, what was skipped, and what is still unverified.

---

## 2. Preflight checks (do these before changing anything)

Run each and note the result. Nothing here changes the system.

```bash
command -v curl && echo "curl OK" || echo "curl MISSING"
command -v tmux && echo "tmux OK" || echo "tmux MISSING"
command -v claude && claude --version || echo "claude NOT INSTALLED"
claude auth status --text 2>&1 || echo "NOT LOGGED IN (or claude missing)"
test -x ~/.local/bin/gb-claude && echo "wrapper exists" || echo "wrapper missing"
echo "$PATH" | tr ':' '\n' | grep -qx "$HOME/.local/bin" && echo "PATH has ~/.local/bin" || echo "PATH lacks ~/.local/bin"
```

Decide what to skip:
- `claude --version` works → **skip Step 1 (install)**.
- `claude auth status` exits 0 with auth method `claude.ai` → **skip Step 2 (sign in)**. If it shows `api_key`, `oauth_token` or another method, you need a claude.ai sign-in for Remote Control (see Troubleshooting).
- Wrapper exists and matches → **skip Step 4**.
- Claude Code cannot run on this OS, e.g. not Ubuntu 20.04+, Debian 10+, Alpine 3.19+, or with less than 4 GB RAM → tell the human and stop (per the setup docs' system requirements).

### 🛑 STOP-AND-ASK #1: paid plan
Ask the human: *"Claude Code needs a paid Claude plan (Pro, Max, Ultra, Team or Enterprise). The free plan doesn't include it. Do you have one on the account you'll sign in with? If it's Team or Enterprise, an admin must also turn on Remote Control. Remote Control doesn't work with API keys."*
Do not continue until they confirm. If no, stop and tell them what they need.

### 🛑 STOP-AND-ASK #2: go-ahead to install
Before installing anything (Claude Code, tmux or curl), tell the human exactly what you will install and where (Claude Code goes to `~/.local/bin/claude` and `~/.local/share/claude`; tmux/curl via the system package manager), and ask for an explicit "yes". If they say no, stop. If tmux or curl is missing, installing them (e.g. `sudo apt install tmux curl` on Debian/Ubuntu) also needs this go-ahead. If you don't have permission to install system packages, tell the human.

---

## 3. Step 1: Install Claude Code (skip if already installed)

Only after STOP #1 and #2.

```bash
curl -fsSL https://claude.ai/install.sh | bash
```
The installer prints no progress while it downloads, so wait for it to finish. Then open a fresh shell (or `export PATH="$HOME/.local/bin:$PATH"`).

**Verify:**
```bash
claude --version
```
**Expected:** prints a version like `2.1.xxx (Claude Code)`. If "command not found", add `~/.local/bin` to PATH (see Troubleshooting). Optional extra check: `claude doctor` (read-only diagnostics).

---

## 4. Step 2: Sign in (skip if already logged in)

Check first:
```bash
claude auth status --text
```
Logged in with `claude.ai` auth (exit 0) → skip to Step 3.

### 🛑 STOP-AND-ASK #3: sign-in approval
Tell the human: *"I'm going to start the Claude sign-in. I'll give you a link to open in your own browser and approve with your own Claude account. Then I'll need a code from you. OK?"* Wait for yes.

### Sign-in procedure (headless login)

> **[unverified]** The official docs say to sign in with `claude auth login` (it opens a browser). They do **not** document how to complete login on a computer with no browser, or how a code gets back to the terminal. The steps below are the safe fallback I have used. Tell the human this part is unconfirmed, and if it doesn't work, stop and report (don't improvise with tokens).

1. Start the login in a detached tmux session, so it can wait for the code. Use `BROWSER=echo` so it prints the URL instead of trying to open a browser **[unverified]**:
   ```bash
   tmux kill-session -t gb-login 2>/dev/null
   tmux new-session -d -s gb-login -x 220 -y 50 "BROWSER=echo claude auth login; exec bash"
   sleep 6
   tmux capture-pane -p -J -S -50 -t gb-login
   ```
2. Find the sign-in URL in the captured screen. Pick the claude.ai option if the CLI asks for a login method (not Console/API billing).
3. **Send the human only the URL.** Ask them to open it in their own browser, sign in, approve, and copy the code shown.
4. Ask for the code **through your secure/masked secret input** (the bot's private secret or form request, never plain chat if such an input exists). **If no secure input exists**, tell the human the risk and ask them whether they want to paste it in chat anyway. A sign-in code is short-lived, but treat it as sensitive.
5. Type it into the pane (without echoing it back anywhere):
   ```bash
   tmux send-keys -t gb-login -l "<CODE>"
   tmux send-keys -t gb-login Enter
   ```
6. Wait a few seconds, then capture the pane to see success or failure. **Never print the code or any token in chat or logs.**
7. Close the temporary login session: `tmux kill-session -t gb-login`.

**Verify:**
```bash
claude auth status --text; echo "exit=$?"
```
**Expected:** shows logged in, exit `0`, auth method `claude.ai`. If not, see Troubleshooting. Don't loop on failed codes. After two failed attempts, ask the human.

Docs: Remote Control does **not** work with API keys or with long-lived tokens from `claude setup-token`. Don't use those.

---

## 5. Step 3 and 4: Test `-p`, then write the wrapper

### Step 3: Quick one-shot test
```bash
claude -p "Reply with the single word: ready"
```
**Expected:** a short reply containing "ready". `-p` prints one answer and exits (no live session). If it errors about login, redo Step 2.

### Step 4: Wrapper script, written only if missing or different

Target path: `~/.local/bin/gb-claude`. Write the intended content to a temp file, and compare:

```bash
mkdir -p ~/.local/bin
cat > /tmp/gb-claude.new <<'SCRIPT'
#!/usr/bin/env bash
# Usage: gb-claude "<name>" [workdir]
# Starts a named Claude Code session with Remote Control in a detached tmux session.
# Prints the tmux session name.
name="${1:?name required}"
dir="${2:-$PWD}"
slug="gb-$(echo "$name" | tr -cs 'A-Za-z0-9' '-' | cut -c1-30)"

tmux new-session -d -s "$slug" -x 220 -y 50 -c "$dir" \
  "export PATH=\$HOME/.local/bin:\$PATH; claude --remote-control 'GB: $name'; exec bash"

echo "$slug"
SCRIPT

if [ -f ~/.local/bin/gb-claude ] && cmp -s /tmp/gb-claude.new ~/.local/bin/gb-claude; then
  echo "wrapper already up to date - skip"
else
  [ -f ~/.local/bin/gb-claude ] && echo "WRAPPER EXISTS BUT DIFFERS"
fi
```

- Missing → install it: `install -m 0755 /tmp/gb-claude.new ~/.local/bin/gb-claude`
- Exists but differs → **do not overwrite silently.** Show the human a `diff -u ~/.local/bin/gb-claude /tmp/gb-claude.new` summary and ask whether to replace it (back up the old one first: `cp ~/.local/bin/gb-claude ~/.local/bin/gb-claude.bak`).

**Verify:**
```bash
test -x ~/.local/bin/gb-claude && bash -n ~/.local/bin/gb-claude && echo "wrapper OK"
```
**Expected:** `wrapper OK`.

Notes: the name `GB: ` prefix lets the human spot bot-started sessions. Keep session names to letters, numbers and spaces. A quote in the name breaks the script.

---

## 6. Step 5: Remote Control test session

### 🛑 STOP-AND-ASK #4: folder trust
Choose a **scratch or project folder the human has approved** (for the test: create an empty folder like `~/claude-test`, and tell the human). Never use the home directory or a folder with secrets. If the folder isn't one the human already approved, ask: *"Claude Code will ask whether to trust the folder `<folder>`. Do you approve me trusting it?"* Wait for yes.

```bash
mkdir -p ~/claude-test
S=$(~/.local/bin/gb-claude "Setup test" ~/claude-test); echo "$S"
sleep 8
tmux capture-pane -p -J -t "$S"
```

Read the screen and act:
- **Folder-trust prompt** (text such as "trust this folder" / "Yes, I trust this folder"): the docs confirm the dialog exists but **option order changes between versions** and a "No / exit" option exists. **Read the screen, identify which numbered option is "Yes, I trust this folder", and press that.** Only do so after STOP #4 approval. (`tmux send-keys -t "$S" Enter` selects the highlighted option; use `Down` first only if the highlighted option is not the "Yes" one.) Re-capture to confirm.
- **First-run theme/welcome screens:** press Enter to continue.
- **"Enable Remote Control?" or similar one-time confirmation:**

### 🛑 STOP-AND-ASK #5: enabling Remote Control
If Claude asks to enable Remote Control, ask the human: *"Remote Control lets you open this session from claude.ai/code or the Claude app. It stores the session transcript (messages, replies, tool activity) on Anthropic's servers while connected. Enable it?"* If yes, accept it in the pane. If no, stop (the link feature won't work).

**Verify the session is connected:**
```bash
tmux capture-pane -p -J -S -100 -t "$S" | grep -iE "remote-control|/rc|claude.ai/code"
```
**Expected:** an indicator like `/rc active` or a line with a `https://claude.ai/code/...` URL. If you see no URL, send `/remote-control` into the pane to open the status panel which shows the URL:
```bash
tmux send-keys -t "$S" -l "/remote-control"; tmux send-keys -t "$S" Enter; sleep 3
tmux capture-pane -p -J -S -100 -t "$S"
```
(The exact `/remote-control is active …` wording is **[unverified]**. The docs mention an `/rc active` indicator and the `/remote-control` panel.) The indicator is hidden if the terminal is too narrow, and the wrapper uses 220 columns.

Give the human the session link and tell them: *"Open it at claude.ai/code, or find the session named 'GB: Setup test' under Code in the Claude mobile app."* Remind them the link is private.

Then ask whether to keep or close the test session. **Close it only if they say so:** `tmux kill-session -t "$S"`.

---

## 7. Save the reusable skill

Save a skill named **`check with Claude`** with this text. (Use your skill-saving ability. If you can't save skills, put it in your notes/memory and tell the human.)

````markdown
---
name: check-with-claude
description: >-
  When the user asks me to check with Claude, ask Claude, or start a Claude /
  Claude Code chat or session for a task.
---
# Check with Claude (Claude Code on my own computer)

Claude Code is installed at `~/.local/bin/claude` and signed in to the user's own Claude account.

## Rules
- Every live session must have Remote Control on and a name starting with `GB: `. Always start live sessions with `~/.local/bin/gb-claude "<name>" [workdir]`; never run plain interactive `claude` outside tmux.
- Only use folders the user has approved. Never use the home directory.
- Never print or share tokens or sign-in codes. Never use --dangerously-skip-permissions.
- Treat session links as private; send them only to the user.
- Close a session (`tmux kill-session -t <name>`) only when the user asks.

## Quick question (one answer, no live session)
Run `claude -p "<question>"` and relay the answer in plain words.

## Live chat or session (default for "check with Claude" / "start a chat")
1. Pick a short topic name (letters/numbers/spaces), e.g. `Trip planning script`.
2. Run `~/.local/bin/gb-claude "<name>" <approved folder>`. It prints the tmux session name.
3. Wait ~8 seconds; run `tmux capture-pane -p -J -t <tmux name>`.
   - Folder-trust prompt: if the folder isn't one the user approved, ask them first. Otherwise read the screen, find the option "Yes, I trust this folder", and select it (option order varies by version).
   - Any one-time "Enable Remote Control?" prompt: ask the user first if they haven't agreed before.
4. Send the prompt: `tmux send-keys -t <tmux name> -l "<prompt>"`, then `tmux send-keys -t <tmux name> Enter`.
5. Poll the reply: wait, then `tmux capture-pane -p -J -S -200 -t <tmux name>`; repeat every ~10-20s until Claude has finished (the screen stops changing and shows its prompt). If it asks for permission to run something, relay the request and ask the user.
6. Get the session link from the `/rc active` indicator or by sending `/remote-control` into the pane.
7. Reply with Claude's answer in plain words plus the session link.

## Not signed in
If `claude auth status` exits non-zero: ask the user's approval, run `claude auth login` in a tmux session, send the user the printed URL, get the code via the secure input, type it into the pane, and verify with `claude auth status`.
````

**Verify:** you can list or find the skill by name. **Expected:** it exists. Tell the human they can now say "check with Claude".

---

## 8. Run procedure (every time the human says "check with Claude")

Decision rule:
- **Short factual or advice question, no files or session needed** → `claude -p "<question>"` and relay the answer.
- **Coding task, repo work, long task, or "start a chat/session"** → wrapper + tmux session:
  1. Choose an approved folder (ask if unsure) and a short topic name.
  2. `S=$(~/.local/bin/gb-claude "<name>" "<folder>")`
  3. `sleep 8; tmux capture-pane -p -J -t "$S"` and **read the screen**.
  4. Trust prompt → STOP #4 rule: ask if the folder isn't approved; otherwise select "Yes, I trust this folder" (read the screen, not blind keys).
  5. Send the prompt with `tmux send-keys -t "$S" -l "<prompt>"` then `tmux send-keys -t "$S" Enter`.
  6. Poll with `tmux capture-pane -p -J -S -200 -t "$S"` every 10–20s. Done when output stops changing and the input prompt returns.
  7. If Claude asks for permission to run a command or edit files, tell the human what it wants and let them decide. Don't approve on their behalf unless they told you to for that task.
  8. Return **Claude's answer + the session link** (private).
  9. Leave the session running. Close only when the human asks.

---

## 9. Troubleshooting (if → then)

- **`claude: command not found`** → open a new shell or `export PATH="$HOME/.local/bin:$PATH"`; add that line to the shell profile (ask first). If still missing, rerun Step 1 (after the go-ahead). Run `claude doctor`.
- **`claude auth status` exits 1 / not logged in** → Step 2 (with STOP #3).
- **Auth method is `api_key`, `oauth_token` or `api_key_helper`** → Remote Control needs a claude.ai subscription login. Tell the human. If `ANTHROPIC_API_KEY` or `ANTHROPIC_AUTH_TOKEN` is set, ask before unsetting it, then redo `claude auth login` with the claude.ai option.
- **"Remote Control requires a claude.ai subscription"** → same as above.
- **"Remote Control requires a full-scope login token"** → a `setup-token` token is in use. Ask the human, then `claude auth login` for a normal sign-in.
- **"Remote Control is disabled by your organization's policy"** → on Team/Enterprise, an admin must enable it. On a personal plan, ask the human before `claude auth logout` then `claude auth login`. Report if it persists.
- **"Remote Control isn't enabled for this account" / "Couldn't verify eligibility"** → run `claude doctor`. Check network/proxy. On an outdated version, `claude update` (ask first), then retry.
- **Remote Control unavailable and `ANTHROPIC_BASE_URL`, Bedrock, Vertex or Foundry settings exist** → these block Remote Control. Tell the human. Don't change them without asking.
- **No session link visible** → send `/remote-control` into the pane; make sure the window is wide (220 columns); re-capture.
- **Session shows offline on web/phone** → `tmux ls`. If the session is gone, start a new one with the wrapper. (Remote Control needs the `claude` process to keep running.)
- **Screen unchanged for a long time** → capture the pane. It is probably waiting on a trust, permission or Remote Control prompt. Handle per the STOP rules, or ask the human.
- **`tmux: command not found`** → STOP #2, then install tmux.
- **tmux session name already exists** → pick a different topic name, or ask before killing the old one.
- **Wrapper missing/different** → Step 4 rules.
- **Login code rejected or expired** → restart the login (kill `gb-login`, redo Step 2). After 2 failures, ask the human.
- **Anything not covered** → read the official docs (links at top) and tell the human what you found. Don't guess with risky commands.

---

## 10. Hard safety rules (never break these)

1. **Never reveal tokens, sign-in codes, or credentials**, in chat, logs, screenshots or files. Don't echo them back.
2. **Never use `--dangerously-skip-permissions`** (or any flag that skips permission prompts).
3. **Scope to project folders** the human approved. Never run sessions in the home directory or a folder with secrets. Never trust a folder without STOP #4.
4. **Close sessions only when asked.**
5. **Don't install anything without the human's explicit go-ahead.**
6. **Treat session links as private.** Send them only to the human; never post them anywhere public.
7. **Don't approve Claude's own permission prompts** (running commands, editing files) on the human's behalf unless they told you to for that task. Relay them instead.
8. **Don't use API keys or `setup-token` tokens** to work around login problems.
9. **Don't change files outside what this brief describes** (the wrapper, the skill, scratch folders) without asking. Back up before overwriting.
10. **Say what's unverified.** Report any step marked [unverified], and any place where you had to improvise.
11. Remember usage limits: sessions use the human's Claude plan allowance (check with `/usage` inside a session). Don't run long unattended sessions without asking.

---

## 11. Final report to the human (send when done)

Tell them in plain words: what you installed or skipped; sign-in status; wrapper status; skill saved; whether the Remote Control test worked (and give the private session link); what's [unverified] (headless login, exact `/remote-control is active` wording, trust-prompt option order); and a one-line reminder: *"Say 'check with Claude' followed by your question or task."*
