Claude Code (Clawdbot)

Use the locally installed Claude Code CLI reliably.

This skill supports two execution styles:

Headless mode (non-interactive): best for normal prompts and structured output.
Interactive mode (tmux): required for slash commands like /speckit.* (Spec Kit), which can hang or be killed when run via headless -p.

This skill is for driving the Claude Code CLI, not the Claude API directly.

Quick checks

Verify installation:

claude --version

Run a minimal headless prompt (prints a single response):

./scripts/claude_code_run.py -p "Return only the single word OK."

Core workflow

1) Run a headless prompt in a repo

cd /path/to/repo
/home/ubuntu/clawd/skills/claude-code-clawdbot/scripts/claude_code_run.py \
  -p "Summarize this project and point me to the key modules." \
  --permission-mode plan

2) Allow tools (auto-approve)

Claude Code supports tool allowlists via --allowedTools. Example: allow read/edit + bash:

./scripts/claude_code_run.py \
  -p "Run the test suite and fix any failures." \
  --allowedTools "Bash,Read,Edit"

3) Get structured output

./scripts/claude_code_run.py \
  -p "Summarize this repo in 5 bullets." \
  --output-format json

4) Add extra system instructions

./scripts/claude_code_run.py \
  -p "Review the staged diff for security issues." \
  --append-system-prompt "You are a security engineer. Be strict." \
  --allowedTools "Bash(git diff *),Bash(git status *),Read"

Notes (important)

After correcting Claude Code's mistakes: Always instruct Claude Code to run:

"Update your CLAUDE.md so you don't make that mistake again."

This ensures Claude Code records lessons learned and avoids repeating the same errors.
Claude Code sometimes expects a TTY.
Headless: this wrapper uses script(1) to force a pseudo-terminal.
Slash commands (e.g. /speckit.*) are best run in interactive mode; this wrapper can start an interactive Claude Code session in tmux.
Use --permission-mode plan when you want read-only planning.
Keep --allowedTools narrow (principle of least privilege), especially in automation.

High‑leverage Claude Code tips (from the official docs)

1) Always give Claude a way to verify (tests/build/screenshots)

Claude performs dramatically better when it can verify its work. Make verification explicit in the prompt, e.g.:

“Fix the bug and run tests. Done when npm test passes.”
“Implement UI change, take a screenshot and compare to this reference.”

2) Explore → Plan → Implement (use Plan Mode)

For multi-step work, start in plan mode to do safe, read-only analysis:

./scripts/claude_code_run.py -p "Analyze and propose a plan" --permission-mode plan

Then switch to execution (acceptEdits) once the plan is approved.

3) Manage context aggressively: /clear and /compact

Long, mixed-topic sessions degrade quality.

Use /clear between unrelated tasks.
Use /compact Focus on <X> when nearing limits to preserve the right details.

4) Rewind aggressively: /rewind (checkpoints)

Claude checkpoints before changes. If an approach is wrong, use /rewind (or Esc Esc) to restore:

conversation only
code only
both

This enables “try something risky → rewind if wrong” loops.

5) Prefer CLAUDE.md for durable rules; keep it short

Best practice is a concise CLAUDE.md (global or per-project) for:

build/test commands Claude should use
repo etiquette / style rules that differ from defaults
non-obvious environment quirks

Overlong CLAUDE.md files get ignored.

6) Permissions: deny > ask > allow (and scope matters)

In .claude/settings.json / ~/.claude/settings.json, rules match in order: deny first, then ask, then allow. Use deny rules to block secrets (e.g. .env, secrets/**).

7) Bash env vars don’t persist; use CLAUDE_ENV_FILE for persistence

Each Bash tool call runs in a fresh shell; export FOO=bar won’t persist. If you need persistent env setup, set (before starting Claude Code):

export CLAUDE_ENV_FILE=/path/to/env-setup.sh

Claude will source it before each Bash command.

8) Hooks beat “please remember” instructions

Use hooks to enforce deterministic actions (format-on-edit, block writes to sensitive dirs, etc.) when you need guarantees.

9) Use subagents for heavy investigation / independent review

Subagents can read many files without polluting the main context. Use them for broad codebase research or post-implementation review.

10) Treat Claude as a Unix utility (headless, pipes, structured output)

Examples:

cat build-error.txt | claude -p "Explain root cause" 
claude -p "List endpoints" --output-format json

This is ideal for CI and automation.

Interactive mode (tmux)

If your prompt contains lines starting with / (slash commands), the wrapper defaults to auto → interactive.

Example:

./scripts/claude_code_run.py \
  --mode auto \
  --permission-mode acceptEdits \
  --allowedTools "Bash,Read,Edit,Write" \
  -p $'/speckit.constitution ...\n/speckit.specify ...\n/speckit.plan ...\n/speckit.tasks\n/speckit.implement'

It will print tmux attach/capture commands so you can monitor progress.

Spec Kit end-to-end workflow (tips that prevent hangs)

When you want Claude Code to drive Spec Kit end-to-end via /speckit.*, do not use headless -p for the whole flow. Use interactive tmux mode because:

Spec Kit runs multiple steps (Bash + file writes + git) and may pause for confirmations.
Headless runs can appear idle and be killed (SIGKILL) by supervisors.

Prerequisites (important)

Initialize Spec Kit (once per repo)

specify init . --ai claude

Ensure the folder is a real git repo (Spec Kit uses git branches/scripts):

git init
git add -A
git commit -m "chore: init"

Recommended: set an origin remote (can be a local bare repo) so git fetch --all --prune won’t behave oddly:

git init --bare ../origin.git
git remote add origin ../origin.git
git push -u origin main || git push -u origin master

Give Claude Code enough tool permissions for the workflow:

Spec creation/tasks/implement need file writes, so include Write.
Implementation often needs Bash.

Recommended:

--permission-mode acceptEdits --allowedTools "Bash,Read,Edit,Write"

Run the full Spec Kit pipeline

./scripts/claude_code_run.py \
  --mode interactive \
  --tmux-session cc-speckit \
  --permission-mode acceptEdits \
  --allowedTools "Bash,Read,Edit,Write" \
  -p $'/speckit.constitution Create project principles for quality, accessibility, and security.\n/speckit.specify <your feature description>\n/speckit.plan I am building with <your stack/constraints>\n/speckit.tasks\n/speckit.implement'

Monitoring / interacting

The wrapper prints commands like:

tmux ... attach -t <session> to watch in real time
tmux ... capture-pane ... to snapshot output

If Claude Code asks a question mid-run (e.g., “Proceed?”), attach and answer.

Operational gotchas (learned in practice)

1) Vite + ngrok: "Blocked request. This host (...) is not allowed"

If you expose a Vite dev server through ngrok, Vite will block unknown Host headers unless configured.

Vite 7 expects server.allowedHosts to be true or string[].
- ✅ Allow all hosts (quick):
```
server: { host: true, allowedHosts: true }
```
- ✅ Allow just your ngrok host (safer):
```
server: { host: true, allowedHosts: ['xxxx.ngrok-free.app'] }
```
- ❌ Do not set allowedHosts: 'all' (won't work in Vite 7).

After changing vite.config.*, restart the dev server.

2) Don’t accidentally let your shell eat your prompt

When you drive tmux via a shell command (e.g. tmux send-keys ...), avoid unescaped backticks and shell substitutions in the text you pass. They can be interpreted by your shell before the text even reaches Claude Code.

Practical rule:

Prefer sending prompts from a file, or ensure the wrapper/script quotes prompt text safely.

3) Long-running dev servers should run in a persistent session

In automation environments, backgrounded vite / ngrok processes can get SIGKILL. Prefer running them in a managed background session (Clawdbot exec background) or tmux, and explicitly stop them when done.

OpenSpec workflow (opsx)

OpenSpec is another spec-driven workflow (like Spec Kit) powered by slash commands (e.g. /opsx:*). In practice it has the same reliability constraints:

Prefer interactive tmux mode for /opsx:* commands (avoid headless -p for the whole flow).

Setup (per machine)

Install CLI:

npm install -g @fission-ai/openspec@latest

Setup (per project)

Initialize OpenSpec with tool selection (required):

openspec init --tools claude

Tip: disable telemetry if desired:

export OPENSPEC_TELEMETRY=0

Recommended end-to-end command sequence

Inside Claude Code (interactive):

/opsx:onboard
/opsx:new <change-name>
/opsx:ff (fast-forward: generates proposal/design/specs/tasks)
/opsx:apply (implements tasks)
/opsx:archive (optional: archive finished change)

If the UI prompts you for project type/stack, answer explicitly (e.g. “Web app (HTML/JS) with localStorage”).

Bundled script

scripts/claude_code_run.py: wrapper that runs the local claude binary with a pseudo-terminal and forwards flags.