What shipped
Claude Code v2.1.261 (4 September 2026) added two settings in one changelog line: "Added bashOutputMaxChars and taskOutputMaxChars settings to raise how much command and background-task output Claude receives inline before it is saved to a file, up to 128K characters." Neither settings-reference nor tools-reference, both fetched in full while researching this piece, had a dedicated entry for either key yet. What follows draws on that one changelog line plus the Bash tool's own output-handling mechanism, which is documented in detail and which these two settings evidently extend.
The output pipeline these settings sit inside
To understand what's new, it helps to know how Claude Code already handles command output, because that system didn't change, these settings just add a lever to part of it. Per Claude Code's tools reference:
Claude Code streams a command's output to a working file as the command runs; a command whose output passes 5 GB is killed. When the command finishes, Claude Code reads the output back from that file, up to the read-back window described below. How much of the output reaches Claude inline depends on whether Claude Code treats the result as a failure:
| Result | What Claude gets |
|---|---|
| Valid | Inline up to roughly 30,000 characters; past that, the path of a file saved to the session directory, truncated past 64 MiB, plus a short preview from the start, and Claude reads or searches the file when it needs the rest |
| Failure | Inline up to roughly 10,000 characters; past that, a head-and-tail excerpt of that size cut from the read-back window, with no file path |
There's a second number in this system, the read-back window itself, controlled by the BASH_MAX_OUTPUT_LENGTH environment variable: "Maximum number of characters of bash output that Claude Code reads back into a command's result (default: 30000; maximum: 150000)." That variable decides how much of a command's total output Claude Code even considers, before the valid/failure table above decides how much of that considered amount actually lands inline versus behind a file path.
Before v2.1.261, the inline ceiling for a valid result, roughly 30,000 characters, was effectively fixed. You could widen the read-back window with BASH_MAX_OUTPUT_LENGTH up to 150,000 characters, which changed how much of a failing command's excerpt you got and how large a file the full output was saved as, but a successful command's output still hit the same roughly-30,000-character wall before falling back to a file path plus preview. bashOutputMaxChars targets that specific ceiling directly, raising it up to 128K characters rather than leaving it fixed regardless of how wide you'd opened the read-back window.
Why the Task tool getting its own setting is the bigger change
The tools reference documents the Bash output-limits system in detail, valid/failure table, working file, 5 GB kill threshold, all of it. It does not, as of this writing, document an equivalent limit for the Task tool, the mechanism behind background tasks and subagents. taskOutputMaxChars is the first setting giving that category of output a comparable, named, configurable ceiling.
That gap makes some sense in hindsight. A subagent or background task's output has historically been handled as part of whatever mechanism returns its result to the parent conversation, without the same dedicated streaming-to-a-working-file treatment Bash commands get. A background command started by a subagent, per Claude Code's changelog history, used to run under a one-hour limit before that cap was removed entirely so such commands "run until they exit or are stopped, matching the main session." Output volume from long-running background work is exactly the kind of thing that grows unpredictably once a time limit stops being the constraint, which is a plausible reason a dedicated character ceiling became worth adding now rather than earlier.
When to raise either setting
The trade-off is the same one that already applies to BASH_MAX_OUTPUT_LENGTH: more output reaching Claude inline costs more tokens on every turn that produces it. Raise bashOutputMaxChars when a command you run routinely produces valuable output past the default ceiling that you actually want Claude reading directly rather than fetching from a saved file on demand, a verbose build log where the interesting error is buried past character 30,000, or a linter run whose full output matters for the next step. Raise taskOutputMaxChars under the same logic for background tasks and subagents whose results tend to be large: a subagent that returns a long analysis, or a background job whose full log you want folded straight into the parent conversation rather than requiring a follow-up read.
Neither setting is free. If most of a command's output is routine noise with the useful part concentrated near the start or end, the existing file-plus-preview fallback (or, for a failing command, the head-and-tail excerpt) is often the cheaper default, since Claude can still search or read the saved file when it actually needs more. Raising the ceiling makes sense specifically when the useful signal is spread through the middle of long output, where a preview or excerpt would miss it.
{
"bashOutputMaxChars": 80000,
"taskOutputMaxChars": 80000
}
Given the changelog states an upper bound of 128K characters for both, values above that ceiling would presumably be clamped, the same pattern Claude Code uses elsewhere, for instance BASH_MAX_OUTPUT_LENGTH's own 150,000-character maximum.
The three settings side by side
Between them, BASH_MAX_OUTPUT_LENGTH, bashOutputMaxChars and taskOutputMaxChars now cover three different points in the same pipeline, which is easy to conflate if you only skim the names:
| Setting | Kind | Controls | Default / ceiling |
|---|---|---|---|
BASH_MAX_OUTPUT_LENGTH | Environment variable | How much of a command's total output Claude Code reads back from the working file at all | 30,000 default; 150,000 ceiling |
bashOutputMaxChars | Setting | How much of a valid Bash result's read-back output arrives inline versus as a file path plus preview | Previously fixed near 30,000; raisable up to 128K |
taskOutputMaxChars | Setting | The equivalent inline ceiling for background-task and subagent output | Not previously documented as a separate limit; raisable up to 128K |
Read top to bottom, that's roughly the order the pipeline applies them in: BASH_MAX_OUTPUT_LENGTH first decides how much of the command's output is even in play, then the inline ceiling, now configurable via bashOutputMaxChars, decides how much of that in-play amount actually lands in Claude's context versus behind a file reference. Raising the environment variable without also raising bashOutputMaxChars widens what's available to read back without changing how much of it shows up automatically; raising bashOutputMaxChars without a wide enough read-back window has nothing extra to draw on. Getting more of a very long, valid command's output inline generally means raising both together.
A worked scenario
Say a project's test suite regularly produces 40,000 to 60,000 characters of output when something fails, well past the roughly-30,000-character inline ceiling for a valid result, and past the 10,000-character ceiling for a failure too. Before v2.1.261, a failing run beyond that point would only reach Claude as a 10,000-character head-and-tail excerpt, which can genuinely miss a failure buried in the middle of a long log. Raising BASH_MAX_OUTPUT_LENGTH widens the window that excerpt is cut from, but the excerpt itself stays capped at roughly 10,000 characters either way for a failing result, per the documented table above.
For the valid-result case specifically, though, and for any background task producing comparably long output, bashOutputMaxChars and taskOutputMaxChars are the more direct fix: instead of Claude Code deciding a valid result over 30,000 characters must become a file path plus preview, a project routinely producing output in the 40,000 to 80,000 character range can raise the inline ceiling to match, and get the full thing inline on every run rather than a preview it then has to fetch the rest of.
What happens to output that still doesn't fit
Even at the maximum of 128K characters, some command and task output will still exceed the inline ceiling, a full CI log or a large dataset dump can run well past that. The documented fallback for a valid result stays the same regardless of where the ceiling sits: Claude Code saves the excess to a file in the session directory, truncated past 64 MiB, gives Claude a short preview from the start of it, and lets Claude read or search that file directly when it actually needs more. Raising bashOutputMaxChars or taskOutputMaxChars moves the point at which that fallback kicks in, it doesn't remove the fallback itself, which is worth knowing if you're tempted to max out both settings expecting every command's output to always arrive inline from then on. For genuinely huge output, the file-based fallback remains the mechanism doing the real work, and Claude reading a saved file on demand is often no slower in practice than a very long inline block would have been to process anyway.
Troubleshooting
The settings aren't recognised. They require Claude Code v2.1.261 or later. Check with claude --version.
Output is still arriving as a file path despite raising bashOutputMaxChars. Confirm the command's result is being treated as valid, not a failure. The documented table applies different ceilings to each case, and it isn't yet confirmed whether bashOutputMaxChars affects the failure-case ceiling as well as the valid-result one; treat the failure path as unchanged unless you've confirmed otherwise on your own version.
Raising taskOutputMaxChars didn't change anything for a subagent's output. Some subagent result paths may not route through the same mechanism this setting targets, since Claude Code's own documentation hadn't confirmed the exact scope of taskOutputMaxChars at the time of writing. If a specific background task's output still truncates the same way after raising it, that's worth treating as a real gap to report rather than a misconfiguration.
Context use has grown noticeably since raising either setting. That's the expected trade-off, not a bug. Lower the value back toward the roughly-30,000-character default for the specific command or task type causing it, or use /skill-doctor and /context to see where your context budget is actually going before deciding whether the trade is worth it.
Where this fits with Claude Code's other context controls
These two settings join a growing list of context-budget knobs Claude Code exposes deliberately rather than hiding behind fixed defaults: the skill listing budget, prompt cache TTL settings, and now the inline ceiling for command and task output specifically. None of them change what Claude can eventually access, a saved file is still readable on request either way, they change what arrives automatically versus what has to be fetched. For the full picture of Bash's output pipeline these settings extend, see Claude Code's tools reference, and for the CLI more broadly, browse Claude Code's platform page.