Releases: the changes worth knowing

Full notes are on the official changelog and the GitHub releases page. These are the ones that change day-to-day use.

2.1.305 (Oct 20):

• sandbox.allowNestedUserNamespaces lets sandboxed commands on Linux create user namespaces, for things like Chromium or rootless podman. The release notes are clear that this also lets those commands get around the sandbox's file protections, so only turn it on where you need it.
• Tool search regression fixed. 2.1.304 made every request fail on Vertex, Bedrock and gateways that reject tool search. Claude Code now retries without it.
• /effort and /autocompact now apply when your model name differs from a modelOverrides value only by letter case or a [1m] tag.
• /usage warnings are now one-line fixes that name their source, and pressing f applies them.
• Full disk errors are readable. A Bash command on a full disk now says the disk is full and that nothing ran, instead of a raw ENOSPC path.

2.1.306 (Oct 20, late evening ET) fixed a real API error being replaced by "prompt is too long" in sessions with many MCP tools.

2.1.307 (Oct 21):

• MCP is steadier. Servers no longer get stuck as timed out when your laptop sleeps while they connect, HTTP MCP tool calls are no longer sent twice when a connection drops mid-call (only read-only or idempotent tools are retried), and a locked macOS keychain now explains itself instead of showing "needs authentication" in claude -p.
• Fewer "Autocompact is thrashing" errors in turns that read many PDF pages, images or other large results.
• /permissions > Recently denied now shows the shell command that was denied, and approving a row names the command.
• New claude_code.safety_event OpenTelemetry event for each tool call a permission rule, auto mode, hook or the sandbox stopped or prompted.

2.1.309 (Oct 22), the security-heavy one:

• Sandboxed Bash no longer runs your shell startup files outside the sandbox before each command (macOS and Linux).
• Several permission holes closed: an Edit(path) deny rule now also blocks a Bash redirect to that path in commands with a subshell, wrapped cd ... && git commands prompt like a plain cd, and sandboxed commands can no longer edit the file passed with --mcp-config.
• Large nested CLAUDE.md files no longer cause repeated compaction; one over the size limit now loads only its start.
• /rewind now shows code changes made through /code-review turns.

2.1.310 (Oct 23):

• The Monitor tool and plugin monitors now work on Bedrock, Vertex and Foundry, and when telemetry or nonessential traffic is off.
• Gateway fix. Requests behind gateways that reject the effort-2025-11-24 beta value or mid-conversation system messages now retry without them.
• Windows hook fix. PreToolUse and PermissionRequest hooks no longer let a tool call through when Git Bash is missing and the hook command is only a quoted path. If you rely on a hook to block things on Windows, update.
• cleanupPeriodDays set very high no longer lets background cleanup delete recent files like pasted images.

(2.1.308 was listed only as bug fixes and reliability improvements.)

Agent Skills now has a neutral home

On Oct 22 Anthropic donated Agent Skills to the Agentic AI Foundation, the Linux Foundation project that already hosts MCP. The name, logo, GitHub organization and the agentskills.io domain move over, and engineers from Anthropic, Google, OpenAI and others will maintain the spec. Anthropic says more than 70 agent platforms have integrated skills and about 1 million have been published. The proposed roadmap covers versioned releases, a formal proposal process and security guidance for people who write and install skills.

What it means for you: a SKILL.md you write for Claude Code is a format with a long life, not a Claude-only trick. If you want to check one before you share it, our free SKILL.md validator and description tester run in the browser.

Community: running many sessions at once

• Show HN: Lights-on software factory boilerplate for Claude Code. Open-source boilerplate based on the setup behind Votito; the author says its orchestrator cut token cost by around 80% versus a bare-bones setup.
• AIPass is feature-complete by @aipass. The open-source framework that turns Claude Code sessions into a team of persistent agents is now fixes-only, with a phone app for watching them.
• hivemux: a tmux sidebar that tells me which Claude Code session needs me by @esteban-eg-kim. Shows each session as running, waiting or done and jumps to the one that has waited longest.
• I kept missing Claude Code's permission prompts, so I built a desktop around it by @fxdgif. VibeDesk, a Windows desktop that turns permission prompts into one-click cards.
• Multirun: A Multi-Agent Run Framework by @kubeden. Runs one task through ten isolated agents, each in its own worktree, then diffs where they agree and split.

Community: cost, limits and tokens

• How Claude Code and Codex tell you your limits by @pikori. Why counting tokens from local logs drifts from what /usage reports.
• What did that Claude Code session actually cost? by @bargan. ccdeck shows quota, per-session cost and monthly spend in one page.
• Sending text as images cut my Claude tokens by up to 81%. It also started inventing numbers. by @jaehyun_cho_0dff271e0d2e5. An honest test of the trade-off.
• caveman vs ponytail vs Chisle by @jaypokale. Compares answer length across three brevity rulesets on the same prompts (written by Chisle's author).
• I made Coco, a little friend for Claude Code by @ninon. A status-bar character that reacts locally and shows your 5-hour and weekly limits.

Community: skills, memory and MCP

• Show HN: Skillstore. A library of engineering skills behind an MCP server that Claude Code can search and load as it works.
• Open-source, cross-harness memory for AI agents. Beacon captures session telemetry from 20+ harnesses and turns it into reusable skills.
• I built a Claude skill that flags scope creep before you reply to a client by @kitwisestudio. Splits a client message into asks, checks each against scope and drafts a priced change order. Useful if you freelance.
• Build a hotel rate-parity watcher with Claude Desktop and SQLite by @huynhtanan. A Google Hotels MCP server plus a small logger (the author notes it calls paid Apify actors).

Community: building with it

• Running Claude Code with Ollama and Local Models by @mohammed_sebaa_2610. Install, IntelliJ setup and a local model through Ollama, tested on a small Java project.
• AI videos with Claude Code for beginners: 11 prompts, $0.62 by @hiper2d. From an empty folder to a narrated 101-second video with skills and FFmpeg, all prompts shared.

My takeaway this week

Update to 2.1.309 or later if you lean on the sandbox or deny rules; the fixes this week closed real gaps, and on Windows 2.1.310 fixes hooks that could fail open. And if you've been putting off writing your own skills, the move to the Linux Foundation is a good reason to start: the same SKILL.md now works across many agents.

Release facts on this page come from Anthropic's Claude Code changelog, the GitHub releases and Anthropic's announcement. Community summaries are mine; all credit to the authors. This page isn't affiliated with Anthropic.

The full, searchable list of Claude Code write-ups (292 posts, sorted by category, refreshed daily) is at solostackkits.netlify.app, and the free browser tools are here.

If you want ready-made skills to start from, grab our free 3-skill sample (client follow-ups, meeting notes to tasks, invoice chasing), or the full Solo Consultant Kit.

Shortcut: our free .mcp.json builder writes a valid MCP config for stdio, HTTP, SSE or WebSocket servers, always sets type on remote entries, and prints the matching claude mcp add command with the -- in the right place, so several of the problems below can't happen. It runs in your browser.

An MCP server gives Claude Code tools from outside your project: a database, Notion, GitHub, Stripe and so on. When one "doesn't work", it's one of three things: Claude Code never read the server's config, it read it but couldn't start or reach the server, or the server connected and isn't giving Claude any tools. Work through the checks below in order.

First: what does Claude Code say about the server?

From your shell, run claude mcp list. Each server gets a status such as ✔ Connected, ! Needs authentication or ✘ Failed to connect. Then run claude mcp get <name> for the one that's broken: on a failure it shows an Issue: line with the HTTP status or error code and any error text the server sent back (Claude Code v2.1.219 or later). Inside a session, /mcp shows the same statuses and the same Issue: detail.

If the server isn't in the list at all, start at cause 1. If it says Pending approval, Rejected or Disabled, go to cause 3. If it says Failed to connect, start at cause 6. If it's connected but Claude can't use it, go to cause 12.

Not loaded: 5 reasons the server never shows up

1. .mcp.json is in the wrong place or uses the wrong key. A project's MCP config goes at the repository root as .mcp.json, not inside .claude/. The servers sit under a top-level mcpServers key. A file copied from VS Code's mcp.json, which uses a servers key, never loads.
2. You put mcpServers in settings.json. Claude Code's settings.json doesn't read an mcpServers key, so servers there never appear. Put project servers in .mcp.json, or add personal ones with claude mcp add --scope user, which stores them in ~/.claude.json.
3. The project server is waiting for approval, rejected or turned off. Claude Code asks once before it uses servers from a project's .mcp.json. If you dismissed that prompt, the server stays at ⏸ Pending approval until you approve it from /mcp. In a folder you haven't trusted yet, approvals committed to the repo's .claude/settings.json are ignored, so run claude there and accept the trust dialog. A server listed in disabledMcpjsonServers in any settings file shows ✘ Rejected, and one you toggled off in /mcp shows ⊘ Disabled for this project until you turn it back on there. To reset your approval choices, run claude mcp reset-project-choices.
4. You added it in a different project, or another scope wins. claude mcp add uses local scope by default, which loads the server only in the project folder you ran it from. Add --scope user to get it everywhere, or --scope project to share it in .mcp.json. If the same name exists in more than one scope, Claude Code uses the whole entry from the highest one (local, then project, then user, then plugins, then claude.ai connectors) and doesn't merge fields, so a stale local entry can hide the one you just edited. claude mcp list warns about the conflict; remove the extra with claude mcp remove <name> --scope <scope>.
5. The name is reserved. Claude Code skips a server named after one of its built-ins, such as workspace, claude-in-chrome or computer-use, and shows a warning asking you to rename it. Server names should use only letters, numbers, hyphens and underscores.

Failed to connect (local stdio servers): 4 reasons

6. The -- separator is missing or --env is in the wrong spot. For a local server, everything after -- is the command that starts it: claude mcp add example --env API_KEY=your-key -- npx -y @example/mcp-server. Without --, Claude Code tries to read the server's own flags, such as -y or --port, as its own. And if the server name comes straight after --env, the CLI reads the name as another KEY=value pair and rejects it, so put another option such as --transport stdio between them.
7. The command uses a relative path. Relative paths in command or args resolve against the folder you launched Claude Code from, not the folder that holds .mcp.json, so the server starts from one directory and fails from another. Use absolute paths for local scripts. Programs on your PATH, like npx or uvx, work as written.
8. An environment variable is missing or has hidden whitespace. Set the variables a server needs in its own env block in the config instead of relying on your shell. A ${VAR} reference to a variable that isn't set and has no ${VAR:-default} fallback stays as the literal text ${VAR}, and claude mcp list warns about it. Claude Code also warns when a pasted value carries a hidden leading or trailing space or newline, but it uses the value as written, so delete the whitespace yourself.
9. The server takes too long to start. A slow first npx download or a heavy server can miss the startup window. Raise it with the MCP_TIMEOUT environment variable, in milliseconds: MCP_TIMEOUT=10000 claude allows ten seconds.

Failed to connect (remote servers): 2 reasons

10. The entry has a url but no type. Claude Code reads an entry with no type as a local stdio server, so a url-only entry copied from another app's config fails. Add "type": "http" (or "sse" if the service says so). For a wss:// address use "type": "ws" through .mcp.json or claude mcp add-json, because claude mcp add --transport doesn't accept ws.
11. The credential is missing, expired or reads as empty. ! Needs authentication means you haven't signed in or the sign-in expired: run /mcp, pick the server and sign in, or run claude mcp login <name> from your shell. Sign-ins are stored per endpoint, so a second definition of the same server with a different URL needs its own sign-in. If you put a header like Bearer ${ANTHROPIC_API_KEY} in a remote server's config, the server receives an empty token and usually answers 401: Claude Code deliberately reads its own and your cloud provider's credentials (and others such as NPM_TOKEN and HTTPS_PROXY) as empty in remote url and headers. Copy the key into a variable with a name of your own, such as MY_SERVICE_KEY, and reference that.

Connected, but Claude can't use it

12. It shows zero tools, or it dropped mid-session. A server that's connected with zero tools started but isn't returning a tool list. Select Reconnect in /mcp. If the count stays at zero, run claude --debug=mcp and read the server's error output in the debug log at ~/.claude/debug/<session-id>.txt. Claude Code reconnects a remote server that drops (up to five tries) but doesn't restart a local stdio server on its own, so reconnect that one from /mcp. To retry every failed server at once, run /mcp reconnect all (v2.1.284 or later in the terminal).

Still stuck?

Run /doctor inside Claude Code (or claude doctor from your shell if it won't start) for a checkup of your installation and settings that flags invalid settings files. Then start a session with claude --debug=mcp, reproduce the failure, and read what the server printed in ~/.claude/debug/<session-id>.txt. The server's own error message usually names the missing package, key or port.

If the server connects but a tool call hangs, or the session freezes while a server starts, Claude Code stuck or not responding covers the MCP timeouts (MCP_TIMEOUT, MCP_TOOL_TIMEOUT and the per-server timeout).

If what's missing is the editor link (diffs in VS Code or JetBrains, shared selection, IDE diagnostics), that runs through a built-in ide server that's hidden from /mcp. Our IDE not connecting guide covers it.

A minimal config that loads

{
  "mcpServers": {
    "notion": {
      "type": "http",
      "url": "https://mcp.notion.com/mcp"
    },
    "airtable": {
      "command": "npx",
      "args": ["-y", "airtable-mcp-server"],
      "env": { "AIRTABLE_API_KEY": "${AIRTABLE_API_KEY}" }
    }
  }
}

Save it as .mcp.json in your project root, set AIRTABLE_API_KEY in your shell, start claude in that folder and approve both servers. Then run /mcp to sign in to Notion. The same two servers from the command line:

claude mcp add --transport http notion https://mcp.notion.com/mcp
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable -- npx -y airtable-mcp-server

Facts on this page come from Anthropic's MCP documentation, debug your configuration guide and error reference. This guide isn't affiliated with Anthropic.

Once your tools are connected, skills turn them into repeat jobs you don't have to re-explain. Start with our free 3-skill sample (client follow-ups, meeting notes to tasks, invoice chasing), or get the full Solo Consultant Kit.

First: does Claude Code see the hook?

Type /hooks at the Claude Code prompt. It lists every configured hook grouped by event. If your hook isn't there, start at cause 1. If it's there but never seems to run, go to cause 5. If it runs but doesn't block or its output is ignored, go to cause 9.

Not loaded: 4 reasons /hooks shows nothing

1. The settings file has a JSON error. Trailing commas and comments aren't allowed in Claude Code settings files, and one stray comma means none of the hooks in that file load. Paste the file into any JSON validator before anything else.
2. The file is in the wrong place. Project hooks go in .claude/settings.json (or .claude/settings.local.json for just you) inside the project. Hooks for every project go in ~/.claude/settings.json. A settings.json at the project root, outside .claude/, isn't read. Cloud sessions also don't read your local ~/.claude/settings.json.
3. The nesting is one level off. Hooks have three levels: the event name, then a list of matcher groups, then each group's own hooks list of handlers. The handler needs "type": "command" and a command. A handler placed straight under the event, with no matcher group around it, is the most common copy-paste mistake. The working shape is at the end of this page.
4. Hooks are turned off or restricted. "disableAllHooks": true in any settings file turns hooks off, and the value left after settings precedence is the one that counts, so a project file can override yours. If /hooks says Only hooks from managed settings run here, your organization set allowManagedHooksOnly, and hooks in your user, project and local files don't run. File edits are normally picked up on their own; if a new hook still hasn't appeared after a few seconds, restart the session.

Loaded but never fires: 4 reasons

5. The matcher doesn't match the tool name exactly. Matchers are case-sensitive: bash never matches the Bash tool. A matcher made only of letters, digits, _, -, spaces, , and | is compared as an exact name (or a list of names like Edit|Write). Anything else is treated as an unanchored regular expression, so Edit.* also matches NotebookEdit; use ^Edit$ when you mean only Edit.
6. The MCP matcher is missing .*. MCP tools are named mcp__<server>__<tool>. A matcher like mcp__memory contains only exact-match characters, so it's compared as an exact string and matches no tool. Use mcp__memory__.*. For a server bundled in a plugin, the name includes the plugin, as in mcp__plugin_my-plugin_db__.*.
7. It's the wrong event, or the event has no matcher. PreToolUse fires before a tool runs and PostToolUse after, so a PostToolUse hook can't undo anything. Stop, UserPromptSubmit and a few other events don't support matchers at all and fire every time. And the optional if field only works on tool events; adding it to any other event stops the hook from running.
8. The script can't start. On macOS and Linux the script must be executable: chmod +x .claude/hooks/my-hook.sh. If you see command not found, use an absolute path or ${CLAUDE_PROJECT_DIR}, and quote it in shell form ("\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/my-hook.sh") or add "args": [] so Claude Code runs it directly without a shell. If the message is jq: command not found, install jq or parse the JSON with Python or Node instead.

Runs but doesn't block, or its output is ignored: 4 reasons

9. It exits 1 instead of 2. Only exit code 2 blocks. Exit 1, the usual Unix failure code, is a non-blocking error: Claude Code shows a hook error notice and lets the action go ahead. For a guardrail, write the reason to stderr and exit 2.
10. The JSON has a field at the wrong level. For PreToolUse, permissionDecision and permissionDecisionReason belong inside hookSpecificOutput, next to "hookEventName": "PreToolUse". At the top level they still parse, and Claude Code silently ignores them. Other events use different shapes: PostToolUse and Stop use a top-level "decision": "block".
11. Something prints before your JSON. Claude Code only reads stdout as JSON when it starts with {. If your shell profile runs an unconditional echo (this happens with Git Bash or when BASH_ENV points at ~/.bashrc), that text lands first and your decision is read as plain text, with no error shown. Wrap profile echoes in if [[ $- == *i* ]]; then ... fi so they only run in interactive shells. Also build JSON with jq or a real encoder; hand-built strings break on quotes and backslashes.
12. A hook can't loosen a deny rule. Hooks can tighten permissions but not loosen them: a hook that returns "allow" doesn't override a deny rule in your settings. In plan mode, an "allow" on a file edit still gets the normal plan-mode prompt. The reverse does work: a PreToolUse deny blocks the tool in every permission mode, including bypassPermissions.

Bonus, for Stop hooks: if Claude keeps going instead of stopping, your hook is blocking every time. Read stop_hook_active from the input and exit 0 when it's true. Claude Code overrides a Stop hook after it blocks eight times in a row.

How to see what a hook actually did

• Test the script by hand. Pipe sample input in and check the exit code: echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh; echo $?
• Read the transcript. Press Ctrl+O. A block shows its message; a non-blocking error shows a hook error notice with the first line of stderr; success usually shows nothing.
• Read the debug log. Start with claude --debug-file /tmp/claude.log and run tail -f /tmp/claude.log in another terminal, or run /debug mid-session. Search it for Hook output does not start with { (cause 11) or Hook JSON output had unrecognized keys (cause 10).

A minimal hook that works

This blocks rm -rf before Bash runs it. Save it in .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-rm.sh"
          }
        ]
      }
    ]
  }
}

And the script, at .claude/hooks/block-rm.sh (run chmod +x on it):

#!/bin/bash
COMMAND=$(jq -r '.tool_input.command')
if echo "$COMMAND" | grep -q 'rm -rf'; then
  echo "Blocked: rm -rf is not allowed. Delete specific files instead." >&2
  exit 2
fi
exit 0

Run /hooks to confirm it's listed under PreToolUse, then ask Claude to delete a folder to see the block.

If you'd rather not write the scripts yourself, our free, MIT-licensed claude-safety-hooks package installs three tested PreToolUse hooks (dangerous shell commands, .env and key files, lockfile edits) with npx claude-safety-hooks. It backs up your existing settings.json first, doesn't add duplicate entries if you run it twice, and --uninstall removes only what it added.

If you'd rather generate the config than hand-write it, the free hooks & settings.json generator writes a valid hooks block with exact-case matchers and blocking exit codes, in your browser.

Drafted with AI assistance and checked line by line against Anthropic's docs.

Facts on this page come from Anthropic's hooks guide and hooks reference. This guide isn't affiliated with Anthropic.

Once your guardrails are in place, skills turn your repeat client work into one-line requests. Start with our free 3-skill sample (client follow-ups, meeting notes to tasks, invoice chasing), or get the full Solo Consultant Kit.