# Tinker Training Debugger

Diagnoses slow, hanging or poor-quality Tinker training runs and deployment errors.

- Repository: https://github.com/thinking-machines-lab/tinker-cookbook (4231 stars)
- Category: Data and ML
- License: Apache-2.0
- Last updated: 2026-10-30
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add thinking-machines-lab/tinker-cookbook --skill debug -g -a claude-code -y`
Codex: `npx skills add thinking-machines-lab/tinker-cookbook --skill debug -g -a codex -y`
Cursor: `npx skills add thinking-machines-lab/tinker-cookbook --skill debug -g -a cursor -y`
Gemini CLI: `npx skills add thinking-machines-lab/tinker-cookbook --skill debug -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add thinking-machines-lab/tinker-cookbook`

## Description

Diagnose training issues with Tinker, slow steps, hanging sessions, output mismatches, error messages, renderer problems, and deployment issues. Use this skill whenever a user reports that training is slow, steps take too long, sessions are hanging, model outputs differ between Tinker and external engines (vLLM, SGLang), they get a confusing error message, training quality is poor (high KL, bad outputs), or they suspect something is wrong. Also trigger when users ask "is this a Tinker issue or my issue?", "is Tinker down?", report unexpected wait times, see output quality regressions, get opaque errors, or want to profile/debug their training or deployment pipeline. This skill walks through systematic triage to determine root cause.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Tinker Debug

Systematic triage for training and deployment issues. Five triage paths:
1. **Performance issues**, slow steps, hanging sessions, throughput problems
2. **Output correctness issues**, mismatches between Tinker sampling and external inference engines
3. **Service availability**, "is Tinker down?" quick diagnostics
4. **Renderer issues**, wrong tokens, training quality degradation, prompt mismatches
5. **Error message decoder**, mapping opaque errors to root causes

Identify which category the user's problem falls into, then follow the appropriate triage.

## How the Tinker SDK works (essential context)

Understanding the SDK's threading model is key to diagnosing most issues. The SDK runs a **background thread** with its own asyncio event loop. All network I/O, heartbeats, and API result polling happen on this thread.

```
┌─────────────────────┐     ┌──────────────────────────────┐
│     Main Thread      │     │      SDK Background Thread    │
│  (user code)         │     │  (asyncio event loop)         │
│                      │     │                               │
│  fb = tc.fwd_bwd_   │────>│  HTTP POST /forward_backward  │
│       async(data)    │     │  → returns request_id         │
│                      │     │                               │
│  # prepare next      │     │  Long-poll /retrieve_future   │
│  # batch here...     │     │  (HTTP 408 = not ready yet)   │
│                      │     │                               │
│  result = fb.result()│<────│  Result arrives → resolve     │
│  # blocks until done │     │                               │
│                      │     │  Heartbeat every 10s          │
└─────────────────────┘     └──────────────────────────────┘
```

The rest: https://github.com/thinking-machines-lab/tinker-cookbook/blob/HEAD/skills/debug/SKILL.md