Claude Code Finally Supports AGENTS.md: CLAUDE.md Is No Longer the Only Option

Hi everyone, it's me! While checking out the newest Claude Code release, I found a change that felt like it had been on people's wish lists for a while. Let me walk you through it.

Claude Code Release github.com

What was announced?

Claude Code's release notes (GitHub Releases) just published the changelog for version v2.1.277. The headline change is added support for AGENTS.md: in a project that doesn't have a CLAUDE.md, Claude Code now reads AGENTS.md instead and uses it as the project instructions. You can change this behavior under "Project instructions" in /config. It's not yet available on Bedrock, Vertex, or Foundry, though.

There's also a new environment variable for the Claude apps gateway, CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1, meant for gateways whose only egress path is a forward proxy: every outbound request now hands the proxy the hostname instead of resolving it locally. Alongside that, gateway upstreams gained an optional headers map, so you can send static headers to a proxy you run in front of a provider.

On top of that, when a background task finishes while a panel like /tasks is open, Claude Code now shows a line letting you know an update is waiting.

The story so far

Until now, the only file Claude Code would read for project-specific instructions was CLAUDE.md. Some other agent tooling instead uses the name AGENTS.md, so teams using multiple tools on the same project sometimes ended up maintaining duplicate instruction files, or found that only one tool was actually reading them.

There was also a frustrating session-level bug: claude -p and Agent SDK sessions could hit an internal error and then just hang with no result, giving you no indication of what went wrong. That's an especially annoying failure mode when you're running Claude Code inside an automation pipeline.

What changes

• Projects without a CLAUDE.md can now use AGENTS.md directly as their project instructions
• Teams using multiple agent tools can consolidate around a single instructions file more easily
• Environments that can only reach the outside world through a forward proxy can set CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1 to hand hostnames straight to the proxy instead of resolving them locally
• Teams running their own proxy in front of a provider can now attach static headers to those requests
• claude -p and Agent SDK sessions no longer hang silently after an internal error — they report the error and exit with code 1

Dive Deep

This release also includes a batch of bug fixes for issues that were genuinely painful in day-to-day use.

• Fixed conversations failing every subsequent request with "text content blocks must be non-empty" when an earlier assistant turn held an empty text block beside other content — this could also happen after --resume
• Fixed being unexpectedly logged out when an older Claude Code build (for example, an IDE extension's bundled CLI) runs on the same machine as the current one
• Fixed interactive startup hanging or showing an error for ANTHROPIC_API_KEY users when ~/.claude.json holds a malformed customApiKeyResponses value
• Fixed update checks erroring every 30 minutes, and claude update hanging when a minimum or maximum version is set, if a proxy returns an invalid version; a malformed minimumVersion is now ignored

There are also smaller fixes around claude update behavior on winget-based installs.

Wrap-up

• Claude Code now supports AGENTS.md as a fallback when there's no CLAUDE.md (not yet on Bedrock, Vertex, or Foundry)
• CLAUDE_GATEWAY_PROXY_IS_EGRESS_BOUNDARY=1 changes hostname resolution behavior for forward-proxy-only environments
• Gateway upstreams gained a headers map for sending static headers to a proxy you run yourself
• Fixed hangs in claude -p and the Agent SDK, empty-text-block errors, and unexpected logouts

This update should especially resonate with teams running multiple agent tools side by side, and with the people managing Claude Code deployments behind corporate proxies. If you've been hit by hangs in automation pipelines, this version should bring some relief!