Kiro stuck in Working: fix terminal integration before clearing cache

If Kiro is stuck in Working on a terminal command, check shell integration before deleting cache. Kiro documents shell customizations as a common cause. Save your changes, enable integration, restart, and test terminal output. Kiro's documentation has no clear-cache command or procedure as of October 9, 2026, so this guide does not prescribe one. Kiro troubleshooting guide.

Sources checked: October 9, 2026.

Protect the work before changing the IDE

Save modified project files and copy the last command and visible output before restarting. This is a precaution, not a promise that restarting restores an interrupted task. Kiro checkpoints guide.

Do not select Restore merely to unfreeze Kiro. The IDE's checkpoint markers restore code and conversation context to the selected point, reverting subsequent agent changes. Use a checkpoint only when you intend to undo that work.

Fix shell integration for Working...

  1. For the error shell integration unavailable, open the Command Palette with Cmd+Shift+P on macOS or Ctrl+Shift+P on Windows/Linux. Run Kiro: Check for Updates, then Kiro: Enable Shell Integration. Quit and reopen Kiro.

  2. If you use Powerlevel10k, Kiro documents adding the following setting to .p10k.zsh. Alternatively, disable the interfering shell theme or customization when running inside Kiro.

    typeset -g POWERLEVEL9K_TERM_SHELL_INTEGRATION=true
  3. After reopening, test a simple command and check that Kiro reads the output before resuming the original command. Check its earlier result first if repeating it could write files or trigger an external action.

Kiro clear cache: what is not verified

The troubleshooting page does not supply a cache-deletion path or establish that cache corruption caused this Working state. Avoid treating a full local-data reset as the next automatic step.

Issue #6780 in Kiro's official repository is a user report, not a supported cleanup recipe. It describes conversation session files inside ~/Library/Application Support/Kiro/User/globalStorage/kiro.kiroagent/ on macOS. Do not assume that directory is disposable cache or that the report proves your own cause. Kiro conversation-storage issue 6780.

If the documented fix fails, report your operating system, Kiro version, attempted steps and exact error to Kiro's issue tracker. Ask for version-specific backup and cleanup guidance before removing local data.

Manual shell integration and Fish output

When automatic setup fails, Kiro documents manual integration in the shell configuration. In ~/.zshrc, use:

[[ "$TERM_PROGRAM" == "kiro" ]] && . "$(kiro --locate-shell-integration-path zsh)"

For Bash, use the same conditional in ~/.bashrc with bash in place of zsh. For Fish, add this to ~/.config/fish/config.fish:

string match -q "$TERM_PROGRAM" "kiro"
and . (kiro --locate-shell-integration-path fish)

For PowerShell, add the documented conditional to $Profile:

if ($env:TERM_PROGRAM -eq "kiro") { . "$(kiro --locate-shell-integration-path pwsh)" }

For Fish terminal-output problems on macOS, the documented integration file is /Applications/Kiro.app/Contents/Resources/app/out/vs/workbench/contrib/terminal/common/scripts/shellIntegration.fish. Its TERM_PROGRAM check must accept kiro as well as vscode; retain the interactive-session and existing-integration guards. Update that check to:

and string match --quiet "$TERM_PROGRAM" "vscode" "kiro"

How ShardStitch helps

ShardStitch can preserve available project changes and task notes while you troubleshoot. It does not clear Kiro cache or prove a command finished. Coverage and limitations. Pricing.