claude-code-clawdbot: Running Claude Code Headlessly Without Losing Your Mind
The Trend Is Real — But Is the Skill?
119 stars on SkillsMP with a rising trend badge. That's not viral noise — that's quiet, steady adoption from developers who ran into the same wall and found this skill before writing their own workaround. I went in skeptical. I came out with it installed.
Let me tell you what's actually here.
What This Skill Does
At its core, claude-code-clawdbot is a thin but essential wrapper around the claude CLI that makes Claude Code usable in non-interactive environments. The headline feature is scripts/claude_code_run.py, which uses script(1) to allocate a pseudo-terminal before invoking claude -p. That's it. That's the fix.
But the SKILL.md layered on top of that shim is where the real value lives. It teaches your Clawdbot agent when to use headless mode versus interactive tmux mode, how to scope tool permissions, how to get structured JSON output, and how to chain Claude Code into longer workflows like Spec Kit pipelines. It's less a skill and more a field manual for treating Claude Code like a Unix utility.
Why This Exists (The Problem It Solves)
If you've tried running claude -p "do something" from a cron job, a CI step, or any non-TTY context, you've probably hit the hang. Claude Code expects a terminal. When it doesn't get one, it either freezes waiting for input that never comes, or it exits with an error that doesn't tell you anything useful.
The naive fix — just wrapping it in a subprocess call — doesn't work reliably. The author's solution is to use script -q -c '...' /dev/null to fake a TTY. It's an old Unix trick, and it works. The wrapper handles this transparently so you don't have to think about it every time.
Beyond the TTY problem, the skill also addresses a second gap: there's no official guidance on how to integrate Claude Code into agent workflows where another AI (Clawdbot, in this case) is the orchestrator. This skill fills that gap with concrete patterns.
Key Capabilities Worth Calling Out
1. Headless mode that actually works
The pseudo-terminal shim is the foundation. Without it, none of the automation use cases are reliable. With it, you can pipe errors into Claude, get structured output back, and chain it into scripts without babysitting.
cat build-error.txt | claude -p "Explain root cause"
claude -p "List all API endpoints" --output-format json
This is the Unix philosophy applied to AI tooling, and it's genuinely useful.
2. Intelligent mode switching (headless vs. tmux interactive)
The wrapper auto-detects slash commands in your prompt and switches to tmux interactive mode. This matters because commands like /speckit.implement involve multiple steps, file writes, confirmations, and git operations — they'll hang or get killed in headless mode. The skill handles this gracefully rather than leaving you to figure it out through trial and error.
3. Tool permission scoping
The --allowedTools flag with explicit examples is something I wish more skills documented clearly. The skill pushes least-privilege by default:
--allowedTools "Bash(git diff *),Bash(git status *),Read"
That's not just a CLI flag — it's a pattern for keeping automation safe when Claude Code has write access to your codebase.
4. The CLAUDE.md feedback loop
There's a tip in the skill that I've started using: after correcting Claude Code's mistakes, tell it to update its CLAUDE.md so it doesn't repeat the error. This is simple, obvious in retrospect, and something I wasn't doing systematically before. The skill bakes this into the workflow as a reminder. Small thing, real impact.
5. Spec Kit integration
If you're using Spec Kit (specify init), this skill documents the full pipeline from /speckit.constitution through /speckit.implement with the right flags, the right git setup, and the right permission mode. This is a niche use case, but if it's your use case, the documentation here will save you a few hours of debugging.
Who Should Install This
Install this if: - You're running Claude Code in any automated context (cron, CI, agent orchestration) - You want another AI agent (like Clawdbot) to drive Claude Code as a subprocess - You're building pipelines that need structured JSON output from Claude Code - You're using Spec Kit and want end-to-end automation - You've already hit the TTY hang issue and duct-taped a fix together
Skip it if:
- You only use Claude Code interactively in a terminal — the skill adds nothing for that workflow
- You're not on a Linux/Ubuntu host (the script hardcodes /home/ubuntu/.local/bin/claude as the default path, though this is configurable)
- You're not using Clawdbot as your agent runtime — the SKILL.md is written for that specific context and may not translate cleanly to other orchestration setups
How to Install
This is a Clawdbot skill, so installation follows the standard pattern:
# Clone into your skills directory
git clone https://github.com/win4r/claude-code-clawdbot-skill \
~/.claude/skills/claude-code-clawdbot
# Verify Claude Code is installed and accessible
claude --version
# Run the sanity check
./scripts/claude_code_run.py -p "Return only the single word OK."
If claude isn't in the expected path, you'll need to adjust the script or set the path explicitly. Check the script's default path assumption (/home/ubuntu/.local/bin/claude) and update it for your environment.
Honest Concerns
The Ubuntu path assumption is a real friction point. The default claude binary path is hardcoded for an Ubuntu setup. If you're on macOS or a different Linux distro, you'll hit this immediately. It's fixable, but it's an onboarding tax that shouldn't exist. A simple environment variable override or PATH lookup would have been cleaner.
The README is bilingual (English + Chinese), which is fine, but the SKILL.md is dense. There's a lot of good information in there, but it's organized more as a reference dump than a progressive guide. First-time users might struggle to find the right entry point. The "Quick checks" section helps, but the overall structure could use a clearer "start here" path.
tmux as a dependency is implicit. Interactive mode requires tmux, but the skill doesn't check for it or tell you to install it upfront. You'll find out when it fails. This should be in the prerequisites section.
119 stars with zero movement in the last 7 days is a slightly odd signal. Rising trend badge, but no recent star activity. This might mean it hit a specific community and saturated it, or it might mean the trend data is lagging. Either way, the underlying code is functional regardless of star velocity.
Security surface area is real. When you're running --allowedTools "Bash,Read,Edit,Write" in automation, you're giving Claude Code significant filesystem access. The skill does push least-privilege defaults, but if you're deploying this in any multi-tenant or production-adjacent context, think carefully about what directories Claude Code can reach.
Verdict
Install it if you're automating Claude Code. The pseudo-terminal wrapper alone is worth it — it solves a real, annoying problem with a clean solution. The SKILL.md is genuinely informative even if you strip out the Clawdbot-specific parts and just use it as a reference for Claude Code best practices.
It's not a flashy skill. It's a plumbing skill. Those are usually the ones worth having.
Two things I'd want to see improved: fix the hardcoded Ubuntu path, and add tmux to the prerequisites. Neither is a dealbreaker, but both would reduce the "why isn't this working" friction for new users.
Bottom line: if you're orchestrating Claude Code from another agent or running it in automation, this skill is doing work you'd otherwise have to do yourself. Just check your binary path first.