From ae96aabc677467d691274a07e23c020daee0a0af Mon Sep 17 00:00:00 2001 From: Vadym Samoilenko Date: Fri, 17 Apr 2026 13:21:24 +0100 Subject: [PATCH] vault backup: 2026-04-17 13:21:24 --- 99 Daily/2026-04-17.md | 6 + raw/{ => _processed}/Troubleshooting.md | 0 .../TypeScript SDK V2 interface (preview).md | 0 wiki/_master-index.md | 4 +- wiki/agent-sdk/_index.md | 1 + wiki/agent-sdk/typescript-v2-interface.md | 150 ++++++++++ wiki/claude-code/_index.md | 1 + wiki/claude-code/troubleshooting.md | 273 ++++++++++++++++++ 8 files changed, 433 insertions(+), 2 deletions(-) rename raw/{ => _processed}/Troubleshooting.md (100%) rename raw/{ => _processed}/TypeScript SDK V2 interface (preview).md (100%) create mode 100644 wiki/agent-sdk/typescript-v2-interface.md create mode 100644 wiki/claude-code/troubleshooting.md diff --git a/99 Daily/2026-04-17.md b/99 Daily/2026-04-17.md index 54b8971..7469824 100644 --- a/99 Daily/2026-04-17.md +++ b/99 Daily/2026-04-17.md @@ -305,3 +305,9 @@ tags: [daily] - 13:20 | `Barclays-banner-builder` - **Asked:** Create an idempotent deployment script for Docker containers on Ubuntu with Apache reverse proxy and database migrations. - **Done:** Generated deploy.sh script with Docker build caching, database initialization, and Alembic migrations; committed changes and pushed to main branch. +- 13:20 | `memory-compiler` + - **Asked:** Compile a new troubleshooting article into the wiki knowledge base with structured sections and cross-references. + - **Done:** Created `wiki/claude-code/troubleshooting.md` with quick-reference error table, platform-specific diagnostics, and wikilinks to related articles. +- 13:21 (<1min) | `memory-compiler` + - **Asked:** Create and file a structured wiki article on the TypeScript V2 SDK interface into the knowledge base. + - **Done:** Wrote article covering V2 exports and usage patterns, then updated both the agent-sdk topic index and master index with new counts. diff --git a/raw/Troubleshooting.md b/raw/_processed/Troubleshooting.md similarity index 100% rename from raw/Troubleshooting.md rename to raw/_processed/Troubleshooting.md diff --git a/raw/TypeScript SDK V2 interface (preview).md b/raw/_processed/TypeScript SDK V2 interface (preview).md similarity index 100% rename from raw/TypeScript SDK V2 interface (preview).md rename to raw/_processed/TypeScript SDK V2 interface (preview).md diff --git a/wiki/_master-index.md b/wiki/_master-index.md index ded2101..a3c40a0 100644 --- a/wiki/_master-index.md +++ b/wiki/_master-index.md @@ -30,9 +30,9 @@ This 3-hop pattern works for hundreds of articles without vector search. | [[wiki/web-agency/_index\|web-agency/]] | AI-assisted website building & selling: Claude Code, Nanobanana 2, Kling, LaunchPath MCP | 1 | | [[wiki/dotfiles/_index\|dotfiles/]] | Linux terminal ricing: Kitty, Fish, WezTerm CLI, modern Rust CLI tools, LazyVim, unified themes, Tabby | 19 | -| [[wiki/agent-sdk/_index\|agent-sdk/]] | Claude Agent SDK (formerly Claude Code SDK) — build autonomous AI agents in Python and TypeScript | 27 | +| [[wiki/agent-sdk/_index\|agent-sdk/]] | Claude Agent SDK (formerly Claude Code SDK) — build autonomous AI agents in Python and TypeScript | 28 | | [[wiki/llm-models/_index\|llm-models/]] | OpenAI model catalog — GPT-5.x, o-series reasoning, audio/realtime, embeddings, moderation | 1 | -| [[wiki/claude-code/_index\|claude-code/]] | Claude Code product docs — install, capabilities, surfaces, MCP, hooks, scheduling, multi-agent, plugins, skills, channels, error recovery | 11 | +| [[wiki/claude-code/_index\|claude-code/]] | Claude Code product docs — install, capabilities, surfaces, MCP, hooks, scheduling, multi-agent, plugins, skills, channels, error recovery | 12 | diff --git a/wiki/agent-sdk/_index.md b/wiki/agent-sdk/_index.md index 9b9f228..298597a 100644 --- a/wiki/agent-sdk/_index.md +++ b/wiki/agent-sdk/_index.md @@ -41,3 +41,4 @@ Build production AI agents using the same tools, agent loop, and context managem | [[wiki/agent-sdk/subagents\|subagents]] | Spawn subagents programmatically or via filesystem; context isolation, parallelization, tool restrictions, resuming, detection | raw/Subagents in the SDK.md | 2026-04-17 | | [[wiki/agent-sdk/todo-tracking\|todo-tracking]] | Built-in TodoWrite tool: lifecycle states, automatic triggers, real-time progress display, activeForm field | raw/Todo Lists.md | 2026-04-17 | | [[wiki/agent-sdk/cost-tracking\|cost-tracking]] | Token usage tracking, deduplicating parallel tool calls, per-model cost breakdown, accumulating across sessions | raw/Track cost and usage.md | 2026-04-17 | +| [[wiki/agent-sdk/typescript-v2-interface\|typescript-v2-interface]] | V2 preview: session-based send/stream pattern, no async generators, createSession/resumeSession/prompt, cleanup | raw/TypeScript SDK V2 interface (preview).md | 2026-04-17 | diff --git a/wiki/agent-sdk/typescript-v2-interface.md b/wiki/agent-sdk/typescript-v2-interface.md new file mode 100644 index 0000000..d446f6a --- /dev/null +++ b/wiki/agent-sdk/typescript-v2-interface.md @@ -0,0 +1,150 @@ +--- +title: "TypeScript SDK V2 Interface (Preview)" +aliases: [typescript-v2, sdk-v2, agent-sdk-v2] +tags: [agent-sdk, typescript, v2, preview, sessions, multi-turn] +sources: [raw/TypeScript SDK V2 interface (preview).md] +created: 2026-04-17 +updated: 2026-04-17 +--- + +# TypeScript SDK V2 Interface (Preview) + +> **Unstable preview** — APIs may change before becoming stable. Session forking and some advanced streaming patterns remain V1-only. + +V2 removes async generators and yield coordination. Each conversation turn is a discrete `send()` / `stream()` cycle — no generator state to manage across turns. + +## Installation + +```sh +npm install @anthropic-ai/claude-agent-sdk +``` + +Same package as V1; V2 is additive under `unstable_v2_*` exports. + +## Core API Surface + +Three concepts cover the full interface: + +| Concept | Function | Purpose | +|---------|----------|---------| +| Start session | `unstable_v2_createSession()` | New conversation | +| Resume session | `unstable_v2_resumeSession(id)` | Continue a stored session | +| One-shot | `unstable_v2_prompt()` | Single-turn, no session needed | + +### SDKSession Interface + +```typescript +interface SDKSession { + readonly sessionId: string; + send(message: string | SDKUserMessage): Promise; + stream(): AsyncGenerator; + close(): void; +} +``` + +`send()` dispatches the message; `stream()` pulls the response. The explicit separation makes it easy to insert logic between turns. + +## Usage Patterns + +### One-shot prompt + +```typescript +import { unstable_v2_prompt } from "@anthropic-ai/claude-agent-sdk"; + +const result = await unstable_v2_prompt("What is 2 + 2?", { + model: "claude-opus-4-7" +}); +if (result.subtype === "success") { + console.log(result.result); +} +``` + +### Basic session (single turn) + +```typescript +import { unstable_v2_createSession } from "@anthropic-ai/claude-agent-sdk"; + +await using session = unstable_v2_createSession({ model: "claude-opus-4-7" }); + +await session.send("Hello!"); +for await (const msg of session.stream()) { + if (msg.type === "assistant") { + const text = msg.message.content + .filter((b) => b.type === "text") + .map((b) => b.text) + .join(""); + console.log(text); + } +} +``` + +`await using` (TypeScript 5.2+) auto-closes the session when the block exits. Use `session.close()` manually on older TS. + +### Multi-turn conversation + +Call `send()` again on the same session — Claude retains prior context: + +```typescript +await session.send("What is 5 + 3?"); +for await (const msg of session.stream()) { /* ... */ } + +await session.send("Multiply that by 2"); // references previous answer +for await (const msg of session.stream()) { /* ... */ } +``` + +### Session resume (across restarts) + +Capture `msg.session_id` from any streamed message, close the session, then resume later: + +```typescript +// Initial session +const session = unstable_v2_createSession({ model: "claude-opus-4-7" }); +await session.send("Remember this number: 42"); + +let sessionId: string | undefined; +for await (const msg of session.stream()) { + sessionId = msg.session_id; +} +session.close(); + +// Resume later +await using resumed = unstable_v2_resumeSession(sessionId!, { + model: "claude-opus-4-7" +}); +await resumed.send("What number did I ask you to remember?"); +for await (const msg of resumed.stream()) { /* ... */ } +``` + +## Cleanup + +| Method | When to use | +|--------|------------| +| `await using session = ...` | TypeScript 5.2+ — auto-closes on block exit | +| `session.close()` | Older TS or explicit lifecycle control | + +## V1 Features Not Yet in V2 + +- Session forking (`forkSession` option) +- Some advanced streaming input patterns + +Use [[wiki/agent-sdk/typescript-api-reference|typescript-api-reference]] (V1) for these. + +## Key Takeaways + +- **No generators** — V2 replaces the async generator / yield pattern with explicit `send()` + `stream()` per turn +- **Three exports** cover everything: `unstable_v2_createSession`, `unstable_v2_resumeSession`, `unstable_v2_prompt` +- **Session ID** is available on every `SDKMessage` as `msg.session_id` — capture it to enable resume +- **`await using`** (TS 5.2+) provides automatic resource cleanup; fall back to `.close()` otherwise +- **Unstable prefix** signals the API is a preview — don't ship production code against it without pinning the version +- **Same package** as V1 — no separate install; V1 and V2 coexist + +## Related Articles + +- [[wiki/agent-sdk/typescript-api-reference|TypeScript V1 API Reference]] — full stable API, session forking, advanced streaming +- [[wiki/agent-sdk/streaming-input|Streaming Input]] — V1 AsyncGenerator vs string input modes +- [[wiki/agent-sdk/streaming-output|Streaming Output]] — StreamEvent structure, text_delta, UI patterns +- [[wiki/agent-sdk/agent-loop|Agent Loop]] — message lifecycle, turns, compaction, sessions + +## Sources + +- `raw/TypeScript SDK V2 interface (preview).md` diff --git a/wiki/claude-code/_index.md b/wiki/claude-code/_index.md index d7164bf..75b6357 100644 --- a/wiki/claude-code/_index.md +++ b/wiki/claude-code/_index.md @@ -25,3 +25,4 @@ Claude Code is Anthropic's agentic coding assistant. Works across terminal, IDE, | [[wiki/claude-code/channels\|channels]] | Push events into a running session via MCP channels: Telegram/Discord/iMessage bridges, webhook receivers, security allowlist, enterprise controls | raw/Push events into a running session with channels.md | 2026-04-17 | | [[wiki/claude-code/headless-cli\|headless-cli]] | Run Claude Code non-interactively via `-p` flag: bare mode, structured output, streaming, tool approval, conversation resumption | raw/Run Claude Code programmatically.md | 2026-04-17 | | [[wiki/claude-code/scheduled-tasks\|scheduled-tasks]] | /loop, CronCreate/List/Delete tools, fixed vs dynamic intervals, loop.md, one-time reminders, jitter, 7-day expiry, scheduling options compared | raw/Run prompts on a schedule.md | 2026-04-17 | +| [[wiki/claude-code/troubleshooting\|troubleshooting]] | Install errors quick-ref, PATH/proxy/TLS fixes, platform issues (Linux/macOS/Windows/WSL), auth problems, performance, IDE integration | raw/Troubleshooting.md | 2026-04-17 | diff --git a/wiki/claude-code/troubleshooting.md b/wiki/claude-code/troubleshooting.md new file mode 100644 index 0000000..9d65f02 --- /dev/null +++ b/wiki/claude-code/troubleshooting.md @@ -0,0 +1,273 @@ +--- +title: "Claude Code Troubleshooting" +aliases: [claude-code-troubleshoot, claude-install-errors, claude-debug] +tags: [claude-code, troubleshooting, installation, auth, windows, wsl, linux, macos] +sources: [raw/Troubleshooting.md] +created: 2026-04-17 +updated: 2026-04-17 +--- + +# Claude Code Troubleshooting + +Quick-reference for installation failures, auth errors, performance problems, and IDE issues. + +--- + +## Installation Error Quick-Reference + +| Symptom | Fix | +|---------|-----| +| `command not found: claude` | Add `~/.local/bin` to PATH | +| `syntax error near unexpected token '<'` | Install script returned HTML (geo-block or network issue) | +| `curl: (56) Failure writing output` | Network interrupted mid-download; retry or use Homebrew/WinGet | +| `Killed` during install on Linux | OOM — add 2 GB swap | +| `TLS connect error` / `SSL/TLS secure channel` | Update CA certs; set `NODE_EXTRA_CA_CERTS` for corporate proxy | +| `Failed to fetch version` | `storage.googleapis.com` blocked; set `HTTPS_PROXY` | +| `irm is not recognized` / `&& is not valid` | Wrong shell — use correct installer for CMD/PowerShell/Bash | +| `Claude Code on Windows requires git-bash` | Install Git for Windows; set `CLAUDE_CODE_GIT_BASH_PATH` in settings | +| `Error loading shared library` | musl/glibc mismatch — reinstall with correct binary | +| `Illegal instruction` on Linux | CPU arch mismatch (ARM vs x86) — verify with `uname -m` | +| `dyld: cannot load` / `Abort trap: 6` on macOS | macOS < 13.0 or binary incompatibility — update macOS | +| `App unavailable in region` | Country not supported | + +--- + +## Install Diagnostics + +### Network check +```bash +curl -sI https://storage.googleapis.com # installer downloads from here +``` + +### Proxy setup (corporate networks) +```bash +export HTTP_PROXY=http://proxy.example.com:8080 +export HTTPS_PROXY=http://proxy.example.com:8080 +curl -fsSL https://claude.ai/install.sh | bash +``` + +### PATH fix (macOS/Linux) +```bash +# Zsh +echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc + +# Bash +echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc +``` + +### Conflicting installs +```bash +which -a claude # find all claude binaries +npm uninstall -g @anthropic-ai/claude-code # remove npm install +brew uninstall --cask claude-code # remove Homebrew install +``` + +### Directory permissions +```bash +test -w ~/.local/bin && echo "writable" || echo "not writable" +sudo mkdir -p ~/.local/bin && sudo chown -R $(whoami) ~/.local +``` + +--- + +## Platform-Specific Issues + +### Linux: Low-memory install failure (`Killed`) +Claude Code requires ≥ 4 GB RAM. Add swap: +```bash +sudo fallocate -l 2G /swapfile +sudo chmod 600 /swapfile && sudo mkswap /swapfile && sudo swapon /swapfile +curl -fsSL https://claude.ai/install.sh | bash +``` + +### Linux: musl/glibc mismatch +```bash +ldd /bin/ls | head -1 # shows "linux-vdso" (glibc) or "musl" +# On Alpine (musl): +apk add libgcc libstdc++ ripgrep +``` + +### macOS: `dyld` errors +- Requires macOS 13.0+. Check: Apple menu → About This Mac +- Fallback: `brew install --cask claude-code` + +### Docker: Install hangs +```dockerfile +WORKDIR /tmp +RUN curl -fsSL https://claude.ai/install.sh | bash +``` +Add `--memory=4g` if using Docker Desktop. + +### Windows: Shell mismatch +| Shell | Command | +|-------|---------| +| PowerShell | `irm https://claude.ai/install.ps1 \| iex` | +| CMD | `curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd` | +| WinGet | `winget install Anthropic.ClaudeCode` | + +### Windows: Claude Desktop overrides CLI +Update Claude Desktop to latest — older versions register `Claude.exe` that shadows the CLI. + +### Windows: Git Bash required +Install from [git-scm.com](https://git-scm.com/downloads/win). If already installed: +```json +{ "env": { "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe" } } +``` + +### WSL2 Issues +- **Node from Windows PATH**: `which npm` should point to `/usr/` not `/mnt/c/` — use nvm in Linux +- **OAuth login**: `export BROWSER="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"` +- **JetBrains not detected**: Add Windows Firewall rule for WSL2 subnet, or set `networkingMode=mirrored` in `.wslconfig` +- **Sandboxing**: `sudo apt-get install bubblewrap socat`; WSL1 does not support sandboxing + +--- + +## Authentication & Permissions + +### Repeated permission prompts +Use `/permissions` to allowlist specific tools. + +### Auth flow reset +``` +/logout → close → reopen claude → re-authenticate +``` +If browser doesn't open: press `c` to copy OAuth URL. + +### OAuth: Invalid code +Token expired or truncated — press Enter to retry quickly after browser opens. + +### 403 Forbidden +- Claude Pro/Max: check subscription at claude.ai/settings +- Console users: verify "Claude Code" or "Developer" role assigned +- Proxy users: see [[wiki/claude-code/mcp-integration|MCP & network config]] + +### Model not found +Check model setting priority (highest wins): +1. `--model` flag +2. `ANTHROPIC_MODEL` env var +3. `.claude/settings.local.json` +4. `.claude/settings.json` +5. `~/.claude/settings.json` + +Run `/model` inside Claude to pick from available models. + +### Disabled org with active subscription +Stale `ANTHROPIC_API_KEY` overriding subscription credentials: +```bash +unset ANTHROPIC_API_KEY +claude +# remove from ~/.zshrc or ~/.bashrc permanently +``` + +### macOS Keychain issues +```bash +claude doctor # check Keychain access +security unlock-keychain ~/Library/Keychains/login.keychain-db +``` + +### Token expired frequently +Check system clock accuracy — token validation is time-sensitive. + +--- + +## Configuration Files + +| File | Purpose | +|------|---------| +| `~/.claude/settings.json` | User settings (permissions, hooks, model overrides) | +| `.claude/settings.json` | Project settings (committed) | +| `.claude/settings.local.json` | Local project settings (not committed) | +| `~/.claude.json` | Global state (theme, OAuth, MCP servers) | +| `.mcp.json` | Project MCP servers (committed) | + +### Full reset +```bash +rm ~/.claude.json && rm -rf ~/.claude/ && rm -rf .claude/ && rm .mcp.json +``` + +--- + +## Performance & Stability + +### High CPU/memory +- Run `/compact` regularly +- Restart between major tasks +- Add build dirs to `.gitignore` +- Run `/heapdump` → inspect `.heapsnapshot` in Chrome DevTools + +### Auto-compaction thrashing +`Autocompact is thrashing` = a single file keeps refilling context. Fix: +- Ask Claude to read file in smaller chunks (line ranges, functions) +- `/compact keep only the plan and the diff` +- Move large-file work to a [[wiki/claude-code/custom-subagents|subagent]] +- `/clear` to start fresh + +### Search not working (`@file`, custom skills) +Install system ripgrep: +```bash +brew install ripgrep # macOS +winget install BurntSushi.ripgrep.MSVC # Windows +sudo apt install ripgrep # Ubuntu/Debian +apk add ripgrep # Alpine +``` +Then set `USE_BUILTIN_RIPGREP=0` in environment. + +### WSL: Slow / incomplete search +Move project to Linux filesystem (`/home/`) instead of `/mnt/c/`. + +--- + +## IDE Integration + +### JetBrains: Escape key not working +Settings → Tools → Terminal → uncheck "Move focus to the editor with Escape" + +### JetBrains: Not detected on WSL2 +Option 1 — Windows Firewall rule: +```powershell +New-NetFirewallRule -DisplayName "Allow WSL2 Internal Traffic" -Direction Inbound -Protocol TCP -Action Allow -RemoteAddress 172.21.0.0/16 -LocalAddress 172.21.0.0/16 +``` +Option 2 — mirrored networking in `.wslconfig`: +```ini +[wsl2] +networkingMode=mirrored +``` + +--- + +## Markdown Formatting Issues + +- Code blocks missing language tags → ask: "Add appropriate language tags to all code blocks" +- Use PostToolUse hooks to auto-run `prettier` on generated markdown +- Document preferred style in `CLAUDE.md` (see [[wiki/claude-code/overview|overview]]) + +--- + +## Diagnostics Command + +``` +/doctor +``` +Checks: install type, version, search, auto-update, settings JSON validity, MCP config errors, keybindings, context warnings, plugin loading. + +--- + +## Key Takeaways + +- **`command not found`** almost always means `~/.local/bin` is not in PATH — add it to shell config +- **Corporate networks**: set `HTTP_PROXY`/`HTTPS_PROXY` and `NODE_EXTRA_CA_CERTS` before installing +- **Linux OOM**: add swap before installing on low-RAM VPS; Claude Code needs ≥ 4 GB +- **macOS requires 13.0+**; use Homebrew as fallback install method on any platform +- **Windows**: use the right installer for your shell (PowerShell vs CMD vs WSL) +- **Auth problems**: try `/logout` → restart → re-auth; check for stale `ANTHROPIC_API_KEY` env var +- **Model not found**: check all 5 config layers in priority order; use `/model` picker to verify access +- **Performance**: `/compact` reduces context; `/heapdump` diagnoses memory growth +- **Search broken**: install system `ripgrep` and set `USE_BUILTIN_RIPGREP=0` +- **`/doctor`** is the first diagnostic to run for any unexplained issue + +--- + +## Sources + +- [Troubleshooting — Claude Code Docs](https://code.claude.com/docs/en/troubleshooting) +- See also: [[wiki/claude-code/error-reference|Error Reference]], [[wiki/claude-code/overview|Claude Code Overview]]