sprite

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sprite Skill

Sprite 技能

Manage Sprites.dev remote VMs with checkpoint/restore — and critically, control an InnerClaude from OuterClaude.

通过Checkpoint恢复功能管理Sprites.dev远程虚拟机，更重要的是，通过OuterClaude控制InnerClaude。

Quick Start: Ask InnerClaude Something

快速开始：向InnerClaude提问

Copy-paste this. Tested Jan 2026.

bash

undefined

直接复制粘贴以下内容，已在2026年1月测试通过。

bash

undefined

Get token from Mac Keychain (or ask user for one)

从Mac钥匙串获取令牌（或向用户索要）

TOKEN=$(security find-generic-password -a claude-sprite -s CLAUDE_CODE_OAUTH_TOKEN -w)

Create tmux session and start Claude (literal paths, no escaping!)

创建tmux会话并启动Claude（使用字面路径，不要转义！）

sprite exec -tty bash -c 'tmux kill-session -t innerClaude 2>/dev/null; tmux new-session -d -s innerClaude -x 150 -y 50' sprite exec -tty bash -c "tmux send-keys -t innerClaude 'source /.sprite/languages/node/nvm/nvm.sh && nvm use default && export CLAUDE_CODE_OAUTH_TOKEN=$TOKEN && export TERM=xterm-256color && claude' Enter" sprite exec -tty bash -c 'tmux pipe-pane -t innerClaude "cat > /tmp/claude-output.txt"' sleep 25

Approve workspace trust dialog

批准工作区信任对话框

sprite exec -tty bash -c 'tmux send-keys -t innerClaude Enter' sleep 15

Send your message (TWO ENTERS to submit!)

发送消息（需要按两次Enter提交！）

sprite exec -tty bash -c 'tmux send-keys -t innerClaude "Write a haiku about recursion" Enter Enter' sleep 30

sprite exec -tty bash -c 'tmux send-keys -t innerClaude "写一首关于递归的俳句" Enter Enter' sleep 30

Read response

读取响应

sprite exec -tty bash -c 'cat /tmp/claude-output.txt | strings | tail -60'

Cleanup

清理

sprite exec -tty bash -c 'tmux kill-session -t innerClaude'


**Key gotchas:** Use literal NVM path (no `$NVM_DIR`), TWO Enters to submit messages, `security` runs on local Mac not sprite.

---

sprite exec -tty bash -c 'tmux kill-session -t innerClaude'


**关键注意事项**：使用字面NVM路径（不要用`$NVM_DIR`），发送消息需按两次Enter，`security`命令在本地Mac而非sprite虚拟机上运行。

---

When to Use

适用场景

OuterClaude/InnerClaude pattern — Testing workflows, install flows, or any scenario where Claude controls Claude
Remote development — Running code on persistent Ubuntu VMs
Checkpoint/restore workflows — Snapshotting and restoring VM state
Bootstrap new sprites — First-time setup with auth and tools

OuterClaude/InnerClaude模式 — 测试工作流、安装流程或任何Claude控制Claude的场景
远程开发 — 在持久化Ubuntu虚拟机上运行代码
Checkpoint恢复工作流 — 快照和恢复虚拟机状态
初始化新Sprite — 首次设置认证和工具

When NOT to Use

不适用场景

Local development — Just use terminal directly
Simple sprite commands —
```
sprite list
```
,
```
sprite console
```
don't need this skill
Claude Code Web — Different product (ephemeral VMs, not Sprites.dev)
Non-sprite servers — Use server-checkup skill instead

本地开发 — 直接使用终端即可
简单sprite命令 —
```
sprite list
```
、
```
sprite console
```
无需使用此技能
Claude Code Web — 不同产品（临时虚拟机，非Sprites.dev）
非Sprite服务器 — 改用server-checkup技能

OuterClaude Pattern (Primary Use Case)

OuterClaude模式（主要用例）

This pattern enables you (OuterClaude) to operate an InnerClaude on a sprite as if you were the human user. Use for testing workflows, install patterns, or Claude-to-Claude interaction.

此模式允许你（OuterClaude）像人类用户一样操作Sprite上的InnerClaude。适用于测试工作流、安装模式或Claude与Claude之间的交互。

Mental Model

思维模型

You (OuterClaude) are the user. InnerClaude is a CLI tool you're operating.

This framing is critical:

When you see InnerClaude's output → you're reading what a human would see
When you send input → you're typing what a human would type
Resist the instinct to "be" InnerClaude — you're operating it

你（OuterClaude）是用户，InnerClaude是你操作的CLI工具。

这个框架至关重要：

当你看到InnerClaude的输出时 → 你正在查看人类用户会看到的内容
当你发送输入时 → 你正在输入人类用户会键入的内容
不要本能地“成为”InnerClaude — 你是在操作它

Prerequisites: Authentication

前提条件：认证

Claude needs a valid OAuth token to start. Without it, Claude exits silently — no error message, no node process, just an empty output file.

Critical insight: Checkpoints don't persist environment variables. Even if you created a checkpoint right after authenticating, the token won't be there on restore. You must export it fresh every time.

Before starting the Working Loop, you need a token. Either:

Retrieve from Keychain (local Mac):

security find-generic-password -a claude-sprite -s CLAUDE_CODE_OAUTH_TOKEN -w

Get one from the user: Ask them to provide
```
CLAUDE_CODE_OAUTH_TOKEN
```
Run setup-token flow on sprite: See Auth Setup section below

To store a token in Keychain (recommended, runs on your Mac not the sprite):

bash

undefined

Claude需要有效的OAuth令牌才能启动。 没有令牌的话，Claude会静默退出 — 无错误消息、无node进程，只有空的输出文件。

关键提示：Checkpoint不会保留环境变量。即使你在认证后创建了Checkpoint，恢复后令牌也会消失。每次都必须重新导出令牌。

在开始工作循环之前，你需要一个令牌，可以通过以下方式获取：

从钥匙串获取（本地Mac）：

security find-generic-password -a claude-sprite -s CLAUDE_CODE_OAUTH_TOKEN -w

向用户索要：请求用户提供
```
CLAUDE_CODE_OAUTH_TOKEN
```
在Sprite上运行setup-token流程：参见下方的认证设置部分

将令牌存储在钥匙串中（推荐，在你的Mac上运行而非Sprite）：

bash

undefined

Run locally on Mac (OuterClaude side) — NOT on the sprite!

在本地Mac上运行（OuterClaude端）—— 不要在Sprite上运行！

security add-generic-password -a "claude-sprite" -s "CLAUDE_CODE_OAUTH_TOKEN" -w "<your-token>" -U


**To verify auth will work before starting:**
```bash
sprite exec -tty bash -c 'source /.sprite/languages/node/nvm/nvm.sh && nvm use default && export CLAUDE_CODE_OAUTH_TOKEN=<token> && claude --version'

If this returns a version number, auth is good. If it says "Invalid API key", the token is expired/invalid.

security add-generic-password -a "claude-sprite" -s "CLAUDE_CODE_OAUTH_TOKEN" -w "<你的令牌>" -U


**在启动前验证认证是否有效**：
```bash
sprite exec -tty bash -c 'source /.sprite/languages/node/nvm/nvm.sh && nvm use default && export CLAUDE_CODE_OAUTH_TOKEN=<令牌> && claude --version'

如果返回版本号，说明认证有效；如果显示“Invalid API key”，则令牌已过期或无效。

The Working Loop

工作循环

ESCAPING WARNING: Variable expansion like

$NVM_DIR

gets mangled through multiple shell layers. Always use literal paths to avoid escaping hell.

bash

undefined

转义警告：

$NVM_DIR

这样的变量扩展会在多层shell中被破坏。始终使用字面路径以避免转义问题。

bash

undefined

1. Create tmux session on sprite (use -tty for proper TTY allocation!)

1. 在Sprite上创建tmux会话（使用-tty来正确分配TTY！）

sprite exec -tty bash -c 'tmux new-session -d -s innerClaude -x 150 -y 50'

2. Set up environment + token + start Claude IN ONE COMMAND

2. 一次性设置环境+令牌+启动Claude

CRITICAL: Use literal path /.sprite/languages/node/nvm/nvm.sh (no $NVM_DIR variable!)

关键：使用字面路径/.sprite/languages/node/nvm/nvm.sh（不要用$NVM_DIR变量！）

Fetch token locally on Mac, then interpolate into the sprite command

在本地Mac获取令牌，然后插入到Sprite命令中

TOKEN=$(security find-generic-password -a claude-sprite -s CLAUDE_CODE_OAUTH_TOKEN -w) sprite exec -tty bash -c "tmux send-keys -t innerClaude 'source /.sprite/languages/node/nvm/nvm.sh && nvm use default && export CLAUDE_CODE_OAUTH_TOKEN=$TOKEN && export TERM=xterm-256color && claude' Enter"

3. Set up pipe-pane for output capture (capture-pane doesn't work!)

3. 设置pipe-pane以捕获输出（capture-pane无效！）

sprite exec -tty bash -c 'tmux pipe-pane -t innerClaude "cat > /tmp/claude-output.txt"' sleep 25 # Claude needs 20-30 seconds to fully start

sprite exec -tty bash -c 'tmux pipe-pane -t innerClaude "cat > /tmp/claude-output.txt"' sleep 25 # Claude需要20-30秒才能完全启动

4. Verify Claude started (should be >1000 bytes if running)

4. 验证Claude是否启动（如果运行，文件大小应>1000字节）

sprite exec -tty bash -c 'wc -c /tmp/claude-output.txt'

5. Read captured output (strings filters escape codes into readable text)

5. 读取捕获的输出（strings命令将转义码过滤为可读文本）

sprite exec -tty bash -c 'cat /tmp/claude-output.txt | strings | tail -100'


**Diagnostic: If output file is tiny (<500 bytes):**
- Check for node process: `sprite exec -tty bash -c 'ps aux | grep node'`
- If no node process → auth failed. Token is invalid/expired.
- Re-run setup-token flow or get fresh token from user.

sprite exec -tty bash -c 'cat /tmp/claude-output.txt | strings | tail -100'


**诊断：如果输出文件很小（<500字节）**：
- 检查node进程：`sprite exec -tty bash -c 'ps aux | grep node'`
- 如果没有node进程 → 认证失败，令牌无效或过期
- 重新运行setup-token流程或向用户获取新令牌

Why pipe-pane, Not capture-pane

为什么用pipe-pane而不是capture-pane

tmux capture-pane
does NOT work for Claude's interactive UI. Claude uses the alternate screen buffer which

capture-pane

misses entirely.

Method	Works?	Why
`capture-pane -p`	❌	Misses alternate screen buffer
`capture-pane -a`	❌	Returns "no alternate screen"
`pipe-pane "cat > file"`	✅	Captures all output including alternate screen

Note: Raw output contains ANSI escape codes. Use

strings

to filter into readable text. The UI content IS captured, just wrapped in terminal control sequences.

tmux capture-pane
对Claude的交互式UI无效。Claude使用的是备用屏幕缓冲区，而

capture-pane

会完全错过它。

方法	是否有效	原因
`capture-pane -p`	❌	无法捕获备用屏幕缓冲区
`capture-pane -a`	❌	返回“no alternate screen”
`pipe-pane "cat > file"`	✅	捕获包括备用屏幕在内的所有输出

注意：原始输出包含ANSI转义码，使用

strings

命令过滤为可读文本。UI内容已被捕获，只是被终端控制序列包裹。

Sending Input

发送输入

TWO-ENTER PATTERN: Claude's input box requires TWO Enters:

First Enter after your text → moves to new line in input box
Second Enter → actually submits the message

bash

undefined

两次Enter模式：Claude的输入框需要按两次Enter：

输入文本后按第一次Enter → 在输入框中换行
按第二次Enter → 实际提交消息

bash

undefined

Send text to InnerClaude (types text + newline, but DOES NOT submit yet!)

向InnerClaude发送文本（输入文本+换行，但尚未提交！）

sprite exec -tty bash -c 'tmux send-keys -t innerClaude "your message here" Enter'

sprite exec -tty bash -c 'tmux send-keys -t innerClaude "你的消息内容" Enter'

THEN submit with a second Enter

然后按第二次Enter提交

sprite exec -tty bash -c 'tmux send-keys -t innerClaude Enter'

Or combine: type, newline, then submit

或者合并：输入+换行+提交

sprite exec -tty bash -c 'tmux send-keys -t innerClaude "your message here" Enter Enter'

sprite exec -tty bash -c 'tmux send-keys -t innerClaude "你的消息内容" Enter Enter'

Navigate options (for dialogs/AskUserQuestion)

导航选项（针对对话框/AskUserQuestion）

sprite exec -tty bash -c 'tmux send-keys -t innerClaude Down' # Next option sprite exec -tty bash -c 'tmux send-keys -t innerClaude Up' # Previous option

sprite exec -tty bash -c 'tmux send-keys -t innerClaude Down' # 下一个选项 sprite exec -tty bash -c 'tmux send-keys -t innerClaude Up' # 上一个选项

Approve dialog (single Enter works for dialogs - they're already focused)

批准对话框（对话框只需按一次Enter，因为已聚焦）

sprite exec -tty bash -c 'tmux send-keys -t innerClaude Enter'

Cancel dialog

取消对话框

sprite exec -tty bash -c 'tmux send-keys -t innerClaude Escape'

undefined

sprite exec -tty bash -c 'tmux send-keys -t innerClaude Escape'

undefined

Recognizing Prompts

识别提示

Prompt Type	Visual Markers	How to Respond
Workspace trust	"Do you trust the files in this folder?"	`Enter` (select Yes)
AskUserQuestion	`☐ {header}` + numbered options with `❯`	`Enter` (current) or `Down` / `Up` then `Enter`
Write permission	"Do you want to create {file}?"	`Enter` (Yes)
Edit permission	"Do you want to edit {file}?"	`Enter` (Yes)
Bash permission	"Do you want to proceed?"	`Enter` (Yes)
Ready for input	`❯` prompt at bottom	Send your next message

提示类型	视觉标记	响应方式
工作区信任	"Do you trust the files in this folder?"（你信任此文件夹中的文件吗？）	`Enter` （选择是）
AskUserQuestion	`☐ {标题}` + 带 `❯` 的编号选项	`Enter` （当前选项）或按 `Down` / `Up` 后按 `Enter`
写入权限	"Do you want to create {file}?"（你要创建{file}吗？）	`Enter` （是）
编辑权限	"Do you want to edit {file}?"（你要编辑{file}吗？）	`Enter` （是）
Bash权限	"Do you want to proceed?"（你要继续吗？）	`Enter` （是）
准备好接收输入	底部显示 `❯` 提示符	发送下一条消息

Response Codes

响应代码

Input	Meaning
`Enter`	Select highlighted option (default)
`1` , `2` , `3`	Explicit option selection
`n`	No/deny
`Escape`	Cancel dialog

输入	含义
`Enter`	选择高亮选项（默认）
`1` , `2` , `3`	明确选择对应选项
`n`	否/拒绝
`Escape`	取消对话框

Auth Setup

认证设置

If InnerClaude shows "OAuth token expired" or "Please run /login":

bash

undefined

如果InnerClaude显示“OAuth token expired”（OAuth令牌过期）或“Please run /login”（请运行/login）：

bash

undefined

Run setup-token in a tmux session

在tmux会话中运行setup-token

sprite exec -tty bash -c 'tmux send-keys -t innerClaude "/exit" Enter' sprite exec -tty bash -c 'tmux send-keys -t innerClaude "claude setup-token" Enter'

Capture the auth URL from output, open it for the user

从输出中捕获认证URL，为用户打开

After user authorizes, paste the code back:

用户授权后，粘贴代码回来：

sprite exec -tty bash -c 'tmux send-keys -t innerClaude "AUTH_CODE_HERE" Enter'

Or use environment variable for subsequent sessions:

或为后续会话设置环境变量：

export CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...

undefined

export CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...

undefined

Complete Example: Interactive Session

完整示例：交互式会话

This is the full annotated version of Quick Start. Use when you need to understand what's happening or debug issues.

bash

undefined

这是快速开始的完整注释版本，当你需要了解运行过程或调试问题时使用。

bash

undefined

0. Get token from local Mac Keychain (this runs on YOUR machine, not the sprite!)

0. 从本地Mac钥匙串获取令牌（此命令在你的机器上运行，而非Sprite！）

TOKEN=$(security find-generic-password -a claude-sprite -s CLAUDE_CODE_OAUTH_TOKEN -w)

If that fails, ask user for token: TOKEN="sk-ant-oat01-..."

如果失败，向用户索要令牌：TOKEN="sk-ant-oat01-..."

1. (Optional) Restore to virgin snapshot for clean test

1.（可选）恢复到初始快照以进行干净测试

sprite restore v11

2. Create fresh tmux session

2. 创建新的tmux会话

sprite exec -tty bash -c 'tmux kill-session -t innerClaude 2>/dev/null; tmux new-session -d -s innerClaude -x 150 -y 50'

3. Start Claude with NVM + token IN ONE COMMAND (use literal path, no $NVM_DIR!)

3. 一次性启动Claude并设置NVM+令牌（使用字面路径，不要用$NVM_DIR！）

sprite exec -tty bash -c "tmux send-keys -t innerClaude 'source /.sprite/languages/node/nvm/nvm.sh && nvm use default && export CLAUDE_CODE_OAUTH_TOKEN=$TOKEN && export TERM=xterm-256color && claude' Enter"

4. Set up pipe-pane capture and wait for startup

4. 设置pipe-pane捕获并等待启动完成

sprite exec -tty bash -c 'tmux pipe-pane -t innerClaude "cat > /tmp/claude-output.txt"' sleep 25

5. Verify Claude started (should be >1000 bytes)

5. 验证Claude是否启动（文件大小应>1000字节）

sprite exec -tty bash -c 'wc -c /tmp/claude-output.txt'

6. Check for workspace trust dialog and approve

6. 检查工作区信任对话框并批准

sprite exec -tty bash -c 'cat /tmp/claude-output.txt | strings | tail -50'

If you see "Do you trust the files in this folder?" → approve it:

如果你看到“你信任此文件夹中的文件吗？” → 批准：

sprite exec -tty bash -c 'tmux send-keys -t innerClaude Enter' sleep 15

7. Clear output and send your message (TWO ENTERS to submit!)

7. 清空输出并发送消息（需要按两次Enter提交！）

sprite exec -tty bash -c '> /tmp/claude-output.txt' sprite exec -tty bash -c 'tmux send-keys -t innerClaude "Your prompt here" Enter Enter' sleep 30

sprite exec -tty bash -c '> /tmp/claude-output.txt' sprite exec -tty bash -c 'tmux send-keys -t innerClaude "你的提示内容" Enter Enter' sleep 30

8. Read the response

8. 读取响应

sprite exec -tty bash -c 'cat /tmp/claude-output.txt | strings | tail -100'

9. For multi-turn: approve permission prompts as needed

9. 多轮对话：根据需要批准权限提示

sprite exec -tty bash -c 'tmux send-keys -t innerClaude Enter' # Approve permission

sprite exec -tty bash -c 'tmux send-keys -t innerClaude Enter' # 批准权限

Repeat steps 7-9 for additional turns

重复步骤7-9进行多轮对话

10. Cleanup

10. 清理

sprite exec -tty bash -c 'tmux kill-session -t innerClaude'

undefined

sprite exec -tty bash -c 'tmux kill-session -t innerClaude'

undefined

Common Pitfalls

常见陷阱

Pitfall	Fix
`$NVM_DIR` escaping breaks	Use literal path `/.sprite/languages/node/nvm/nvm.sh` — no variables!
Message doesn't submit	Need TWO Enters: first adds newline, second submits. Use `Enter Enter`
Token not exported in tmux session	Export `CLAUDE_CODE_OAUTH_TOKEN` INSIDE the tmux session, not just outer shell
Claude starts but output file stays tiny	Auth failed silently. Check `ps aux
Using `-p` mode for interactive dialogs	Use tmux + interactive `claude` instead
Using `capture-pane` instead of `pipe-pane`	Claude's UI needs `pipe-pane`
Not sourcing NVM before running `claude`	Add NVM setup to session init
Sending Enter before prompt renders	Always `sleep` then capture before responding
OAuth token expired	Long-lived tokens (setup-token) last ~1 year. Store in Keychain
Assuming checkpoint has valid auth	Checkpoints don't persist env vars. Export token fresh every time
`security` command on sprite	That's macOS — fetch token locally, then pass to sprite

陷阱	解决方法
`$NVM_DIR` 转义失败	使用字面路径 `/.sprite/languages/node/nvm/nvm.sh` — 不要用变量！
消息未提交	需要按两次Enter：第一次换行，第二次提交。使用 `Enter Enter`
Tmux会话中未导出令牌	在Tmux会话内部导出 `CLAUDE_CODE_OAUTH_TOKEN` ，而不仅仅是外部shell
Claude启动但输出文件很小	认证静默失败。检查`ps aux
对交互式对话框使用 `-p` 模式	改用tmux+交互式 `claude`
使用 `capture-pane` 而非 `pipe-pane`	Claude的UI需要 `pipe-pane`
运行 `claude` 前未加载NVM	在会话初始化时添加NVM设置
提示渲染前发送Enter	始终先 `sleep` 再捕获输出，然后响应
OAuth令牌过期	长期令牌（setup-token）有效期约1年，存储在钥匙串中
假设Checkpoint包含有效认证	Checkpoint不保留环境变量，每次都要重新导出令牌
在Sprite上运行 `security` 命令	这是macOS命令，Sprite是Linux — 在本地获取令牌，再传递给Sprite

Quick Reference

快速参考

Command	Purpose
`sprite list`	List all sprites
`sprite use <name>`	Set default sprite for directory
`sprite exec <cmd>`	Run command on active sprite
`sprite console`	Interactive shell (for humans)
`sprite checkpoint create`	Snapshot current state
`sprite checkpoint list`	List checkpoints
`sprite restore <id>`	Restore to checkpoint
`sprite proxy <port>`	Forward port locally

For detailed command reference: See references/commands.md

命令	用途
`sprite list`	列出所有Sprite
`sprite use <名称>`	为目录设置默认Sprite
`sprite exec <命令>`	在当前Sprite上运行命令
`sprite console`	交互式shell（面向人类）
`sprite checkpoint create`	快照当前状态
`sprite checkpoint list`	列出Checkpoint
`sprite restore <ID>`	恢复到指定Checkpoint
`sprite proxy <端口>`	本地转发端口

详细命令参考：参见references/commands.md

Setup & Bootstrap

设置与初始化引导

Fresh sprites need authentication and tool setup before use.

Quick bootstrap:

bash

sprite create my-sprite
sprite use my-sprite
sprite exec gh auth login          # GitHub auth (interactive)
sprite exec gh auth setup-git      # Enable credential helper
sprite checkpoint create --comment "Fresh with gh auth"

For full setup guide: See references/setup.md

新的Sprite在使用前需要认证和工具设置。

快速初始化：

bash

sprite create my-sprite
sprite use my-sprite
sprite exec gh auth login          # GitHub认证（交互式）
sprite exec gh auth setup-git      # 启用凭证助手
sprite checkpoint create --comment "Fresh with gh auth"

完整设置指南：参见references/setup.md

Troubleshooting

故障排除

Issue	Fix
Output file tiny, no node process	Auth failed silently. Token must be exported INSIDE tmux session
`capture-pane` shows nothing	Use `pipe-pane` instead — see OuterClaude Pattern
Claude won't start in tmux	Source NVM first — see Working Loop
"OAuth token expired" or "Invalid API key"	Get fresh token. Run setup-token flow or ask user for token
"Permission denied (publickey)"	Use HTTPS URLs, run `gh auth login`
`claude -p` returns empty	Use `sprite exec -tty` to allocate a PTY

问题	解决方法
输出文件很小，无node进程	认证静默失败，必须在Tmux会话内部导出令牌
`capture-pane` 无输出	改用 `pipe-pane` — 参见OuterClaude模式
Claude无法在Tmux中启动	先加载NVM — 参见工作循环
"OAuth token expired"或"Invalid API key"	获取新令牌，运行setup-token流程或向用户索要
"Permission denied (publickey)"	使用HTTPS URL，运行 `gh auth login`
`claude -p` 返回空	使用 `sprite exec -tty` 分配PTY

Quick Diagnostic Sequence

快速诊断流程

When InnerClaude isn't working:

bash

undefined

当InnerClaude无法工作时：

bash

undefined

1. Is there a node process?

1. 是否存在node进程？

sprite exec -tty bash -c 'ps aux | grep node | grep -v grep'

No output = Claude never started (usually auth)

无输出 = Claude从未启动（通常是认证问题）

2. What's in the output file?

2. 输出文件内容是什么？

sprite exec -tty bash -c 'wc -c /tmp/claude-output.txt'

<500 bytes = Claude exited immediately

<500字节 = Claude立即退出

3. Can Claude start at all with this token? (use literal path!)

3. 使用此令牌Claude能否启动？（使用字面路径！）

Fetch token locally (Mac), then pass to sprite

在本地Mac获取令牌，然后传递给Sprite

TOKEN=$(security find-generic-password -a claude-sprite -s CLAUDE_CODE_OAUTH_TOKEN -w) sprite exec -tty bash -c "source /.sprite/languages/node/nvm/nvm.sh && nvm use default && export CLAUDE_CODE_OAUTH_TOKEN=$TOKEN && claude -p 'hello' 2>&1"

"Invalid API key" = token expired/invalid

"Invalid API key" = 令牌过期或无效


**For full troubleshooting guide:** See [references/troubleshooting.md](references/troubleshooting.md)


**完整故障排除指南**：参见[references/troubleshooting.md](references/troubleshooting.md)

TTY Allocation: Use

-tty

Flag (Jan 2026)

TTY分配：使用

-tty

标志（2026年1月）

The fix: Always use

sprite exec -tty

when running commands that need TTY allocation (tmux, Claude, interactive tools).

bash

undefined

解决方法：运行需要TTY分配的命令（tmux、Claude、交互式工具）时，始终使用

sprite exec -tty

。

bash

undefined

CORRECT: -tty allocates a PTY

正确：-tty分配PTY

sprite exec -tty bash -c 'tmux new-session -d -s innerClaude ...'

WRONG: no TTY, pipe-pane won't capture output

错误：无TTY，pipe-pane无法捕获输出

sprite exec bash -c 'tmux new-session -d -s innerClaude ...'


**What `-tty` does:** Allocates `/dev/pts/X` so pipe-pane can capture both input AND output. Without it, you see keystrokes going in but Claude's responses are missing.

**Diagnostic (if output capture fails):**
```bash
sprite exec -tty bash -c 'tty'  # Should show /dev/pts/0 or similar

sprite exec bash -c 'tmux new-session -d -s innerClaude ...'


**`-tty`的作用**：分配`/dev/pts/X`，使pipe-pane能够捕获输入和输出。没有它，你会看到按键输入，但Claude的响应会丢失。

**诊断（如果输出捕获失败）**：
```bash
sprite exec -tty bash -c 'tty'  # 应显示/dev/pts/0或类似内容

Anti-Patterns

反模式

Pattern	Problem	Fix
Use `$NVM_DIR` variable in send-keys	Escaping hell across shell layers	Use literal `/.sprite/languages/node/nvm/nvm.sh`
Send message with single Enter	First Enter is newline, second submits	Use `Enter Enter` (type + submit)
Use `capture-pane` for Claude UI	Alternate screen buffer not captured	Use `pipe-pane`
Run `claude` without NVM setup	Node won't be in PATH	Source NVM first in tmux
Use `-p` mode for interactive testing	Can't handle dialogs	Use tmux + interactive `claude`
Assume OAuth persists across restores	Checkpoints may have stale tokens	Export `CLAUDE_CODE_OAUTH_TOKEN`
Run `security` on the sprite	`security` is macOS, sprite is Linux	Fetch token locally, pass to sprite
Use SSH URLs for git	gh credential helper needs HTTPS	Use HTTPS URLs
Skip `gh auth setup-git`	uv/pip need credential helper	Always run after `gh auth login`

模式	问题	解决方法
在send-keys中使用 `$NVM_DIR` 变量	多层shell中转义混乱	使用字面路径 `/.sprite/languages/node/nvm/nvm.sh`
按一次Enter发送消息	第一次Enter是换行，第二次才是提交	使用 `Enter Enter` （输入+提交）
对Claude UI使用 `capture-pane`	无法捕获备用屏幕缓冲区	使用 `pipe-pane`
未设置NVM就运行 `claude`	Node不在PATH中	在Tmux中先加载NVM
对交互式测试使用 `-p` 模式	无法处理对话框	使用tmux+交互式 `claude`
假设OAuth在恢复后仍有效	Checkpoint可能包含过期令牌	导出 `CLAUDE_CODE_OAUTH_TOKEN`
在Sprite上运行 `security` 命令	`security` 是macOS命令，Sprite是Linux	在本地获取令牌，再传递给Sprite
对git使用SSH URL	gh凭证助手需要HTTPS	使用HTTPS URL
跳过 `gh auth setup-git`	uv/pip需要凭证助手	总是在 `gh auth login` 后运行

Integration with Other Skills

与其他技能的集成

Complements:

server-checkup — For non-sprite Linux servers
claude-go (google-workspace skill) — Shares interaction patterns (tmux send-keys)

Virgin Snapshot Pattern: Maintain a checkpoint with Anthropic + GitHub auth but no customizations. Restore before each test:

bash

sprite restore v11  # Your virgin checkpoint ID

互补技能：

server-checkup — 针对非Sprite Linux服务器
claude-go（google-workspace skill） — 共享交互模式（tmux send-keys）

初始快照模式：维护一个包含Anthropic和GitHub认证但无自定义设置的Checkpoint。每次测试前恢复：

bash

sprite restore v11  # 你的初始Checkpoint ID