DEV Community: aicoding-guide

Codex CLI v0.166 adds codex queue --resume and codex doctor --network-only

aicoding-guide — Sun, 01 Nov 2026 19:15:17 +0000

Originally published at https://aicoding-guide.com.

Codex CLI v0.166.0 ships six features and seven fixes. Two matter day to day: codex queue --resume and codex doctor --network-only.

Both are flags on existing commands, so knowing what each command already does is the quickest way to see what changed.

Key point
What this article covers

How codex queue works and the situation --resume fixes

What codex doctor checks, and what --network-only narrows it to

Approval settings and token accounting now surviving resume and fork

codex queue --resume resumes the thread

The release notes read: "Added codex queue --resume to resume unloaded threads after queueing a message."

codex queue itself is documented: it queues a text message for an existing session.

codex queue --thread <SESSION_ID> --message "Run the remaining checks"

Option	Detail
`--thread`	A UUID or an exact session name; use a UUID when sessions share a name
`--message`	The text to queue
Others	`--remote` and `--remote-auth-token-env` are accepted; image attachments are not

Previously, queueing a message to a thread that was not loaded left it waiting. With --resume, queueing and resuming happen in one step — useful when a script or CI job adds work to an existing session.

--resume is not in the commands documentation
As of 2026-11-02, the flags documented for codex queue are --thread, --message, --remote and --remote-auth-token-env. There is no entry for --resume; it appears only in the release notes.

codex doctor --network-only narrows the report

The other addition: "Added codex doctor --network-only for focused configuration, connectivity, and WebSocket diagnostics."

codex doctor is the diagnostic command to run before filing a support issue or while investigating a broken installation. The documentation describes its scope as "installation, configuration, authentication, runtime, Git, terminal, app-server, and thread inventory health".

# The full report
codex doctor

# Narrowed to configuration, connectivity and WebSocket
codex doctor --network-only

The full report includes the thread inventory, so it takes a while. When the symptom is clearly network-side — connections failing behind a proxy, WebSockets dropping — --network-only is the faster path.

This flag could not be confirmed in the documentation either: codex doctor's option table is rendered dynamically on that page, so individual flags are not readable from the Markdown.

For the network proxy settings themselves, see Combining approval_policy and sandbox_mode in Codex.

Transcript handling and the other features

The remaining four are display and interaction changes.

Addition	What it does
Transcript selection	Keyboard-driven, with word, line and page motions, integrated search, and configurable shortcuts
Markdown rendering	Made consistent in async questions, choices, answers and transcript replies
GPT-6.1 Terra	Added to the bundled, Vertex AI and Amazon Bedrock model catalogs
Safety-block explanations	Clearer reasons in the TUI, with selectable safer follow-up prompts

GPT-6.1 Terra reached the bundled catalog in v0.165.0; v0.166.0 adds it to the Vertex AI and Amazon Bedrock catalogs. That follows v0.165.0 making Vertex AI a built-in provider via model_provider = "gcp" — see Codex CLI v0.165 makes Vertex AI a built-in provider.

Fixes around resume and fork

Two of the seven fixes concern resuming and forking sessions.

Approval and permission settings persist: "Preserved acknowledged approval and permission settings when resuming or forking threads."
Reasoning-token accounting persists: "Preserved reasoning-token accounting across resume and fork to avoid premature compaction."

The second has the clearer practical effect. When the accounting reset, a resumed session could be judged to have met the compaction threshold while it actually had room left, so context was lost earlier than it needed to be.

Also fixed: spawned descendant threads are restored when their parent is unarchived, app-server thread startup and shutdown races are resolved with completed runtimes released promptly, and TUI reconnection recovery now handles offline /quit and /exit.

Summary

codex queue --resume queues a message and resumes an unloaded thread in one step
codex queue takes a UUID or exact session name in --thread and does not support image attachments
codex doctor --network-only narrows diagnostics to configuration, connectivity and WebSocket
Approval settings and reasoning-token accounting now survive resume and fork
Neither --resume nor --network-only could be confirmed in the official commands documentation

This week in Claude Code, Codex and Gemini CLI (week of November 1, 2026)

aicoding-guide — Sat, 31 Oct 2026 19:08:39 +0000

Originally published at https://aicoding-guide.com.

This week has a deadline in it. Fast mode for Opus 4.8 is deprecated as of 2026-10-30 and removed on 2026-11-30. The CHANGELOG is specific that after removal, fast mode requests on Opus 4.8 return an error and do not fall back to standard Opus 4.8.

On the feature side, idle compaction spread to VS Code and the desktop app — two weeks after it arrived, terminal-only.

Key point
This week in brief

Fast mode on Opus 4.8 is removed on November 30; move to Opus 5.5 to keep the speedup

Idle compaction was added to VS Code and the desktop app's Code tab

permissions.blockWritesOutsideWorkingDirectories was added

Claude Code

Four releases: 2.1.311, 2.1.312, 2.1.314 and 2.1.316.

A deprecation with a date (2.1.316)

The CHANGELOG reads: "Deprecated fast mode for Opus 4.8 as of October 30, 2026; it will be removed on November 30, 2026. After removal, fast mode requests on Opus 4.8 return an error and do not fall back to standard Opus 4.8. Migrate to Opus 5.5 to keep the speedup."

If a script or settings file assumes fast mode, move it to Opus 5.5 during November. After removal it does not quietly get slower — it errors.

Confining writes to the working directories (2.1.314)

Setting	What it does
`permissions.blockWritesOutsideWorkingDirectories`	Write, Edit and NotebookEdit refuse paths outside the working directories in every permission mode

It pairs with permissions.blockReadsOutsideWorkingDirectories on the read side. With both set, the reach of the file tools no longer depends on the permission mode.

Idle compaction spread (2.1.314)

"Added idle compaction to VS Code and Claude Desktop's Code tab: a 200K+ token conversation left idle is summarized, and the summary is used on your next message if the prompt cache has expired."

What landed in the terminal in 2.1.299 reached VS Code and the desktop Code tab two weeks later. For the conditions and how to turn it off, see Making Claude Code compact earlier, or never.

New environment variables (2.1.316)

Variable	What it does
`CLAUDE_CODE_DISABLE_ULTRATHINK`	Turns the `ultrathink` keyword off
`CLAUDE_CODE_SUBAGENT_EFFORT`	Sets the effort subagents run at when nothing else names one, instead of inheriting the session's

Telemetry and permissions (2.1.312, 2.1.316)

claude_code.safety_event stopped being sent after a week
The claude_code.safety_event OpenTelemetry event added in v2.1.307 was withdrawn in v2.1.312: "Changed Claude Code to stop sending the claude_code.safety_event OpenTelemetry event." We covered it in last week's digest; it lasted a week. A dashboard built on that event needs rebuilding.

On security, --restricted sessions could upload files from outside the working directories when a Read allow rule covered them; that is fixed. Separately, for Team and Enterprise logins, server-managed settings fetched from Anthropic's API now apply without an approval prompt, and a stored copy that doesn't verify is refused.

Easy ones to miss

Sessions failing turn after turn with "Invalid effort level" where an admin caps a model's effort are fixed: Claude Code lowers the effort, retries, and says which level it uses (2.1.314)
A PreCompact hook with very large output could make compaction fail or repeat; each hook's output is now cut at 10,000 characters (2.1.314)
Claude could overwrite a very large CLAUDE.md, rules file or @-included file after seeing only its start; Write now asks Claude to read it all or edit in place (2.1.312)
Standard-context sessions that stopped with "Usage credits required for 1M context" past 200K tokens now compact and continue (2.1.311)
SubagentStop hooks were firing about twice a minute per running subagent instead of once at the end (2.1.311)

Codex

v0.165.0 brought the Vertex AI provider and memories by default; see Codex CLI v0.165.

v0.166.0 adds six features.

Addition	What it does
`codex queue --resume`	Resumes unloaded threads after queueing a message
`codex doctor --network-only`	Runs focused configuration, connectivity and WebSocket diagnostics
Transcript selection	Keyboard-driven, with word, line and page motions, search and configurable shortcuts
GPT-6.1 Terra	Added to the bundled, Vertex AI and Amazon Bedrock model catalogs
Safety-block explanations	Clearer reasons in the TUI, with selectable safer follow-up prompts

Two fixes stand out, both about resuming: acknowledged approval and permission settings are now preserved when resuming or forking threads, and reasoning-token accounting is preserved across resume and fork to avoid premature compaction.

Gemini CLI

v0.66.0 is 26 entries of fixes and chores with no features. The configuration-related ones:

Settings placeholders are now resolved after .env files are loaded
The user-level ~/.gitconfig is preserved in shell and git environments
Interactive credential and SSH prompts are disabled in getSafeGitEnv
MCP OAuth flows support opt-in private network endpoints
keybindings.json supports a keys array

A banner was also added saying Gemini CLI is not optimized for Gemini 4. For the previous release, see Gemini CLI v0.65 enforces read-only settings in untrusted folders.

What to check now

If you use fast mode on Opus 4.8, move to Opus 5.5 before November 30
Rebuild any telemetry that relied on claude_code.safety_event
Note that idle compaction now runs in VS Code and the desktop app too
Set permissions.blockWritesOutsideWorkingDirectories if you want writes confined

Summary

Fast mode on Opus 4.8 is removed on 2026-11-30 and will error, with no fallback
Idle compaction was added to VS Code and the desktop app's Code tab
permissions.blockWritesOutsideWorkingDirectories confines writes in every permission mode
claude_code.safety_event stopped being sent a week after it was added
Codex 0.166.0 adds codex queue --resume and codex doctor --network-only

Codex CLI v0.165 makes Vertex AI a built-in provider and turns memories on by default

aicoding-guide — Thu, 29 Oct 2026 19:19:07 +0000

Originally published at https://aicoding-guide.com.

Codex CLI v0.165.0 brings six features and six fixes. Two of them touch configuration: a built-in Vertex AI provider and memories on by default.

For both, the release notes are ahead of the official configuration reference. Check the behaviour on your own machine before relying on either.

Key point
What this article covers

The Vertex AI provider configured with model_provider = "gcp"

Why the release notes and the configuration reference disagree about memories

Changing reasoning effort partway through a conversation

Vertex AI is now a built-in provider

The release notes read: "Added a built-in Google Cloud Vertex AI provider, configured with model_provider = "gcp"." Using Vertex AI previously meant writing your own model_providers entry; now it is treated as built in.

gcp is not in the configuration reference yet
As of 2026-10-30, the reference lists only three built-in provider IDs: "Built-in provider IDs (openai, ollama, and lmstudio) are reserved and cannot be overridden." There is no mention of gcp or Vertex AI. The ID appears only in the release notes.

Where you write the setting matters. The configuration reference states that model_provider and model_providers are ignored in a project-local .codex/config.toml.

# Put this in ~/.codex/config.toml; a project-local copy is ignored
model_provider = "gcp"

The ignored keys include openai_base_url, chatgpt_base_url, model_provider, model_providers, notify, profile, profiles and otel. Provider, notification and telemetry keys belong in user-level config. For defining a custom provider, the fields are model_providers.<id>.name, .base_url, .env_key and others, covered in Configuring Codex with config.toml.

GPT-6.1 Terra was also added to the model catalogs.

Memories are on by default for fresh profiles

The release notes read: "Enabled memory v2 by default for fresh profiles and added support for importing external-agent memories into it."

The two sources disagree on the default
The configuration reference still describes features.memories as "Enable Memories (off by default)" (checked 2026-10-30). The term "memory v2" does not appear in the memories documentation at all. Since the documents do not settle which applies, check the actual state with /memories.

The mechanism itself is documented.

Aspect	Detail
Storage	`~/.codex/memories/`, holding summaries, durable entries, recent inputs and evidence
When they are written	In the background once a chat has been idle long enough, not at the end of every chat
What is skipped	Active and short-lived sessions; secrets are redacted from generated memory fields
Throttling	A background pass is skipped when your rate-limit remaining percentage is below the configured threshold
Per-chat control	`/memories` chooses whether the chat can use existing memories and whether it feeds future ones

The documentation is also explicit about the limits of relying on them: "Keep required team guidance in AGENTS.md or checked-in documentation. Treat memories as a helpful recall layer, not as the only source for rules that must always apply."

On the files themselves, it says "Treat these files as generated state" — fine to inspect when troubleshooting or before sharing your Codex home directory, but not a control surface to edit by hand.

Reasoning effort can change mid-conversation

Another entry reads: "Enabled reasoning effort changes during a conversation by default for supported models." On models that support it, you can change the depth after a conversation has started.

Switching through /model already existed; what changed is that mid-conversation changes are enabled by default. For the values and the ways to set them, see How to change reasoning effort in Codex CLI.

The session picker also gained a repository filter, and the agent command center now groups by directory, which makes sessions easier to find across linked worktrees.

Security and the other fixes

There are six fixes. The security one reads: "Closed a marketplace URL validation gap that could allow Git to connect to a different host than the one checked against allowed patterns."

The remaining fixes that change behaviour:

Fresh TUI sessions now honour the server's default approval reviewer when no explicit override is given
TUI preferences stay editable and immediately applicable when execution settings are invalid
Queued agent messages no longer restart work after an interrupt or a switch to Plan mode
When a provider reports that a model was not found, Codex stops retrying and preserves the error message

For the previous release, see Codex CLI v0.164 adds /presets and inline /permissions arguments.

Summary

A built-in Vertex AI provider is configured with model_provider = "gcp"
gcp could not be confirmed in the configuration reference, which still lists only openai, ollama and lmstudio
model_provider is ignored in a project-local .codex/config.toml; put it in user-level config
Memories are said to be on by default for fresh profiles, while the reference still says off by default
A marketplace URL validation gap that could redirect Git to another host was closed

Claude Code vs Cursor compared on pricing, permission settings and rule files

aicoding-guide — Tue, 27 Oct 2026 19:19:33 +0000

Originally published at https://aicoding-guide.com.

Claude Code and Cursor are both coding agents. Cursor is known as an editor, but it now ships a CLI too, so using it from a terminal looks much like using Claude Code.

What changed in 2026 is what your subscription includes. Cursor is sold as part of the X Subscription, and what comes with it is Grok and Composer. Using Claude's models costs extra. That is the single biggest factor in choosing between them.

Key point
What this article covers

The models each subscription actually includes

Similar permission syntax, but different places you can put settings

How the project rule files differ

At a glance

Verified against the official documentation as of 2026-10-28.

	Claude Code	Cursor
Surfaces	CLI, VS Code extension, desktop app	Editor, CLI, cloud agents
Models included	Claude models	Cursor models (Grok 4.7 / 4.6 / 4.5, Composer 2.5)
Third-party models	N/A	Not included; Premium and above pay API list price from prepaid credit
Usage unit	Rolling five-hour session window	A pool that refreshes weekly
Permission syntax	`Bash(...)`, `Read(...)`, `Edit(...)`	`Shell(...)`, `Read(...)`, `Write(...)`, `WebFetch(...)`, `Mcp(...)`
Config file	`settings.json`, five scopes	`cli-config.json` (global) and `cli.json` (project)
Rule file	`CLAUDE.md`	Four kinds, including `.mdc` files in `.cursor/rules` and `AGENTS.md`

The subscriptions include different models

The documentation opens with it: "Cursor is sold as part of The X Subscription, one subscription for Grok, Cursor, and X." Paid plans come with a weekly pool of usage for Cursor's models, and third-party models are not included.

Cursor plan	Monthly	Annual
Free	$0	—
Plus	$8	$80
Premium	$30	$300
Super	$100	$1,000
Ultra	$200	$2,000

Teams is $30, $100 or $200 per seat, and Enterprise is custom. Prices exclude tax.

Plus is the tier to read carefully. The documentation says it runs Cursor's own models at fixed settings: Fast off, effort medium, and Grok 4.7 on the 256k context window. No Auto, Cloud Agents, Automations, Bugbot, Origin, third-party models, or your own API keys.

On the Claude side, Free is $0, Pro is $20 billed monthly or $17/mo billed annually ($200 up front), and Max starts at $100 for 5x or 20x Pro's usage. Claude Code is included in Pro and Max, and is not available on Free. Limits "reset on a rolling five-hour session window".

The same money buys different things
At $8 against $20, Cursor Plus looks like the cheaper option. But Plus runs Grok and Composer, not Claude. Running Claude's models through Cursor needs Premium or above plus prepaid credit, which reverses the comparison. The reliable question is not which is cheaper but which subscription contains the model you want to use.

The documentation also calls Pro, Pro+, Ultra, Start, and Teams Standard and Premium "legacy Cursor plans". Note that Ultra appears in both the current and the legacy lists, so the names overlap.

The permission syntax is similar

Cursor CLI's permission tokens look a lot like Claude Code's. You list them under permissions.allow and permissions.deny.

{
  "permissions": {
    "allow": [
      "Shell(git)",
      "Read(src/**/*.ts)",
      "Write(package.json)",
      "WebFetch(docs.github.com)",
      "Mcp(datadog:*)"
    ],
    "deny": [
      "Shell(rm)",
      "Read(.env*)",
      "Write(**/*.key)"
    ]
  }
}

Shell is Shell rather than Bash, and edits are Write rather than Edit. For MCP, Claude Code writes mcp__<server>__<tool> while Cursor writes Mcp(server:tool). Keeping .env out of reach works the same way in both. For the Claude Code syntax, see Claude Code permissions in settings.json.

The real difference is where settings can live. Cursor CLI reads ~/.cursor/cli-config.json globally and <project>/.cursor/cli.json per project, but the documentation states: "Only permissions can be configured at the project level. All other CLI settings must be set globally."

So in Cursor, permissions are the only thing a project can vary. That is a different design from Claude Code, where five scopes from managed settings down to user settings can override nearly any key.

Rule file conventions

Cursor has four kinds of rules.

Kind	Where it lives
Project Rules	`.mdc` files in `.cursor/rules`, version-controlled
User Rules	Global to your Cursor environment
Team Rules	Managed from the dashboard, on Team and Enterprise plans
AGENTS.md	Markdown instructions, a simpler alternative to `.cursor/rules`

The extension is the trap in Project Rules. The documentation says "A plain .md file in .cursor/rules is ignored by the rules system because it has no frontmatter to specify description, globs, and alwaysApply." Use .mdc, or use AGENTS.md instead.

Claude Code uses CLAUDE.md. Because Cursor reads AGENTS.md, the tidiest arrangement for using both is to keep the shared content in AGENTS.md and reference it from CLAUDE.md. Codex reads AGENTS.md too, which makes this pay off across all three.

Choosing between them

Situation	The better fit
You mainly want Claude's models	Claude Code
You want completions while writing in the editor	Cursor
You want settings to vary per project	Claude Code, where more than permissions is per-project
You are happy on Grok and Composer and want a cheap start	Cursor Plus
You are wiring it into CI	Either; both have a CLI, so follow your existing subscription

Model quality is left out deliberately, since it changes with each release. For the same comparison against other tools, see Codex vs Claude Code and Gemini CLI vs Claude Code.

Summary

Cursor is sold inside the X Subscription and includes Grok 4.7 / 4.6 / 4.5 and Composer 2.5
Third-party models are not included; Premium and above pay API list price from prepaid credit, and Plus cannot use them
Claude Code comes with Pro ($20/mo) and Max (from $100), and is not on Free
The permission syntax is close, but Cursor can only vary permissions per project
A plain .md in .cursor/rules is ignored; use .mdc or AGENTS.md

Codex CLI v0.164 adds /presets and inline /permissions arguments for permission profiles

aicoding-guide — Sun, 25 Oct 2026 19:17:04 +0000

Originally published at https://aicoding-guide.com.

Codex CLI v0.164.0 is the first release in a while with several genuine features. The two that matter are /presets and inline /permissions arguments.

The second is more than a typing shortcut. Behind it sits permission profiles, a beta mechanism that does not combine with the older sandbox_mode settings. Configure both without knowing that, and one of them is silently ignored.

Key point
What this article covers

What the ten /presets slots hold

How the permission profiles that /permissions selects are built

Why permission profiles and sandbox_mode cannot be used together

Ten preset slots for prompts

The release notes read: "Save reusable prompts and slash commands in ten numbered /presets slots, with a keyboard menu for quick access."

Reusable prompts and slash commands go into ten numbered slots, recalled from a keyboard menu. It gives the standing instructions you retype every session somewhere to live.

The other input-side addition is arguments for /model and /permissions: "Set model, reasoning effort, speed, and permission profiles directly with inline /model and /permissions arguments." Instead of opening a menu and choosing, you pass the value on the command.

/presets and /permissions are not in the official list
As of 2026-10-26, the official slash command list (28 entries) has no row for /presets or /permissions. That page does say "Available commands vary based on your environment and access", so availability may vary, but neither could be confirmed in the documentation. Nor is there any statement of where the preset slots are stored.

The permission profiles behind /permissions

The permission profiles that /permissions selects are a beta feature with their own documentation page: "A profile is a named policy that combines filesystem rules, which define what commands can read or write, with network rules, which define which destinations commands can reach."

Three profiles are built in.

Profile	What it does
`:read-only`	Keeps local command execution read-only
`:workspace`	Allows writes inside the active workspace roots and system temp directories
`:danger-full-access`	Removes local sandbox restrictions; only when that breadth is intended

Define your own under [permissions.<name>] and select it with the top-level default_permissions key.

default_permissions = "project-edit"

[features]
network_proxy = true

[permissions.project-edit.workspace_roots]
"~/code/app" = true
"~/code/shared-lib" = true

[permissions.project-edit.filesystem]
":minimal" = "read"

[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write"
".devcontainer" = "read"
"**/*.env" = "deny"

[permissions.project-edit.network]
enabled = true

[permissions.project-edit.network.domains]
"api.openai.com" = "allow"
"*.github.com" = "allow"
"tracking.example.com" = "deny"

The **/*.env deny line is the practically useful part: writes stay allowed inside the workspace while environment files are carved out.

network.enabled = true alone does not enforce domain rules
The documentation states: "A profile's network.enabled = true permits command network access, but it does not start the network proxy." To have the domain rules enforced, also set features.network_proxy = true in config.toml. Without an active proxy, those domain rules do not restrict direct network access.

Permission profiles and sandbox_mode do not mix

This is the part that catches people migrating. The documentation is explicit: "Permission profiles do not compose with the older sandbox settings. Configure either default_permissions and [permissions], or sandbox_mode / sandbox_workspace_write, but not both."

The resolution falls entirely to one side. If sandbox_mode appears anywhere in a loaded config file, if you pass --sandbox, or if the selected config profile sets sandbox_mode, Codex uses the older sandbox settings rather than default_permissions.

So a sandbox_mode line left over in ~/.codex/config.toml silently voids a permission profile you just wrote. Remove the old settings first. For the older model, see Combining approval_policy and sandbox_mode in Codex.

Credential masking and the other fixes

Two security changes landed. One is "Mask credentials during supported remote Bash commands and Zsh snapshot sessions", which covers custom provider credentials too. The other is "Hardened sandbox checks for case-variant metadata paths on macOS and replaceable symlinks used to locate executables."

Three fixes stand out:

A failed compaction no longer leaves partial summaries in conversation history
Resuming a session now finds compressed histories and restores saved thread settings
Windows HTTPS and WebSocket connections handle proxy authentication challenges with the signed-in user's credentials

Beyond those, enterprise MCP connections can authenticate through Codex account grants or a dedicated sign-in, and the Amazon Bedrock setup wizard is now on by default. For the previous release, see Codex CLI v0.163 turns Daybreak back on by default.

Summary

/presets stores reusable prompts and slash commands in ten numbered slots
/model and /permissions now accept their settings as inline arguments
The permission profiles /permissions selects are beta; the built-ins are :read-only, :workspace and :danger-full-access
Permission profiles do not combine with sandbox_mode; a leftover sandbox_mode wins
/presets and /permissions could not be confirmed in the official slash command list

This week in Claude Code, Codex and Gemini CLI (week of October 25, 2026)

aicoding-guide — Sat, 24 Oct 2026 19:08:18 +0000

Originally published at https://aicoding-guide.com.

This was a security fix week. Claude Code 2.1.309 carries more than ten fixes for routes around the sandbox and the permission checks. Codex 0.164.0 hardened its own sandbox checks and added credential masking.

Codex also shipped features. /presets stores prompts and slash commands in ten slots, and /model and /permissions now take their settings as arguments.

Key point
This week in brief

Claude Code 2.1.309 concentrates fixes for sandbox and permission-check bypasses

Codex 0.164.0 adds /presets and masks credentials in remote Bash

Claude Code gained the claude_code.safety_event OpenTelemetry event

Claude Code

Eight releases this week, 2.1.303 through 2.1.310.

Sandbox and permission bypasses (2.1.309)

This release is lopsided: it is largely a list of routes that worked when they should not have.

Route	What was wrong
Shell startup files	On macOS and Linux, every sandboxed Bash command ran the shell's startup files outside the sandbox first
Symbolic links	macOS `denyWrite` glob patterns did not apply at a path's real location when the pattern's folder was reached through a symlink
MCP config file	Sandboxed commands and auto-accepted edits could modify the config passed with `--mcp-config`
Redirects	The Bash permission check trusted a variable set by a command whose redirect can fail to open
Compound commands	A `cd` that was wrapped or prefixed before a git command did not prompt, as a plain `cd` does
Deny rules	An `Edit(path)` deny rule did not block a Bash redirect to that path in some commands holding a subshell
Worktree isolation	Locale-prefixed commands, and some zsh arithmetic commands, passed the isolation guard

On Windows, PowerShell permission checks were auto-approving some Set-Location and cd commands that carry extra arguments. 2.1.310 adds another: with Git Bash missing, PreToolUse and PermissionRequest hooks let a tool call through when the hook's command was only quoted strings.

Upgrade if you depend on deny rules or the sandbox
These are "configured but not actually enforced" fixes. If your setup assumes .env cannot be read or writes are confined, move to 2.1.310 and then review the rules themselves. Claude Code permissions in settings.json covers the syntax.

Telemetry and settings (2.1.305, 2.1.307)

claude_code.safety_event: a new OpenTelemetry event for each tool call that a permission rule, auto mode, a safety check, a hook or the sandbox stopped, prompted on, or sent back
sandbox.allowNestedUserNamespaces: lets sandboxed commands on Linux create user namespaces, for Chromium and rootless podman. The CHANGELOG also states plainly that this lets them get around the sandbox's file protections
CLAUDE_CODE_RETRY_WATCHDOG_USAGE_LIMIT_RECHECK_MS: unattended retry mode now notices a usage limit lifted before its reset

Easy ones to miss (2.1.304, 2.1.310)

CLAUDE_CODE_AUTO_COMPACT_WINDOW=200k silently set a 100K window. The variable now accepts k and M suffixes and warns when a value is out of range
A very large cleanupPeriodDays made background cleanup delete some recent files, such as pasted images
claude --worktree removed the worktree and its branch without asking at exit when HEAD was detached or on another branch, which could lose commits

Codex

v0.164.0 is a feature release.

Addition	What it does
`/presets`	Saves reusable prompts and slash commands in ten numbered slots, recalled from a keyboard menu
`/model` and `/permissions` arguments	Set model, reasoning effort, speed and permissions inline as arguments
Image preview	Shows viewed and generated images in the fullscreen transcript on Kitty or Sixel terminals
Enterprise MCP auth	Authenticates through Codex account grants or a dedicated sign-in, including OAuth clients that need secrets
Credential masking	Masks credentials in remote Bash commands and zsh snapshot sessions, custom provider credentials included
Bedrock setup	The Amazon Bedrock setup wizard is now on by default

On the security side, sandbox checks were hardened for case-variant metadata paths on macOS and for replaceable symlinks used to find executables — the same direction as Claude Code's symlink fixes this week.

Among the fixes, two stand out: a failed compaction no longer leaves a partial summary in history, and Windows HTTPS and WebSocket connections now handle proxy authentication with the signed-in user's Negotiate or NTLM credentials. For the previous release, see Codex CLI v0.163 turns Daybreak back on by default.

Gemini CLI

v0.65.0 (October 20) had one feature among 27 entries, the otlpHeaders telemetry setting. The change that matters more in practice is that workspace settings in an untrusted folder are now enforced as read-only. See Gemini CLI v0.65 enforces read-only settings in untrusted folders.

What to check now

Move Claude Code to 2.1.310, first if you rely on the sandbox or on deny rules
Check whether cleanupPeriodDays is set to an extreme value
If you wrote a suffixed value such as 200k for CLAUDE_CODE_AUTO_COMPACT_WINDOW, confirm it is the window you meant
Upgrade Codex to 0.164.0 if you use its sandbox

Summary

Claude Code 2.1.309 fixes more than ten ways around the sandbox and the permission checks
Sandboxed commands were running the shell's startup files outside the sandbox first
claude_code.safety_event makes blocked and prompted tool calls measurable
Codex 0.164.0 adds /presets, inline /model and /permissions arguments, and credential masking
Gemini CLI v0.65.0 enforces untrusted folder settings and adds otlpHeaders

Gemini CLI v0.65 enforces read-only settings in untrusted folders and adds OTLP headers

aicoding-guide — Thu, 22 Oct 2026 19:17:52 +0000

Originally published at https://aicoding-guide.com.

Gemini CLI v0.65.0 carries 27 changes, but only one is a feature: the telemetry OTLP exporter now accepts custom headers. The rest is 25 fixes and one performance change.

As in the previous release, untrusted folder handling and @ references both got attention. Those are the same two areas v0.64.0 touched, so this is the second release in a row working on them.

Key point
What this article covers

Workspace settings in an untrusted folder are now enforced as read-only

How to write otlpHeaders, the release's only new feature

Fixes around session resume, OAuth and @ references

Untrusted folder settings are enforced as read-only

PR #29583 makes workspace settings read-only in a folder you have not trusted.

Folder trust exists to stop an unvetted project from loading its own configuration. Per the documentation, an untrusted folder does not load .gemini/settings.json or .env, cannot install or update extensions, disables tool auto-acceptance, and does not connect to MCP servers.

v0.64.0 fixed headless mode treating an untrusted folder as trusted. This release continues that work by closing the write side. If your CI depends on the feature, v0.65.0 is the version that has both. For the previous release, see Gemini CLI v0.64 fixes the CPU hang on @ inside code.

Relatedly, PR #29672 removes false positives from the untrusted command flag and compound loop checks — the case where the check erred so far toward caution that ordinary commands were caught by it.

The only new feature is custom OTLP headers

PR #29641 adds otlpHeaders to the telemetry settings, so you can attach arbitrary headers to OTLP exporter requests. That is what you need when the collector you send to requires an authentication header.

{
  "telemetry": {
    "enabled": true,
    "target": "local",
    "otlpEndpoint": "http://localhost:4317",
    "otlpProtocol": "grpc",
    "otlpHeaders": {
      "x-api-key": "your-key"
    }
  }
}

The documentation's settings table defines it as:

Setting	Environment variable	Values	Default
`otlpHeaders`	`GEMINI_TELEMETRY_OTLP_HEADERS`	JSON or `key=value`	none

Because the environment variable works too, a CI job can pass the key from its own secret store instead of a settings file.

A key written into the header stays in the settings file
Putting an API key directly in otlpHeaders leaves it in .gemini/settings.json. If you commit that file, pass the value through GEMINI_TELEMETRY_OTLP_HEADERS instead.

Session resume and authentication fixes

Six fixes address losing work or failing to sign in.

PR	What it fixes
#29584	A resumed session's history being deleted on a quick exit (Issue #29198)
#29618	Duplicate tool response turns when resuming a session
#29728	Session poisoning on a rapid Ctrl-C interruption
#29655	Infinite verification and OAuth retry loops
#29643	Cached credentials now cleared when Google login is re-selected
#29616	OAuth callback `iss` validation aligned with RFC 9207 metadata

#29584 and #29728 are the kind of bug that costs you work. If you routinely resume long sessions, they are the reason to upgrade.

@ references and ignore-file performance

PR #29617 stops the eager recursive file reading that @ references triggered, so pointing at a directory with @src/ no longer pulls in its contents unconditionally.

v0.64.0 fixed the CPU hang on code containing @, so @ handling has now been worked on in two consecutive releases.

On performance, PR #29582 optimises ignore filtering and enables subtree pruning (Issue #29077), which helps when file discovery is slow in a large repository.

Also fixed: the Enter key hanging in interactive mode (PR #29476, Issue #23297), one extension failing the allowlist check preventing the others from loading (PR #29720), and unnecessary terminal clears when expanding with Ctrl+O (PR #29640). For MCP configuration, see Setting up MCP servers in Gemini CLI.

Summary

Of 27 entries in v0.65.0, one is a feature, one is performance, and 25 are fixes and release work
Workspace settings in an untrusted folder are now enforced as read-only
The feature is telemetry.otlpHeaders, also settable via GEMINI_TELEMETRY_OTLP_HEADERS
Resumed session history loss and session poisoning on rapid Ctrl-C are fixed
@ references no longer read recursively ahead of time, continuing v0.64's @ work

Gemini CLI v0.64 fixes the CPU hang on @ inside code and headless folder trust

aicoding-guide — Tue, 20 Oct 2026 19:18:57 +0000

Originally published at https://aicoding-guide.com.

Gemini CLI v0.64.0 adds no features. All 17 entries under "What's Changed" are fixes, refactors or release chores.

Two of them matter a great deal, though: a hang where piping code containing @ into -p pins the CPU at 100%, and a headless mode that treated untrusted folders as trusted. If the first sounds familiar, that alone is a reason to upgrade.

Key point
What this article covers

Why input like @scope/pkg hung the CLI, and the workaround that worked

How headless folder trust diverged from the actual trust decision

File writes and state persistence becoming atomic

Piping code with @ pinned the CPU at 100%

The fix is PR #29557 (Issue #29434). The symptom: piping code into -p on stdin made the CLI stop before it sent anything to the model. In the reporter's words, "The node process sits at ~100% CPU (state RN) indefinitely."

The trigger is input where an @-prefixed token is immediately followed by a double quote, with more quoted strings after it. In practice that means a scoped npm import.

import { x } from "@scope/pkg";
import { y } from "./local";

The symptoms were:

Aspect	Behaviour
Output	Nothing at all, not even an error
`--output-format stream-json`	Only the `init` event appears, then it stops
Signals	SIGINT and SIGTERM are ignored; only SIGKILL stops it
Versions reproduced	The reporter names v0.59.0 and v0.60.0

The reporter attributes the cause to the @-path regex matching across multiple quoted spans, so the result falls back to a glob whose large brace expansion minimatch then processes synchronously. That is the reporter's analysis; the fix itself is described only as stopping the CPU hang and quote swallowing caused by @ inside code.

A workaround if you cannot upgrade yet
The reporter writes that escaping every @ in the piped text avoids the hang. If a CI job pipes source code into gemini -p, add that preprocessing step until you can upgrade.

Headless treated untrusted folders as trusted

This is PR #29528 (Issue #29031). In headless mode (-p), the internal folder trust handling always passed the state through as trusted. The result was a mismatch: the warning said the folder was untrusted while the application-level check said it was trusted.

Folder trust exists to stop a project you have not vetted from loading its own configuration. According to the documentation, an untrusted folder disables all of the following:

The project's .gemini/settings.json is not loaded
The project's .env files are not loaded
Extensions cannot be installed, updated or uninstalled
Tool auto-acceptance is disabled, so every tool prompts
Automatic memory loading from directories in local settings is disabled
MCP servers are not connected
Custom .toml commands are not loaded, both project and user ones

So while the mismatch lasted, an untrusted folder's settings, hooks and MCP servers could still take effect in a headless run. If your CI relies on this feature, that is a reason to upgrade.

The docs disagree on the default
The settings table gives security.folderTrust.enabled a default of true. The Trusted Folders page says "The Trusted Folders feature is disabled by default." Both live on main in the same repository (checked 2026-10-21). Open /permissions to see which applies in your own setup.

To turn it on explicitly:

{
  "security": {
    "folderTrust": {
      "enabled": true
    }
  }
}

Decisions are stored in ~/.gemini/trustedFolders.json. Running headless against an untrusted folder exits with FatalUntrustedWorkspaceError, so a CI job that must proceed uses the --skip-trust flag or GEMINI_CLI_TRUST_WORKSPACE=true. For MCP configuration, see Setting up MCP servers in Gemini CLI.

Writes and state persistence became atomic

Three fixes address data corruption:

Fix	What changed
PR #29499	File tool operations are serialised and writes are atomic
PR #29558	State persistence is atomic, with recovery from a backup when the state is corrupt
PR #29568	Conversation recording uses append-only delta patching with bounded history windowing

These cover parallel file operations clobbering each other, and a state file left corrupt when the process dies mid-save. They matter most in long-running sessions.

Windows and interaction fixes

Four more that show up in daily use:

Windows ConPTY now forwards the IME cursor position (PR #29560), fixing misplaced cursors while composing text in an IME
Ctrl+C emergency abort now reaches the cancellation handler during active operations (PR #29586)
@file:line references and a ghost-text wrap hang are fixed (PR #29581)
Enter and Spacebar reliably confirm selection list options (PR #29502)

Beyond those, updating an extension on Windows now retries directory removal through file-locking errors (PR #29540), scroll position is preserved (PR #29520), and ACP resolves sessions by exact ID (PR #29580). For the previous release, see Gemini CLI v0.63 fixes the diff cannot spawn error.

Summary

v0.64.0 adds no features; all 17 "What's Changed" entries are fixes, refactors or release chores
Piping code containing @scope/pkg into -p no longer pins the CPU at 100%, a state only SIGKILL could end
Headless mode no longer treats an untrusted folder as trusted
File writes and state persistence are atomic, with backup recovery for corrupt state
The official docs give security.folderTrust.enabled both a true default and "disabled by default"

Codex CLI v0.163 turns Daybreak back on by default and makes /config searchable

aicoding-guide — Sun, 18 Oct 2026 19:19:07 +0000

Originally published at https://aicoding-guide.com.

Codex CLI v0.163.0 reverses a change that shipped five days earlier: Daybreak is on by default again. Alongside it come a searchable settings panel, mid-turn steering, and three security fixes in the network proxy.

Two things are worth acting on. If you had explicitly disabled Daybreak, check its current state. If you restrict network access in the sandbox, upgrade to 0.163.0.

Key point
What this article covers

Daybreak is the default again for eligible accounts

/config searches across categories, and you can steer a response mid-turn

The three fixes that landed in the network proxy

Daybreak is the default again

The release notes say "Daybreak is enabled by default for eligible accounts." In v0.161.0 it required --enable cli_daybreak or features.cli_daybreak=true, and daybreak=true alone was not enough. That requirement lasted five days.

# What v0.161.0 and v0.162.0 required
[features]
cli_daybreak = true

From v0.163.0, an eligible account does not need this. codex exec can also use Daybreak with an OpenAI API key now.

Do not treat this setting as settled
The same setting has moved twice in five days, and the release notes do not define what makes an account "eligible". If cli_daybreak is written into a runbook or a shared config.toml, verify the real behaviour after upgrading. What changed in Codex CLI v0.161 and v0.162 covers how it worked before.

/config and mid-turn control

How you find settings, and what happens when you interrupt, both changed.

Change	What it does
`/config`	Searches preferences across categories. Supported changes apply in place, and ones needing a restart are marked as such
Follow-ups mid-response	Send a follow-up while Codex is responding to steer it immediately
Interrupting a turn	Also stops running Code Mode cells and nested tool calls
Leader key in `/keymap`	The default is `Ctrl+X`. Voice mute moved to `F9`
`/daemon`	Restarts a managed background server, warning about work that may be interrupted
`/side`	A temporary side chat. It persists across thread switches, and prompt answers go back to the originating thread
Parallel read-only tools	Independent reads such as skills, memories and conversation history run in parallel

/config, /keymap and /daemon are not in the official list
As of 2026-10-19 the official slash command reference has no entry for /config, /keymap or /daemon. They appear only in the release notes. The reference does list /approve, /compact, /model, /plan, /review, /side, /status and /worktree, among others, and describes /side as "Start a temporary side chat without interrupting the main chat."

The network proxy and the sandbox

Three security fixes landed:

The network proxy now checks permission before a DNS lookup
It rejects duplicate Host headers
Credential aliases can no longer bypass the inspection hooks

The first matters most in practice. Previously name resolution could run ahead of the permission decision, so even a connection you blocked could leak to your DNS server which host was about to be contacted. Resuming a saved thread now also restores its permission and network approvals.

On the documentation side, the Linux sandbox section was updated. The official sandboxing page says that on Linux and WSL2 you install bubblewrap with your package manager first, that Codex uses the first bwrap executable it finds on PATH, and that without one it falls back to a bundled helper which "requires support for unprivileged user namespace creation". Codex shows a startup warning when bwrap is missing or the helper cannot create the namespace.

Glossary
bubblewrap (bwrap): a Linux sandboxing tool that isolates processes using namespaces without needing privileges. Codex uses it to limit where commands can write and what they can reach over the network.

The release notes say the Linux sandbox documentation now also explains seccomp, but as of 2026-10-19 no mention of seccomp could be found on the official sandboxing page. For how approvals and the sandbox interact, see Combining approval_policy and sandbox_mode in Codex.

The bundled zsh is gone

Codex no longer bundles a patched zsh and uses its standard shell executor instead. Configurations that use the retired shell flags get a migration notice.

The names of those flags could not be confirmed in the official configuration reference, so if the notice appears, follow what the message itself says. For the structure of the configuration file as a whole, see Configuring Codex with config.toml.

Two smaller items: the Linux and macOS release binaries are smaller because symbols are stripped from the packaged copies, and codex exec no longer repeats file diffs after unrelated commands. Clipboard paste handling on Windows and WSL was also fixed.

Summary

v0.163.0 makes Daybreak the default for eligible accounts; cli_daybreak is no longer needed
/config searches settings across categories and marks changes that need a restart
You can send a follow-up mid-response, and interrupting also stops Code Mode cells
The network proxy checks permission before a DNS lookup and rejects duplicate Host headers
/config, /keymap, /daemon and the retired shell flag names could not be confirmed in the official docs

This week in Claude Code, Codex and Gemini CLI (week of October 18, 2026)

aicoding-guide — Sat, 17 Oct 2026 19:13:13 +0000

Originally published at https://aicoding-guide.com.

The change with the widest reach this week is idle compaction in Claude Code. Leave a long conversation sitting and it now gets summarised on its own.

On the Codex side, Daybreak is enabled by default again — a setting that only became an explicit opt-in five days earlier in v0.161.0. It has flipped twice in under a week.

Key point
This week in brief

Claude Code compacts idle conversations automatically (idleCompaction turns it off)

Codex 0.163.0 made Daybreak the default for eligible accounts again

CLAUDE_CODE_DISABLE_FILE_MENTIONS and CLAUDE_CODE_AUTO_MODE_MODEL were added

Claude Code

Four releases this week, 2.1.299 through 2.1.302.

Idle compaction arrived (2.1.299, 2.1.302)

The CHANGELOG wording is: "Added idle compaction in the terminal: a 200K+ token conversation left idle for about 54 minutes is compacted before its one-hour prompt cache expires, so your next message doesn't reprocess it all."

The motivation is cost. Leave a conversation above 200K tokens idle for roughly 54 minutes and it is summarised before the one-hour prompt cache expires, so your next message does not pay to reprocess everything. The prompt caching documentation also notes that Claude Code may compact when idle, and that idleCompaction disables it.

Setting	What it does
`"idleCompaction": false`	Turns off automatic idle compaction (v2.1.290+)
`CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS`	Changes the 200K token threshold (v2.1.290+)
`Idle compaction` row in `/config`	Toggles it from the UI (added in v2.1.302)

Know what compaction drops before you leave it on
Compaction replaces the conversation layer with a summary. CLAUDE.md itself is re-read from disk, but the contents of files that Claude read because CLAUDE.md told it to are folded into the summary. Context management with /compact and /clear covers the difference. If your workflow depends on what is in the window, turn it off.

New environment variables (2.1.299, 2.1.301, 2.1.302)

Variable	What it does
`CLAUDE_CODE_DISABLE_FILE_MENTIONS`	Claude gets the paths of `@` file mentions rather than their contents, and reads them with its own file tools
`CLAUDE_CODE_AUTO_MODE_MODEL`	Chooses the model the client-side auto mode classifier uses. It does not change server-side auto mode
`CLAUDE_CODE_RETRY_WATCHDOG_MAX_USAGE_LIMIT_WAIT_MS`	In unattended retry mode, exits instead of waiting out a usage limit whose reset is too far off

CLAUDE_CODE_DISABLE_FILE_MENTIONS is the useful one if @-mentioning a large file keeps filling your context in one shot.

Security fixes (2.1.301, 2.1.302)

The Read tool loaded an image file of any size — or a pipe or device named like an image — entirely into memory. Image sources over 128 MB are now refused
Quitting removed a worktree made by a WorktreeCreate hook without asking, even when it might hold unpushed commits

Telemetry

The OpenTelemetry api_request event now splits cache writes by lifetime with cache_creation_5m_tokens and cache_creation_1h_tokens. The tool_decision event gained classifier_verdict, permission_mode and classifier_category, so you can tell an auto mode classifier decision apart from one made by a permission rule.

Codex

Daybreak is the default again (0.163.0)

/config and steering (0.163.0)

/config: search preferences across categories, change supported ones in place, and see which changes need a restart
Follow-ups mid-response: send a follow-up while Codex is responding to steer it immediately. Interrupting a turn also stops running Code Mode cells and nested tool calls
Leader key in /keymap: the default is Ctrl+X. Voice mute moved to F9
Parallel read-only tools: independent reads such as skills, memories and conversation history now run in parallel

Network and sandbox (0.163.0)

Three proxy fixes landed: the network proxy now checks permission before a DNS lookup, rejects duplicate Host headers, and prevents credential aliases from bypassing inspection hooks. Resuming a saved thread now restores its permission and network approvals too.

One operational change: Codex no longer bundles a patched zsh and uses its standard shell executor instead. Configurations using the retired shell flags get a migration notice.

Gemini CLI

v0.64.0 is fixes only. The notable ones: a CPU hang and swallowed quotes when @ appears in code, file tool operations serialised with atomic writes, and atomic state persistence with recovery from a backup when the file is corrupt. On Windows, ConPTY now forwards the IME cursor position.

What to check now

Decide how you feel about idle compaction. If you do not want conversations summarised unprompted, turn it off in /config or with "idleCompaction": false
If you had explicitly disabled Daybreak in Codex, check its current state — the default moved
Upgrade Claude Code to 2.1.302 or later if the Read tool image issue matters to you
Upgrade Codex to 0.163.0 if you restrict network access in the sandbox, for the pre-DNS permission check

Summary

Claude Code now compacts idle conversations: 200K+ tokens left for about 54 minutes
Turn it off with "idleCompaction": false, tune it with CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS, toggle it in /config
CLAUDE_CODE_DISABLE_FILE_MENTIONS passes @ mentions as paths instead of contents
Codex 0.163.0 made Daybreak the default again for eligible accounts, reversing v0.161.0
Gemini CLI v0.64.0 is fixes only

Claude Code on Windows, native or WSL, and what trips people up

aicoding-guide — Fri, 16 Oct 2026 19:22:28 +0000

Originally published at https://aicoding-guide.com.

Claude Code started out aimed at macOS and Linux, with Windows users pointed at WSL. There is now a native Windows build you can run straight from PowerShell. Which one to choose comes down to one question: do you need sandboxing?

This article compares the two, gives the install steps for each, and collects the things that actually trip people up.

Key point
What you will learn

Native versus WSL, and the sandboxing difference that decides it

Install steps for each, and whether Git for Windows matters

The gotchas: hooks, paths, encoding and line endings

Native versus WSL 2

	Native Windows	WSL 2
Runs on	Windows directly	Linux inside WSL (Ubuntu, etc.)
Requires	Nothing; Git for Windows is optional	WSL 2 enabled
Sandboxing	Not supported	Supported
Shell tool	Git Bash when Git for Windows is installed, otherwise the PowerShell tool	bash / zsh
Where projects live	Windows drives (`C:\...`)	Inside WSL (`/home/...`) is recommended
Linux tooling such as Docker	Needs a Windows build	Linux builds work as-is
Suits	Windows-native development (.NET, Node)	Linux toolchains, or sandboxed command execution

WSL 1 is the third option, for when WSL 2 is unavailable; like native Windows, it does not support sandboxing.

Touching Windows files from WSL is slow
Working on a project under /mnt/c/... from WSL makes file I/O dramatically slower. If you choose WSL, keep the project inside WSL, under ~/projects/ for example.

Installing the native build

1. Git for Windows (optional)

The documentation calls Git for Windows optional. With it, Git Bash backs the Bash tool; without it, Claude Code runs shell commands through the PowerShell tool. If your hooks and scripts assume bash, install it. The defaults from Git for Windows are fine.

With Git for Windows installed, the PowerShell tool is available alongside Bash: on by default for claude.ai and Console accounts, and enabled with CLAUDE_CODE_USE_POWERSHELL_TOOL=1 in Amazon Bedrock, Google Cloud's Agent Platform and Microsoft Foundry sessions. Set it to 0 to turn the tool off.

2. Install Claude Code

Open PowerShell and run:

irm https://claude.ai/install.ps1 | iex

In CMD the command is different — your prompt shows PS C:\ in PowerShell and C:\ without the PS in CMD:

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

WinGet works too, but a WinGet install does not auto-update, so run winget upgrade Anthropic.ClaudeCode periodically:

winget install Anthropic.ClaudeCode

The npm package is another option and needs Node.js 22 or later. You do not need to run the installer as Administrator.

3. Start it and check

cd C:\path\to\project
claude

The first run prompts you to log in. claude doctor reports installation health and settings-file validation errors without starting a session.

If Claude Code cannot find Git Bash, point at it in your settings file:

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}

Installing in WSL

Sandboxed command execution requires WSL 2; WSL 1 does not support it.

Run wsl --install in an elevated PowerShell and restart. Ubuntu is installed by default.
Open the Ubuntu terminal and install Node.js if you plan to use the npm package (nvm is the easy route).
Install with the Linux command — you run it inside the WSL terminal, not from PowerShell or CMD:

curl -fsSL https://claude.ai/install.sh | bash

For VS Code, install the WSL extension, open a folder inside WSL, and install the Claude Code extension into WSL.

What trips people up

Hooks and scripts run through Git Bash

With Git for Windows installed, the Bash tool uses Git Bash, so PowerShell cmdlets are not available directly. Invoke PowerShell explicitly instead:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "powershell -NoProfile -File .claude/hooks/format.ps1"
          }
        ]
      }
    ]
  }
}

For hook basics, see Run lint and format on save with Claude Code hooks.

Writing paths

In permission patterns and CLAUDE.md, forward slashes (src/**) work on Windows too. Avoid backslashes, which need escaping inside JSON.

Encoding

If command output comes back garbled, set PowerShell's output encoding to UTF-8:

[Console]::OutputEncoding = [System.Text.Encoding]::UTF8

Line endings

A CLAUDE.md or hook script saved with CRLF by a Windows editor can fail under Git Bash when a stray \r ends up in the script. Set *.sh text eol=lf in .gitattributes and save scripts with LF.

Summary

Install natively from PowerShell with irm https://claude.ai/install.ps1 | iex; Git for Windows is optional, and without it the PowerShell tool runs commands
Sandboxing means WSL 2. Native Windows and WSL 1 do not support it. Keep projects inside WSL when you go that route
Write hooks and scripts for Git Bash, and keep line endings at LF
Fix garbled output with UTF-8 output encoding, and use forward slashes in paths

Run Claude Code in GitHub Actions with claude-code-action

aicoding-guide — Fri, 16 Oct 2026 19:22:27 +0000

Originally published at https://aicoding-guide.com.

Comment "@claude fix this bug" on an issue and have Claude Code implement the fix and open a pull request. Have a review appear automatically when a PR opens. Both come from the official claude-code-action, configured with workflow files in your repository.

This article covers setup, the two basic configurations — mention response and automated review — and how to limit permissions and cost.

Key point
What you will learn

Setting up with /install-github-app, and which authentication secret to use

The workflow that responds to @claude mentions

The automated review workflow, who can trigger runs, and how to cap cost

Setting up

Run /install-github-app from Claude Code inside the repository. It installs the Claude GitHub App, sets up the authentication secret, and pushes a branch with the workflow files, opening a pull request for you to create. You need admin access to the repository, and the GitHub CLI installed and authenticated with gh auth login.
Register the authentication secret. Use ANTHROPIC_API_KEY for a Claude API key from the Claude Console, or CLAUDE_CODE_OAUTH_TOKEN for a subscription token generated with claude setup-token. In the workflow, pass them to anthropic_api_key and claude_code_oauth_token respectively.
Create and merge the pull request. @claude then works in the repository.

/install-github-app only works with github.com repositories; on a gitlab.com or bitbucket.org remote it prints a notice and exits. For manual setup, install the Claude GitHub App yourself, add the secret, and copy examples/claude.yml into .github/workflows/.

Glossary
The GitHub App and GITHUB_TOKEN: by default the action authenticates as the Claude GitHub App. If you pass github_token: ${{ secrets.GITHUB_TOKEN }} instead, GitHub won't trigger workflows on the commits Claude makes — the documented fix for "CI not running on Claude's commits" is to remove that line.

Configuration 1: respond to @claude mentions

name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]

jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write
      actions: read
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

id-token: write is required for the action's default GitHub App authentication, and actions: read lets Claude read CI results on PRs. With no prompt input, the action runs in interactive mode and waits for the trigger phrase — @claude by default, changeable with trigger_phrase.

Requests that work well:

On an issue: "@claude reproduce this and open a PR with a fix"
On a review comment: "@claude add error handling to this function"
On a PR: "@claude add tests for what this change affects"

Configuration 2: review automatically when a PR opens

Supplying a prompt input puts the action in automation mode, which runs without waiting for a mention. The configuration the documentation now shows calls the code-review plugin's skill rather than a free-text prompt:

name: Code Review
on:
  pull_request:
    types: [opened, synchronize, ready_for_review, reopened]

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: read
      issues: read
      id-token: write
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          plugin_marketplaces: "https://github.com/anthropics/claude-code.git"
          plugins: "code-review@claude-code-plugins"
          prompt: "/code-review:code-review --comment ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"
          claude_args: '--allowedTools "mcp__github_inline_comment__create_inline_comment"'

Without --comment, nothing is posted
In automation mode, "By default, results appear in the workflow run log rather than a comment." --comment is what makes Claude post on the pull request. Keep the claude_args line too: even though the skill's own allowed-tools frontmatter names the same tool, the action starts the inline-comment MCP server only when --allowedTools in claude_args names it.

With a free-text prompt you have to grant the tools yourself: "For a plain-text prompt, Claude has no shell or GitHub API access until you grant the tools the prompt needs" — through --allowedTools in claude_args, or a permissions.allow rule in the settings input.

Claude skips draft and closed pull requests, ones it judges not to need review, and ones that already carry a comment from Claude.

Limiting permissions and cost

Goal	How
Keep outsiders from triggering runs	Already checked by the action (see below). Narrow further with an `if:` on `github.event.comment.author_association`
Minimize write access	Give the review workflow `contents: read`
Restrict the tools	Pass `--allowedTools` in `claude_args`
Cap the work per run	Pass `--max-turns`, and set a workflow-level timeout
Enforce your project's rules	Put them in the repository's `CLAUDE.md`, which the action reads

Glossary
Who can trigger a run is checked by the action itself: two checks run before Claude starts, and the run fails if either rejects it. Write access — on issue and pull request events the triggering user must have write access to the repository; to allow specific users without it, set allowed_non_write_users and pass your own github_token. Human actor — a bot actor is rejected unless listed in allowed_bots, which keeps bots from triggering Claude in a loop. That check also applies to scheduled runs, which GitHub attributes to a repository user.

Secrets and pull requests from forks
On public repositories, GitHub withholds secrets from runs triggered by fork pull requests, so a review workflow runs only on pull requests from branches in the same repository. Before reaching for pull_request_target to change that, understand that it runs the fork's code with your secrets available.

How this relates to CLAUDE.md

Claude inside the action reads the repository's CLAUDE.md the same as it does locally — the documentation lists "Define project standards in CLAUDE.md" as a best practice, and notes that Claude reads it on every run, so keeping it concise also keeps cost down. Review criteria and prohibitions belong there rather than in the workflow's prompt, so you maintain one copy (How to write CLAUDE.md).

For a lighter setup that calls claude -p directly instead of using the official action, see Run Claude Code headless in CI.

Summary

/install-github-app installs the app and workflows; register ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN as the secret
No prompt means interactive mode and the @claude trigger; a prompt means automation mode
In automation mode results go to the run log unless you pass --comment and name the inline-comment tool in claude_args
Write access and a human-actor check already gate who can trigger runs; allowed_bots and allowed_non_write_users adjust them
Keep review criteria in CLAUDE.md, and cap cost with --max-turns, a smaller model, and workflow timeouts