AI Beginner's Guide: Get Started with AI Tools

You installed Claude Code, but typing claude gives "zsh: command not found: claude", "bash: claude: command not found", or "is not recognized as an internal or external command" on Windows. In most cases the install dir is simply not on your PATH, and the install itself succeeded. This article explains how the shell searches PATH folders, the install methods and locations (the native installer is recommended and lands in ~/.local/bin, Windows %USERPROFILE%\.local\bin; npm needs Node 18+ and installs the same native binary; Homebrew/WinGet; installing only the VS Code extension does not add claude to PATH), the main causes and fixes (add ~/.local/bin to PATH and restart the terminal, an npm EACCES permission error should switch to native rather than sudo, Node too old, multiple-install conflicts checked with which -a / where.exe and reduced to one native install, and the native-binary-not-found case from skipping optional deps), Windows-specific traps (the wrong-shell mix-up like running irm in CMD, restarting the terminal, the old Claude Desktop WindowsApps Claude.exe conflict, and CLAUDE_CODE_GIT_BASH_PATH for Git Bash), auto-update and updating (claude update, claude install, claude doctor for the update result, DISABLE_AUTOUPDATER / DISABLE_UPDATES), and the diagnostic workflow (claude doctor to which -a to PATH to removing extras to a native reinstall) — all based on official information.

On a corporate machine or over VPN, Claude Code fails to connect with "Unable to connect to API", "Unable to connect to API (ECONNREFUSED)", "SSL certificate verification failed", or "fetch failed" — these are network errors where the request never reached Anthropic server (api.anthropic.com), which is different from auth (401/403), server overload (529/500), and rate limiting (429). This article covers the three enterprise blockers (an unconfigured proxy, a TLS inspection proxy replacing certificates, and a firewall blocking domains) plus DNS/VPN/Docker, proxy setup (HTTPS_PROXY/HTTP_PROXY/NO_PROXY, authenticating proxies, SOCKS unsupported, NTLM/Kerberos via an LLM gateway with ANTHROPIC_BASE_URL, and MCP servers needing the vars in their own env), TLS and corporate CA certs (recent Claude Code trusts both its bundled CA set and the OS trust store so a corporate root in the OS store often works with no config; otherwise point NODE_EXTRA_CA_CERTS at the PEM, mTLS via CLAUDE_CODE_CLIENT_CERT/KEY, and curl --cacert at install time), the critical security rule to never use NODE_TLS_REJECT_UNAUTHORIZED=0 (it exposes all traffic including api.anthropic.com to man-in-the-middle attacks), the firewall allowlist domains (api.anthropic.com, claude.ai, platform.claude.com, downloads.claude.ai, raw.githubusercontent.com, with statsig/sentry optional), the diagnostic workflow (curl -I https://api.anthropic.com for reachability, /doctor and proxy check, cert/proxy settings, a direct connection to confirm, then DNS/VPN/Docker), and how to tell it apart from auth/server/rate by whether the request reached the server — all based on official information.

When Claude Code suddenly stops with "API Error: 529 {\"type\":\"overloaded_error\",\"message\":\"Overloaded\"}" or "500 Internal server error", these are transient server-side events — not a mistake in your request or settings, and not your usage running out. This article explains the meaning of 529 Overloaded (Anthropic API temporarily over capacity, congestion across all users) and 500 (an unexpected internal error, with related 504 timeout_error; 502/503 usually come from upstream infrastructure), the fact that neither consumes your usage quota, how Claude Code auto-retries up to 10 times with exponential backoff before showing anything (Retrying in Ns, attempt x/y; CLAUDE_CODE_MAX_RETRIES default 10, API_TIMEOUT_MS default 10 minutes), the user fixes (wait and retry, switch model with /model since capacity is per model so Sonnet often works when Opus is busy, check status.claude.com, /feedback with request_id if a 500 persists), how to tell it apart from confusable errors (529/500 = server-side and no quota used, 429 = your rate limit with a retry-after header and quota, usage limit = plan allowance, 400 = a bad request), developer guidance (typed SDK exceptions and auto-retry, exponential backoff plus jitter, retry-after only on 429, --fallback-model, Priority Tier/Batch), and how to tell a transient spike from a continuing incident — all based on official information.

Working in Claude Code, you suddenly see "Claude usage limit reached. Your limit will reset at 3pm" and stop cold. This is not an error or a bug: it is how the Pro/Max subscription usage limits work. This article explains the two-tier structure (a rolling 5-hour window that recovers ~5 hours after your first prompt, plus a weekly window that resets every 7 days, and on Max a separate weekly cap just for Opus), the fact that Claude Code and the Claude apps share the same plan allowance, the four biggest consumption drivers (model choice where Opus burns far more than Sonnet, context size, long continuous sessions, and subagents/MCP), five ways to keep working when you hit the cap (drop to Sonnet with /model, trim context with /compact, wait out a 5-hour window, switch to pay-as-you-go API, or buy credits / upgrade), how to see what is left (/usage, /status, and Settings to Usage for the weekly reset date), and the difference between subscription limits and API limits (429, retry-after, tiers). Because the exact numbers get revised over time, it avoids asserting current figures and recommends checking the live official view.

The "Prompt is too long" error in Claude Code and the API (on the API: "prompt is too long: 233153 tokens > 200000 maximum") is not a usage limit — it means the input you tried to send (conversation history + attached/read files + tool definitions) exceeded the model context window. This article explains what fills the window (the dynamic factors of ever-growing conversation history, files you read, and tool results, plus the fixed factors of MCP tool definitions, CLAUDE.md, and the system prompt), how Claude Code avoids it by default with auto-compact, the window sizes (standard 200K vs 1M, where 1M is at standard pricing as of 2026 but subscriptions may need usage credits and the new tokenizer consumes roughly 30-35% more tokens), the fixes (/compact to summarize, /clear to restart, offloading big reads to a subagent that uses its own window, /context to see the breakdown and disable unused MCP or slim CLAUDE.md, and a 1M model only when truly needed), and how to tell the three confusable errors apart (Prompt is too long = input overflow, max_tokens = output cutoff, usage limit = plan quota, plus the 1M credits entitlement message) — based on official information.

You set up an MCP (Model Context Protocol) server in Claude Code, but /mcp shows it stuck at failed, needs authentication, or pending approval. This article shows how to first classify the cause by the /mcp (or claude mcp list) status into three families (✓ connected / ✗ failed = local launch failure / △ needs authentication = remote auth / ⏸ pending approval = project approval, plus the connected-but-0-tools state), the main causes and fixes for failed and config issues (relative path → absolute, server API keys belong in the per-server env not settings.json, MCP_TIMEOUT for startup timeouts, .mcp.json at the repo root with care for undefined ${VAR}, and never logging to stdout which corrupts the protocol), the very common Windows npx problem (spawn npx ENOENT → make command cmd and wrap with /c npx, or use WSL), remote OAuth (401/403 → authenticate from /mcp; some services like Microsoft 365 and Gmail connect via claude.ai connectors instead), the diagnostic workflow (/mcp status → claude --debug mcp for stderr → launch the server standalone → MCP Inspector → fully restart Desktop), and a prevention checklist — all based on official information.

During long Claude Code sessions, a stray "court" or a raw <invoke name="Bash"> tag suddenly leaks to the screen and the tool call never executes. This is not a mistake in your environment or command: it is a known model-side glitch where Claude (especially the Opus 4.8/4.7 family) corrupts the control tags of a tool call as it generates them, with many issues filed in Anthropic official repository (#64108, #64150, #64690, #65705, #66153, #67295, #68354). This article explains how an agent generates tool calls as text, why the fail-closed harness rejects them so no wrong command ever runs, the two-layer cause (control-token corruption plus a self-poisoning chain where the broken block stays in history and the model imitates it), the trigger conditions (long multi-day sessions, heavy context, the post-/compact state, multiple tools at once, 3+ MCP servers, long tool arguments), three common misconceptions (it did not go rogue; court is meaningless but a useful marker; retry only fixes mild cases), the user fix (bail to a fresh session /clear after two misses; /compact is unreliable), the developer fix (check stop_reason, detect invoke leakage and retry, never keep broken history, shorten arguments), how to tell it apart from similar errors (thinking-block 400, max_tokens truncation, third-party Bedrock parsing), and the official status that no fix has shipped as of June 2026 — all grounded in official docs and the real issues.

One day your ChatGPT or Claude account suddenly stops working: in 2026 reports of account suspensions (bans) and warnings are rising, and the scary part is you can be banned by accidentally breaking the terms even with no bad intent. This article organizes what to know to avoid losing your account on OpenAI (ChatGPT, Codex) and Anthropic (Claude, Claude Code), based on published usage policies and reports (not a guide to evading detection, but to staying compliant). Five common triggers across both: banned content / jailbreaks (illegal or harmful generation, trying to break safety filters via prompts; serious violations can be an instant permanent ban), unauthorized automation / scraping (bots, scripts, deceptive mass access like spam/phishing), sharing or reselling accounts/API keys, suspicious access patterns (frequent IP/country changes, heavy VPN, device switching read as abnormal logins), and payment mismatch/fraud (geographic gaps, suspicious payment methods). The biggest 2026 pitfall: using Claude personal-plan (Free/Pro/Max) OAuth tokens in any product other than the official app, including harnesses like the Agent SDK, is a Consumer ToS violation that caused a large ban wave; the right approach is to run apps/agents via the API (pay-as-you-go) and treat personal plans as official-app chat. OpenAI specifics: circumventing safety/access restrictions, automation/scraping, improper API key reuse, illegal uses. Anthropic specifics: personal-plan OAuth token misuse, unofficial third-party access, anti-distillation/competing-model clauses, jailbreaks. A 7-point prevention checklist (read the policy, match plan to purpose, do not put personal tokens in third-party tools, no jailbreaks/banned content, do not share or resell, region-matching payment and stable access, act on warnings immediately). Warnings are a chance to correct and most can continue; minor or accidental violations may be appealable, but serious violations are permanent and hard to recover. The right plan, for the right purpose, honestly. Always confirm each company current official terms.

Retraining a giant AI from scratch is too expensive, but you want to tweak it just for you; LoRA (Low-Rank Adaptation) grants that wish by freezing the original model and training only a tiny add-on part (an adapter), cutting trainable parameters by about 90%. LoRA makes fine-tuning dramatically cheaper and faster, and is hugely popular in image generation like Stable Diffusion as a small file that adds a character or style. This article explains it with a patch analogy. LoRA is the flagship of parameter-efficient fine-tuning (PEFT): leave the huge original weights frozen, insert a small add-on matrix into each layer, and train only that (W = W0 + BA, where W0 is frozen and BA is the small added part). It builds on the discovery that adapting an AI does not require big changes (a low rank is enough). Benefits: about 90% fewer trainable params (reportedly 10,000x fewer at GPT-3 scale), less GPU memory (about 3x less), faster and cheaper training, no inference latency once the adapter is merged, and lower overfitting risk. Its biggest strength is swappable adapters: keep one common base and swap small (few-MB) LoRA files per use case (support, company tone, a specific character) instantly. Many people first meet LoRA in image generation, where Stable Diffusion LoRAs that learned a character, style, or subject are shared widely (add a style, teach a character, light and shareable). QLoRA combines quantization, training LoRA on a 4-bit base for ~4x less memory than standard LoRA, enabling fine-tuning huge models on a consumer GPU (sometimes CPU) with minimal accuracy loss. Versus full fine-tuning (train all weights), LoRA differs in weights trained, cost, output, and best use; for most work LoRA is enough. Keep the base, season it small. Figures are quoted from public materials, directional.

A huge 70B model running on a single home gaming PC instead of a rack of data-center GPUs is made possible by quantization, which lowers the numerical precision of a model's weights to dramatically shrink size and memory. Whereas model distillation moves knowledge into a separate smaller model, quantization makes the same model lighter. This article explains it with a photo-compression analogy. Quantization replaces weights stored as FP16/FP32 decimals with INT8 (8-bit) or INT4 (4-bit) integers, cutting bytes per weight (FP32=4, INT8=1, INT4=0.5); like compressing a RAW photo to JPEG, you sacrifice a little precision for a big reduction, and the surprise is how little you give up. On memory, 4-bit uses about a quarter of FP16: a 70B model drops from ~140GB to ~35GB, and an 8B model at 4-bit is ~4.5-5GB, fitting a midrange 8GB-VRAM GPU for local use (the democratization of LLMs). On accuracy, INT8 is nearly lossless and INT4 degrades under 4% on general Q&A/commonsense tasks, but loss is more noticeable for math, code generation, and hard reasoning (it shows as a small rise in perplexity), so pick the bit-width for the task. Main methods: GPTQ (pioneer of accurate 4-bit), AWQ (protects the ~1% most important weights, often 1-2% more accurate and faster), GGUF (llama.cpp/Ollama format, Q2_K-Q8_0, CPU+GPU hybrid, for local), and QLoRA (4-bit base plus LoRA for consumer-GPU fine-tuning). It differs from distillation (move to a separate small model) and fine-tuning (add task knowledge), and the three are usually combined (quantize a distilled model; fine-tune a quantized base). To start, run a GGUF model with Ollama in one command, choose Q4/Q8 by VRAM, and avoid INT4 for code or exact math. Most major models ship already quantized, so you just download and use them. Keep the smartness, drop only the weight. Figures are quoted from public materials, directional.

A huge, high-performance AI is smart but heavy and expensive; model distillation (knowledge distillation) solves this by transferring a large teacher model's knowledge to a small student model, keeping 95%+ of the teacher's performance at one-tenth the size and speed. This article explains it with a teacher-student analogy. The key is soft labels: ordinary training teaches only "the answer is cat" (hard label), while distillation passes the teacher's full probability distribution like "90% cat, 8% dog, 2% fox," whose degree of hesitation carries rich information; a temperature parameter softens the probabilities to reveal subtle relationships (real example: GPT-4o mini distilled from GPT-4o). Benefits: fast and cheap, ~10x more compact while keeping 95%+ performance, runs on the edge, strong for specialization. Two approaches: white-box (full access to weights and internal representations, deeper transfer; for your own or OSS models) and black-box (only outputs/API responses visible; using another company's API as teacher can violate terms). It differs from quantization (compress the same model's weight precision) and fine-tuning (further-train an existing model for a task) — distillation moves knowledge into a separate small model, and the three are combinable. The legal/ToS reality was a big 2026 issue: the technique is legitimate, but OpenAI, Anthropic, Mistral, and xAI include anti-competitive distillation clauses prohibiting using outputs to build competing models, so distilling a competitor from a restricted API can violate terms. The OpenAI v. DeepSeek dispute (OpenAI alleged DeepSeek-linked accounts circumvented restrictions to obtain outputs for distillation, while DeepSeek's terms reportedly permit distilling its outputs) shows the assessment depends on whose API terms apply, and Claude Fable 5/Mythos 5 reportedly restrict responses on distillation-flagged work. Tips: use your own or licensed OSS models as teacher, check anti-distillation clauses before using a commercial API, and judge whether the use is "developing a competing model." Smartness from the big model, operation from the small — but who you pick as teacher changes the outcome technically and legally. Figures are quoted from public materials, directional.

In "How to build a multi-agent system" we said to instrument every handoff before adding agents; the tech that powers that instrumentation in production is AI observability. It makes visible what LLMs and agents actually do in production (which model with what prompt, which tools and searches, what was returned, and how long and how much it cost) so you can trace back to the cause. The decisive difference from ordinary app monitoring: AI can return 200 OK in 50ms and still confidently hallucinate, so most AI failures are quality failures (hallucination, weak retrieval, unsafe answers, incomplete tasks, poor tool use, post-prompt-change regressions), not infrastructure failures. Observability rests on three pillars: traces (one request as a tree of spans showing LLM calls, tools, retrieval, reasoning chains; the star of AI observation), metrics (latency, cost, tokens, error rate, throughput), and logs (per-event detail). The industry standard OpenTelemetry GenAI conventions capture prompts, responses, token usage, and tool/agent calls in a vendor-neutral schema feedable into Datadog/Grafana. The most-confused distinction is observability vs evaluation (evals): observability shows what happened (easy to measure, but cannot tell if the answer is correct), while evals measure whether the answer is good (accuracy, groundedness, safety) and require explicit evaluation. Because cost and latency are easy to measure but answer quality is not, 2026 tools combine trace display with output scoring and degradation alerts. Metrics split into operational (cost, latency, tokens, error rate) and quality (hallucination, groundedness/faithfulness which is most critical for RAG, safety, task completion), with hallucination detection via LLM-as-a-judge, semantic similarity, and groundedness scores. Major tools: LangSmith (LangChain), Langfuse (open-source self-host), Arize Phoenix (RAG debugging), MLflow (lifecycle), AgentOps (agents), and OpenTelemetry (the standard). Start by capturing traces (OpenTelemetry-compliant), visualize operational metrics, then connect evals before shipping. For multi-agent systems observation is essential since failures hide in multi-step chains visible only in a full-session trace. Observe plus evaluate is what makes AI production-grade. Figures and traits are quoted from public materials, directional.