About

Claude Code Rust is a native Rust terminal interface for Claude Code. It replaces the stock Node.js and React Ink terminal UI with a Ratatui-based binary while keeping Claude Code functionality routed through Anthropic’s Agent SDK.

The goal is a faster, lower-memory terminal experience with reliable scrollback, direct terminal rendering, native input handling, and a project-local configuration surface.

Project Status

The project is pre-1.0. The crate version in the root Cargo.toml and the Changelog are the source of truth for the current release.

The project is useful today, but the runtime still depends on the upstream Claude Agent SDK bridge. Startup readiness, authentication behavior, billing, model availability, and service limits are controlled by Anthropic.

Relationship To Anthropic

This project is not affiliated with, endorsed by, or supported by Anthropic. It is a third-party terminal UI that talks to the official Agent SDK through a local TypeScript bridge. It is not a fork, copy, or port of Anthropic’s Claude Code source.

For official Claude documentation, use the Claude documentation:

• Claude Docs
• Claude Code Agent SDK overview

Billing Note

Because Claude Code Rust uses the Agent SDK, usage should be treated as Agent SDK usage. Anthropic has paused the previously announced Agent SDK credit change. For now, Agent SDK usage, including claude -p and third-party apps like this one, still draws from normal Claude subscription limits.

Check Anthropic’s current support article before relying on billing assumptions:

• Use the Claude Agent SDK with your Claude plan

Installation

User Prerequisite

The Claude Code CLI must be installed as fallback for some SDK-unsupported features. See anthropics/claude-code for how to install it.

The recommended script install includes the application and its runtime dependencies. It does not require a Rust toolchain, Node.js, npm, or a separate Bun installation.

Install Script

Install scripts are available in GitHub Releases starting with v0.14.0 and are the recommended install path. They install a self-contained release without requiring npm, Node.js, or Bun on the user’s machine.

The scripts download a complete release archive from GitHub, verify the release archive integrity, install the native binary with the bundled private Bun runtime, Agent SDK bridge, and production node_modules, then run a quiet claude-rs --version check. Strict runtime diagnostics are available with the opt-in verify flag.

Interactive terminals display live progress for longer installation steps. Redirected output and CI remain plain and log-friendly, and NO_COLOR disables colored status output.

macOS/Linux:

curl -fsSL https://raw.githubusercontent.com/srothgan/claude-code-rust/main/scripts/install/install.sh | sh

Windows PowerShell:

powershell -NoProfile -ExecutionPolicy Bypass -Command "irm 'https://raw.githubusercontent.com/srothgan/claude-code-rust/main/scripts/install/install.ps1' | iex"

The default Unix install layout is:

${XDG_DATA_HOME:-$HOME/.local/share}/claude-rs/
$HOME/.local/bin/claude-rs

The app directory contains claude-rs, claude-rs-bridge-bun, agent-sdk/, and node_modules/. The file in $HOME/.local/bin is a launcher script that executes the app binary.

The default Windows install layout is:

%LOCALAPPDATA%\Programs\claude-rs\

The Windows app directory is added to the user Path unless path modification is disabled.

Install From npm

npm remains supported for users who prefer package-manager ownership of the global command:

npm install -g claude-code-rust
claude-rs --version
claude-rs

The npm option requires Node.js 24 and npm to install and run its JavaScript launcher. The package owns the claude-rs command, selects the matching platform payload with npm optional dependencies, and includes the private Bun runtime used by the Agent SDK bridge. A Rust toolchain and separate Bun installation are not required. No install-time binary download or postinstall script is used.

Supported npm platforms are Linux x64/arm64 with glibc, Windows x64/arm64, and macOS x64/arm64.

Pinning a Release

Use CLAUDE_RS_RELEASE to install a specific release:

curl -fsSL https://raw.githubusercontent.com/srothgan/claude-code-rust/main/scripts/install/install.sh | CLAUDE_RS_RELEASE=v0.14.0 sh

$env:CLAUDE_RS_RELEASE = "v0.14.0"
powershell -NoProfile -ExecutionPolicy Bypass -Command "irm 'https://raw.githubusercontent.com/srothgan/claude-code-rust/main/scripts/install/install.ps1' | iex"

The version can include or omit the v prefix.

Reinstalling the Same Version

Before downloading release checksums or an archive, the installer compares the selected release with the version recorded in an existing script-owned install at the configured install directory. It does not compare with an npm install or another claude-rs found on PATH, because those may represent a different installation method or location.

When the selected version is already installed, an interactive installation asks whether to reinstall it and defaults to no. Declining is a successful no-op and leaves the existing files unchanged. In CI or another non-interactive environment, the same-version check also exits successfully without reinstalling.

Use --yes or -Yes to approve an intentional same-version reinstall, for example to repair an installation:

curl -fsSL https://raw.githubusercontent.com/srothgan/claude-code-rust/main/scripts/install/install.sh | sh -s -- --release v0.14.0 --yes

.\install.ps1 -Release v0.14.0 -Yes

Update mode always treats an already-installed selected version as a successful no-op, even though update mode otherwise runs non-interactively. With the default latest selection, the installer must first request GitHub Release metadata to resolve the release tag; the same-version guard still runs before downloading SHA256SUMS or the release archive.

Custom Install Locations

On macOS/Linux, pass installer flags after sh -s --:

curl -fsSL https://raw.githubusercontent.com/srothgan/claude-code-rust/main/scripts/install/install.sh | sh -s -- --install-dir "$HOME/.local/share/claude-rs" --bin-dir "$HOME/.local/bin"

For non-interactive Unix installs:

curl -fsSL https://raw.githubusercontent.com/srothgan/claude-code-rust/main/scripts/install/install.sh | sh -s -- --yes

The Unix installer also accepts:

• --release <version>
• --install-dir <dir>
• --bin-dir <dir>
• --yes or -y
• --non-interactive
• --no-modify-path
• --verify
• --run
• --remove-npm
• --keep-npm
• --uninstall
• --update

When using the PowerShell one-liner, configure the installer with environment variables because arguments cannot be passed through iex:

$env:CLAUDE_RS_INSTALL_DIR = "$env:LOCALAPPDATA\Programs\claude-rs"
$env:CLAUDE_RS_NO_MODIFY_PATH = "1"
powershell -NoProfile -ExecutionPolicy Bypass -Command "irm 'https://raw.githubusercontent.com/srothgan/claude-code-rust/main/scripts/install/install.ps1' | iex"

If you download the script first, PowerShell flags are also available:

.\install.ps1 -Release v0.14.0 -InstallDir "$env:LOCALAPPDATA\Programs\claude-rs" -NoModifyPath

Other PowerShell flags available when the script is downloaded first:

• -Yes
• -Verify
• -Run
• -RemoveNpm
• -KeepNpm
• -Uninstall
• -Update

With the PowerShell one-liner, use the matching environment variables:

• CLAUDE_RS_VERIFY=1
• CLAUDE_RS_RUN=1
• CLAUDE_RS_REMOVE_NPM=1
• CLAUDE_RS_KEEP_NPM=1
• CLAUDE_RS_UNINSTALL=1

After a successful install, an interactive run asks whether to start claude-rs immediately. This runs the installed binary directly, so it works even before a new shell picks up PATH changes. Use --run, -Run, or CLAUDE_RS_RUN=1 to start it automatically after install.

When the startup update screen offers Install update, it detects whether the running executable is owned by a script or npm install and uses the same method. Script updates replace the existing app directory while preserving its launcher and PATH configuration. If the executable is not in a recognized install layout, the screen offers separate script and npm choices instead of guessing from PATH order.

Supported Script Platforms

Install archives are published for Linux x64/arm64 with glibc, Windows x64/arm64, and macOS x64/arm64.

Linux musl distributions are not supported by the install archives yet. Use npm if your platform has a matching package, or build from source.

The scripts do not require user-installed Node.js or Bun. If npm is available and a global claude-code-rust install is present, the installer reports it and can remove it after explicit confirmation so the script install owns claude-rs on PATH. If the selected release does not contain install archives, the installer exits with:

install script is currently not available for this release

Switching Install Methods

claude-rs is resolved by normal PATH order. npm and script installs use different app layouts, and one method does not automatically own files created by the other. If both are installed, whichever claude-rs appears first on PATH runs.

To see every visible claude-rs on macOS/Linux:

command -v claude-rs
which -a claude-rs

To see every visible claude-rs on Windows:

Get-Command claude-rs -All

To switch from npm to the install script, either let the installer prompt you or pass the explicit removal flag:

curl -fsSL https://raw.githubusercontent.com/srothgan/claude-code-rust/main/scripts/install/install.sh | sh -s -- --remove-npm

$env:CLAUDE_RS_REMOVE_NPM = "1"
powershell -NoProfile -ExecutionPolicy Bypass -Command "irm 'https://raw.githubusercontent.com/srothgan/claude-code-rust/main/scripts/install/install.ps1' | iex"
Remove-Item Env:\CLAUDE_RS_REMOVE_NPM

To switch from the install script back to npm, uninstall the script layout first, then install from npm:

npm install -g claude-code-rust

The installers do not silently remove the other install method because that would delete files outside their ownership and can be surprising in managed environments. For non-interactive installs, use --remove-npm / CLAUDE_RS_REMOVE_NPM=1 when you want the script installer to remove the npm install, or --keep-npm / CLAUDE_RS_KEEP_NPM=1 when you want it kept without prompting.

If the wrong claude-rs runs after switching methods, see Troubleshooting.

Uninstall

Remove a script install on macOS/Linux with --uninstall:

curl -fsSL https://raw.githubusercontent.com/srothgan/claude-code-rust/main/scripts/install/install.sh | sh -s -- --uninstall

On Windows, PowerShell supports -Uninstall when the script is downloaded first:

.\install.ps1 -Uninstall

With the PowerShell one-liner, arguments cannot be passed through iex, so use CLAUDE_RS_UNINSTALL:

$env:CLAUDE_RS_UNINSTALL = "1"
powershell -NoProfile -ExecutionPolicy Bypass -Command "irm 'https://raw.githubusercontent.com/srothgan/claude-code-rust/main/scripts/install/install.ps1' | iex"
Remove-Item Env:\CLAUDE_RS_UNINSTALL

The script uninstall path removes the script install directory, removes the Unix launcher when it points at that directory, and removes installer-managed PATH entries where supported. It refuses to delete an app directory that does not look like a claude-code-rust script install.

An npm install is owned by npm and is removed with npm:

npm uninstall -g claude-code-rust

Reporting Install Problems

Include:

• install method
• OS and architecture
• terminal
• npm --version, for npm installs
• npm config get omit, for npm installs
• claude-rs --version
• claude-rs doctor --json
• the command you ran
• the exact error output

Usage

Start a new session in the current directory:

claude-rs

Start in a specific working directory:

claude-rs -C path/to/project

Resume a previous session:

claude-rs resume

Resume by session id:

claude-rs resume <session_id>

The app prints a resume hint on clean exit when the active session has an id.

Support And Diagnostics

Use support commands when you need a repeatable snapshot of the local environment or diagnostic logs.

See Diagnostics for full options, logging presets, bundle contents, and sharing guidance.

CLI Options

The installed claude-rs --help command exposes these options:

See Diagnostics before enabling verbose logs or perf telemetry.

Core UI

The main screen is a terminal-owned chat view. The app renders messages, tool calls, diffs, permissions, questions, autocomplete, and status directly through Crossterm and Ratatui.

Common surfaces:

• Chat input for prompts and multiline text.
• File, slash-command, and subagent autocomplete.
• Inline permission prompts for tool decisions.
• Inline questions for agent-requested choices or text.
• Fullscreen settings, status, usage, MCP, plugins, and help tabs.
• Session picker when running claude-rs resume without a session id.

Use /help for the fullscreen help tab, /config for settings, and /docs <topic> for live in-chat help generated from the running app state.

More Usage Topics

• Slash Commands
• Keyboard Shortcuts
• Settings
• Diagnostics
• Help

Slash Commands

Claude Code Rust has app-owned slash commands and can also show slash commands advertised by the active Agent SDK session. App-owned commands are available from the Rust TUI itself; SDK-advertised commands depend on the current session and what the bridge reports.

Use /docs commands in the app to render the live merged command list into chat. That is the source to use when you want to know exactly which app-owned and SDK-advertised commands are available in the current session.

App-Owned Commands

SDK-Advertised Commands

The active SDK session can advertise additional slash commands. These are not documented as a fixed table here because they can change with SDK behavior, session capabilities, account state, and future upstream changes.

Use:

/docs commands

to inspect the current session’s full command list. The output includes app-owned commands and SDK-advertised commands, with descriptions when the SDK provides them.

Project-Local Commands

/1m-context and /opus-version persist folder-local settings under ./.claude/settings.local.json. The current session is not restarted automatically, so run /new-session after changing either setting.

/1m-context disable writes the environment setting used to disable the 1M context window for future sessions in that folder. enable clears that override.

/opus-version <version> pins the folder-local Opus alias. default clears the pin.

Keyboard Shortcuts

Keyboard shortcuts are context-sensitive. Use /docs shortcuts in the app to show the live shortcuts for the current state.

Global

When the app is blocked before a usable session is available, Ctrl+C quits.

Chat Input

Readline-style bindings are also supported:

Undo And Redo

On Unix except macOS, Ctrl+Z is reserved for process suspend.

Autocomplete

Inline Permissions

Letter shortcuts such as Ctrl+A, Ctrl+Y, or Ctrl+N are not permission shortcuts.

Inline Questions

Settings

Claude Code Rust has a fullscreen settings surface with multiple tabs. These slash commands open that surface directly:

The settings surface is session-aware. Some tabs need an active bridge session before they can show live SDK-backed state.

Usage

Open the settings surface with any command in the table above. Each command opens the same fullscreen surface but targets a different starting tab.

The tab order is:

Settings -> Plugins -> Status -> Usage -> MCP -> Help

Use Tab to move to the next tab and Shift+Tab to move to the previous tab. The active tab can also have its own navigation and action keys. For example, the Settings tab edits persisted settings, the Plugins tab navigates plugin lists and overlays, the MCP tab opens server actions and authorization flows, and the Usage and Status tabs refresh live session-backed data.

The surface is not only for editing JSON settings. It is the shared fullscreen control area for settings, plugins, MCP, account/session status, usage, and in-app help.

Help

Use /help when you want fullscreen help inside the same tabbed surface. The Help tab has three sections:

Use Left and Right inside the Help tab to switch sections. Use Up and Down to move through rows in the active section.

The Help tab is live UI, not a static manual page. Its Shortcuts section changes with focus and state, and its Commands and Subagents sections depend on what the active SDK session advertises.

Settings Files

Settings are loaded from Claude-compatible JSON files. The app can edit supported settings and display unsupported settings that exist for compatibility or future work.

Malformed JSON files are backed up with a timestamped .bak extension and replaced in memory with an empty object so the app can keep running.

For read-only support workflows, use:

claude-rs config
claude-rs config show
claude-rs config export --output claude-rs-config.json

These commands inspect and export redacted config data without starting the TUI and without rewriting or backing up malformed files.

Supported Settings

Currently Unsupported Settings

These settings are represented in the settings UI but are not currently supported by the app runtime:

MCP

The MCP tab shows live session-backed MCP state. Use /mcp to inspect servers, refresh status, complete authorization, reconnect servers, and handle SDK-provided MCP prompts when available.

If no session is active, the tab asks you to open or resume a session first. If the active session reports no MCP servers, the tab shows an empty state rather than editing raw config files.

Plugins

The Plugins tab is available through /plugins. It shows installed plugins, marketplace plugins, and configured marketplaces.

Supported actions include enabling, disabling, updating, uninstalling, and installing plugins into user, project, or local scopes when those actions are available for the selected plugin.

After plugin changes, the app requests a session runtime plugin reload when an active session is available.

Project-Local Overrides

Two slash commands write project-local environment overrides into ./.claude/settings.local.json:

/1m-context <enable|disable|status>
/opus-version <4.5|4.6|4.7|4.8|default|status>

These settings apply to future sessions. Run /new-session after changing them.

Diagnostics

Diagnostics are off by default. Enable them only when debugging or preparing a useful issue report because verbose logs can grow quickly.

Doctor

Run deterministic environment diagnostics:

claude-rs doctor

For machine-readable output:

claude-rs doctor --json

For CI or support scripts that should fail on hard runtime prerequisites:

claude-rs doctor --strict

Use -C, --dir with doctor to inspect project-local settings for a specific folder:

claude-rs -C path/to/project doctor

Config Inspection

Inspect resolved config paths without starting the TUI:

claude-rs config
claude-rs config path

claude-rs config prints the same path summary as config path, including user settings, project-local settings, user preferences, and whether each file is present and valid. Use -C, --dir to inspect project-local config for a specific folder.

For script-friendly path output:

claude-rs config path --which settings
claude-rs config path --which local-settings
claude-rs config path --which preferences

Show a concise redacted config summary:

claude-rs config show
claude-rs config show --json

Export a support-safe config snapshot:

claude-rs config export --output claude-rs-config.json

Config output redacts obvious credentials by default. Export refuses to overwrite existing files, and inspection does not repair, back up, normalize, or rewrite config files. Malformed existing config files are reported as invalid and cause show or export to return a non-zero exit code.

Logging

Enable runtime diagnostics with a named preset:

claude-rs --enable-logs --diagnostics-preset session
claude-rs --enable-logs --diagnostics-preset render

Available presets:

Use an explicit log path when you want the file somewhere predictable:

claude-rs --enable-logs --diagnostics-preset bridge --log-file claude-rs.log

Use an explicit tracing filter for targeted debugging:

claude-rs --log-filter "info,app.render=trace,bridge.protocol=debug"

--log-filter overrides --diagnostics-preset. If --log-file is omitted but logging is enabled through --enable-logs, --diagnostics-preset, --log-filter, or RUST_LOG, the app writes to a timestamped default diagnostics file.

The default diagnostics directory is under the platform local data directory:

• Windows: %LOCALAPPDATA%\claude-code-rust\logs\runtime\
• Linux: usually $XDG_DATA_HOME/claude-code-rust/logs/runtime/ or ~/.local/share/claude-code-rust/logs/runtime/
• macOS: the platform data directory reported by the dirs crate, under claude-code-rust/logs/runtime/

Default runtime log files include the UTC start timestamp, process id, and a short run id, for example:

claude-rs-20260614T075924Z-p12345-r8f3a2c1.log

Logs rotate at 10 MB and keep up to five rotated files per run. Default runtime logs are retained up to 256 MB or 30 days, while always preserving at least 10 newest files. Retention only applies to app-managed timestamped files in the default runtime log directory; explicit --log-file paths are never cleaned up by the app.

--log-append appends to an explicit --log-file. When used without --log-file, it appends to the legacy shared default file claude-rs.log for compatibility; prefer the normal timestamped defaults for new diagnostics.

Finding Logs

Use the logs command to find diagnostics paths without starting the TUI:

claude-rs logs
claude-rs logs --path
claude-rs logs --latest

claude-rs logs prints the runtime log directory, legacy log path, perf log directory, latest discovered log, and common follow-up commands. --path prints only the default runtime log directory for scripts. --latest prints only the latest runtime log path, falling back to the legacy shared log when no timestamped runtime log exists.

To inspect recent log output safely:

claude-rs logs --tail 200

Tail output is redacted for obvious credentials such as API keys, bearer tokens, OAuth tokens, passwords, and authorization headers before it is printed.

Debug Bundles

Create a redacted support bundle with:

claude-rs logs --bundle --yes

Without --yes, an interactive terminal is prompted before the bundle is written. Use --output <PATH> to choose the ZIP path.

The bundle includes:

• manifest.json
• doctor.json, equivalent to claude-rs doctor --json
• selected recent runtime logs
• the legacy log if present
• bridge diagnostics extracted from structured log records
• last-crash.json when the previous run crashed
• diagnostics paths

The bundle excludes full config files, Claude credentials, environment dumps, and arbitrary project files. Redaction removes obvious credentials, but logs can still contain private conversation text, local file paths, command output, or project-specific context. Review a bundle before sharing it publicly.

Failure Reports

Top-level failures print a short issue-friendly report to stderr with a category, exit code, version, platform, latest discovered log path, and one next-step command. Bridge failures are categorized as spawn, initialization, stdout close, SDK/protocol failure, or timeout so support output points at the likely failing boundary.

Unexpected Rust panics install a local panic hook. The hook writes a redacted last-crash.json file in the diagnostics root and prints the same safe-to-paste metadata to stderr. No crash report is uploaded automatically.

Bridge Diagnostics

When runtime logging is active, bridge diagnostics are enabled and bridge stderr is captured into the structured log. This is useful for Agent SDK startup, authentication, MCP, permission, and protocol issues.

The bridge script can be overridden with:

claude-rs --bridge-script /path/to/agent-sdk/dist/bridge.js

or:

CLAUDE_RS_AGENT_BRIDGE=/path/to/agent-sdk/dist/bridge.js

Debug builds can override the bridge runtime with:

CLAUDE_RS_AGENT_BRIDGE_RUNTIME=/path/to/bun

Release npm installs use the root package launcher to start the native platform binary and point it at the bundled bridge script. The native binary resolves the private claude-rs-bridge-bun executable from the installed platform package. In doctor --json, the runtime checks are reported as bridge_runtime, bridge_runtime_version, and bridge_script.

Perf Telemetry

Perf telemetry is a separate JSON-lines sidecar intended for high-frequency render and layout samples. It requires a binary built with the perf feature.

From source:

cargo run --features perf -- --enable-perf
cargo run --features perf -- --perf-log claude-rs-perf.log

For an already-built perf-enabled binary:

claude-rs --enable-perf
claude-rs --perf-log claude-rs-perf.log

If the binary was not built with --features perf, perf flags are rejected at startup.

When --perf-log is omitted, default perf telemetry uses timestamped JSON-lines files under the sibling logs/perf/ directory.

Useful Issue Reports

Include:

• claude-rs --version
• OS and terminal.
• Install method: npm package, source build, fork build, or manual binary.
• The exact command used to launch the app.
• Whether a custom bridge script or debug bridge runtime override was used.
• A short reproduction.
• A claude-rs logs --bundle --yes bundle or relevant redacted log snippets, not full secrets or private conversation content.

Troubleshooting

Start with claude-rs doctor. It runs installation, runtime, config path, log path, npm metadata, and credential checks, and it names the failing boundary for most of the problems below.

claude-rs doctor
claude-rs doctor --json

When you need the underlying detail, enable diagnostics and read the log. See Diagnostics for presets, log locations, and debug bundles.

claude-rs logs
claude-rs logs --tail 200

The App Will Not Start Or The Bridge Will Not Spawn

The TUI depends on the Agent SDK bridge, which runs as a child process under a private Bun runtime. If the bridge cannot start, the app reports the failing boundary as spawn, initialization, stdout close, SDK or protocol failure, or timeout.

Check what the app actually resolved:

claude-rs doctor --json

The bridge_runtime, bridge_runtime_version, and bridge_script checks show which runtime and bridge script the binary picked. A missing or unexpected path there is the usual cause: a source build without the bridge built, a partially extracted install, or a stale CLAUDE_RS_AGENT_BRIDGE override left in the environment.

For a source build, the bridge has to be built before the app can spawn it. See Development.

To capture the bridge’s own startup output, run with bridge logging enabled and inspect the log:

claude-rs --enable-logs --diagnostics-preset bridge
claude-rs logs --latest

Login And Authentication Failures

Authentication is owned by the Claude Code CLI, not by this project. claude-rs reuses the credentials the CLI already holds.

Sign in from inside the app with /login, or from a shell:

claude auth login

If login appears to succeed but sessions still fail, confirm that the CLI itself works, then re-check the credential state:

claude-rs doctor

Billing, model availability, and service limits are controlled by Anthropic and surface here as session errors rather than install problems. For the authentication and permission flow in the log, use the session preset:

claude-rs --enable-logs --diagnostics-preset session

The Wrong claude-rs Runs

The script install and the npm install use different layouts, and neither owns the other’s files. If both are present, PATH order decides which one runs, so an update can appear to do nothing.

List every claude-rs that is visible on macOS/Linux:

command -v claude-rs
which -a claude-rs

On Windows:

Get-Command claude-rs -All

Compare the resolved path with the install layout reported by:

claude-rs --version
claude-rs doctor

If the wrong one wins, remove the install you do not want, or reorder PATH so the one you want comes first. See Switching Install Methods and Uninstall.

Troubleshooting npm Installs

If npm omitted optional dependencies, the launcher cannot find the native platform package. Check your npm config and reinstall:

npm config get omit
npm install -g claude-code-rust

If the resolver reports a missing platform package, npm optional dependencies were likely omitted. Check npm config get omit and reinstall without --omit=optional.

Linux npm packages currently require glibc. On musl-based distributions, build from source until a matching npm package is available.

If claude-rs resolves to an older global shim, ensure your npm global bin directory comes first on PATH or remove the stale shim before retrying.

Reporting A Problem

For install failures, see Reporting Install Problems. For anything else, see Useful Issue Reports and attach a redacted bundle:

claude-rs logs --bundle --yes

Help

Claude Code Rust has two built-in help paths:

/help
/docs <topic>

/help opens the fullscreen Help tab. Use it when you want navigable in-app help without adding a message to the chat transcript.

/docs renders live help into the chat. Use it when you want the current commands, shortcuts, modes, models, or subagents copied into the conversation as reference material.

Fullscreen Help

The fullscreen Help tab has three sections:

Use Left and Right to switch Help sections. Use Up and Down to move through the visible rows in the active section.

The Shortcuts section is state-sensitive. It changes depending on whether focus is in chat input, autocomplete, an inline permission prompt, an inline question, or a blocked state such as connecting or command-pending.

The Commands and Subagents sections are also session-sensitive. While the app is connecting, they show loading rows. If the active session does not advertise SDK commands or subagents, the Help tab shows an empty-state row instead of inventing unavailable entries.

In-Chat Docs

/docs covers two topics that are not sections in the fullscreen Help tab: mode and models. Those topics are based on the active session’s advertised modes and models.

The /docs output is based on the running app state. It can differ from this manual when the active session advertises different models, modes, commands, or agents.

Development

This page covers building and running Claude Code Rust from source. For CI checks, coding standards, and how to open a pull request, see CONTRIBUTING.md.

Build From Source

Use this path when developing the project or testing a fork without installing a global claude-rs command:

Source development requires Rust 1.88.0 or newer, Node.js 24 with npm, and Bun. These are developer toolchain requirements, not requirements for script-installed users.

git clone https://github.com/srothgan/claude-code-rust.git
cd claude-code-rust
npm ci --prefix agent-sdk
npm run build --prefix agent-sdk
cargo run

Maintainer and source-build npm tooling targets Node.js 24. Packaged installs use the bundled private Bun runtime for the Agent SDK bridge.

Debug builds resolve agent-sdk/dist/bridge.js from the checkout after the bridge is built. They use bun from PATH unless CLAUDE_RS_AGENT_BRIDGE_RUNTIME points at a specific Bun executable.

For a release-mode source binary, build the bridge and binary, then provide both an explicit bridge script and a Bun runtime using the bundled-runtime filename. Release-mode source binaries do not use the debug PATH fallback for Bun.

npm ci --prefix agent-sdk
npm run build --prefix agent-sdk
cargo build --release --locked --bin claude-rs
cp "$(command -v bun)" ./target/release/claude-rs-bridge-bun
./target/release/claude-rs --bridge-script ./agent-sdk/dist/bridge.js

On Windows, copy bun.exe next to the binary as claude-rs-bridge-bun.exe, then run:

Copy-Item (Get-Command bun).Source .\target\release\claude-rs-bridge-bun.exe
.\target\release\claude-rs.exe --bridge-script .\agent-sdk\dist\bridge.js

Do not use cargo install --path . if you want to test the npm install shape. cargo install writes only the Rust binary to Cargo’s bin directory and does not install the bundled Agent SDK bridge, private Bun runtime, or platform package layout.

Manual Bridge Overrides

If you need to run a manually built binary outside the npm package layout, pass the bridge explicitly:

claude-rs --bridge-script /path/to/claude-code-rust/agent-sdk/dist/bridge.js

You can also set:

CLAUDE_RS_AGENT_BRIDGE=/path/to/agent-sdk/dist/bridge.js

Debug builds can use a local runtime override while developing the bridge:

CLAUDE_RS_AGENT_BRIDGE_RUNTIME=/path/to/bun

Release npm installs ignore runtime overrides and use the bundled claude-rs-bridge-bun executable from the platform package.

Architecture

Claude Code Rust is split into a native Rust terminal app and a TypeScript Agent SDK bridge.

Runtime Shape

The Rust binary owns the terminal UI and process lifecycle. It parses CLI options with Clap, starts a Tokio runtime, and runs the app inside a LocalSet because parts of the terminal and child-process runtime are not Send.

The app then starts or resumes a bridge session and renders the chat view directly in the terminal.

Rust Terminal App

Important Rust areas:

The current runtime uses inline terminal-owned rendering rather than an older fullscreen-only model. Fullscreen views are still used for config, help, status, usage, MCP, and plugin surfaces.

Agent SDK Bridge

In packaged npm installs, the Rust process resolves a private Bun runtime named claude-rs-bridge-bun or claude-rs-bridge-bun.exe from the installed package layout. That runtime runs:

agent-sdk/dist/bridge.js

The TypeScript bridge wraps @anthropic-ai/claude-agent-sdk. Rust and TypeScript communicate over stdin/stdout using newline-delimited JSON command and event envelopes.

Rust sends commands such as session creation, session resume, prompt submission, permission responses, MCP actions, and runtime refresh requests. The bridge sends events such as assistant messages, tool updates, permission requests, question requests, available commands, modes, models, usage, and errors.

Packaging

The npm install is split across a root command package and platform payload packages.

The root package is claude-code-rust. It exposes the claude-rs command through the npm launcher and includes the built Agent SDK bridge under:

bin/claude-rs.js
agent-sdk/dist/bridge.js

The platform packages are selected through root package optional dependencies. They include the native Rust binary and private Bun runtime. The exact package mapping lives in scripts/shared/npm-package-config.mjs; supported npm payloads currently cover Linux x64/arm64 glibc, Windows x64/arm64, and macOS x64/arm64.

At runtime, npm’s generated shim starts bin/claude-rs.js. The launcher selects the matching platform package, sets CLAUDE_RS_AGENT_BRIDGE to the root package bridge script, and spawns the native binary. The native binary resolves the bundled Bun runtime from the platform package bin/ directory. No npm postinstall script, install-time binary download, or global Bun is required.

Release Model

Release packaging is designed around immutable artifacts:

• Native binaries are built on GitHub-hosted runners for Linux x64 glibc, Linux arm64 glibc, Windows x64, Windows arm64, macOS x64, and macOS arm64.
• Private Bun runtime files are staged into each platform package as third-party runtime artifacts.
• Generated npm package directories are verified against allowlisted package contents before packing.
• Packed npm tarballs are smoke-tested before publication.
• GitHub Releases include native binaries, npm tarballs, package-content manifests, build metadata, and SHA256SUMS.
• The release workflow generates and verifies build provenance attestations for native binaries before npm publication.
• npm publication uses Trusted Publishing rather than a long-lived npm token.
• The root package remains the user-facing npm install package and depends optionally on platform payload packages.

Source builds are different: cargo build or cargo install --path . produce only the Rust binary. They do not build or install the JavaScript bridge or private Bun runtime. Build the bridge with Node.js 24/npm and provide it through the checkout fallback, --bridge-script, or CLAUDE_RS_AGENT_BRIDGE. Debug builds can use CLAUDE_RS_AGENT_BRIDGE_RUNTIME to point at a local Bun runtime; release npm installs use only the bundled runtime. See Development for the exact steps.

Boundaries

Claude Code Rust owns the terminal UI, local settings surface, bridge process management, and event rendering. Anthropic owns the Agent SDK, authentication, service behavior, billing, models, and upstream Claude Code semantics.

The project does not depend on Agent SDK package subpath exports such as /browser, /bridge, or /assistant as the runtime path. The runtime path is the local TypeScript bridge in this repository.

Governance

This page records repository governance rules for maintainers and contributors. It describes who stewards the project, how conduct concerns are reported, how the repository is protected, how release authority is gated, and which GitHub settings are expected to remain in place.

Project Stewardship

The project is maintained by Simon Rothgang, who is currently the only maintainer and the only Community Moderator.

Repository rules, workflow permissions, release publication, and code of conduct enforcement are all owned by that single role. The project does not have an independent escalation contact today. If a concern involves the maintainer directly, there is no separate internal channel to route it to, and this page does not pretend otherwise.

Community Conduct and Reporting

The Code of Conduct is the policy and the source of truth for what is expected, what is restricted, and how violations are addressed. This section only describes how to reach the maintainer privately.

Conduct concerns must not be reported through public GitHub issues, GitHub Discussions, or GitHub Security Advisories. Those channels are public or reserved for security vulnerabilities, and none of them are an appropriate place for a report involving a person.

Report a concern by email to the Community Moderator, Simon Rothgang:

• Send a Code of Conduct Report
• If no email client is configured, write to simonrothgang@icloud.com with the subject Code of Conduct Report.

Include whatever you can of the following. Only what is needed to understand and respond to the report is expected:

• what happened
• where and when it happened
• relevant links, messages, or screenshots
• who was involved
• any immediate safety or confidentiality needs

Reports are handled privately by the Community Moderator. This page does not promise absolute confidentiality or a fixed response time; the enforcement process and the possible outcomes are described in the Code of Conduct.

Repository Safeguards

Branch Protection

The main branch is protected by an active GitHub repository ruleset rather than classic branch protection.

The ruleset requires pull requests before merging to main and requires these status checks to pass:

• pr-gate
• Lint PR title

Pull request reviews are required. Review conversations must be resolved before merge, and new reviewable commits dismiss previous approvals.

GitHub Actions Permissions

Repository default GITHUB_TOKEN permissions are expected to be read-only. Workflows should request broader permissions only where a job needs them.

Examples of intentionally elevated job permissions include:

• provenance attestations for release artifacts
• OIDC tokens for npm Trusted Publishing and GitHub Pages deployment
• GitHub Release creation and publication
• issue creation or update from scheduled dependency monitoring

Do not rely on repository-wide write permissions for normal CI behavior.

Release Authority

Release workflow changes are maintainer-owned because they can affect package contents, provenance, publication, and user installation paths.

The npm-release environment gates publication jobs. It requires reviewer approval before npm publication or GitHub Release publication can proceed.

npm publication must use Trusted Publishing. The release process must not use a checked-in npm token or a long-lived NPM_TOKEN.

Governance Changes

Changes to repository rules, deployment environments, workflow permissions, npm Trusted Publishing configuration, or release publication behavior require explicit maintainer review.

When changing governance-sensitive files or settings, summarize the impact in the pull request and include verification of the relevant GitHub setting after the change is applied.

Changelog

All notable changes to this project will be documented in this file.

[Unreleased]

[0.14.1] - 2026-07-18 Changes

Documentation

• Manual restructure (#282, @srothgan): Split installation into end-user install, development, and troubleshooting pages, document /agent, restore the conduct report contact in the issue chooser, and add tests keeping the slash command and CLI tables in sync with the code.

Release and Packaging

• Installer progress and idempotency (#281, @srothgan): Add inline installer progress across PowerShell, macOS, and Linux while keeping CI output plain, and make same-version reinstalls a prompted opt-in with --yes/-Yes approval.

CI and Dependencies

• Claude Agent SDK update (#285, @srothgan): Bump the bundled bridge to Agent SDK 0.3.214, preserve subagent model routes, retry and Bash timeout state, keep Grep and Artifact output accurate, and disable new review-dependent tools until the TUI can present them safely.

[0.14.0] - 2026-07-12 Changes

Features

• In-chat usage limits (#270, @srothgan): Add /limits to print recent 5-hour, 7-day, and extra-credit usage into the chat from the existing usage snapshot/refresh pipeline, including a loading message for stale data and a concise refresh failure message while keeping /usage as the fullscreen Usage tab.
• Native textarea cursor (#268, @srothgan): Use tui-textarea-2 native cursor positioning for the chat composer, hide the textarea-drawn cursor, and restore terminal cursor shape when leaving chat surfaces.
• Startup update screen (#264, @srothgan): Show available updates in a startup screen with install, skip, and release-notes actions.

Fixes

• Inline cursor tracking (#266, @srothgan): Avoid Unix/macOS live-loop DSR cursor reads in inline chat by using tracked cursor state for the ratatui viewport and invalidating cached seeds after external terminal ownership boundaries.
• Markdown list rendering (#263, @srothgan): Keep streamed inline Markdown handoffs mutable only until delimiters resolve, let stable scrollback advance after resolved blocks, and preserve fenced code layout when code lines look like Markdown list items.

Documentation

• Governance and source install docs (#262, @srothgan): Document repository release controls and clarify source-build auth/runtime setup.
• Private conduct reporting (@srothgan): Add a dedicated private contact for code of conduct reports and keep security advisories focused on vulnerability disclosure.

Maintenance

• Repository health cleanup (#262, @srothgan): Consolidate duplicated UI rendering helpers, add Rust SPDX headers, and remove stale TODO/header noise.

Release and Packaging

• Install scripts (#259, #267, @srothgan): Add macOS/Linux and Windows install scripts that install from GitHub Releases without requiring npm, Node.js, or Bun on the user’s machine, and preserve the detected install method for in-app updates.
• Release script phases (#260, @srothgan): Reorganize release tooling scripts into phase directories, add shared repository-root resolution, and expand PR validation for install archives and public installers.
• Windows npm mock smoke (#262, @srothgan): Make local Windows mock package smoke tests use spawnable binaries and isolated npm cache state.

CI and Dependencies

• Duplicate-code gate (#262, @srothgan): Add PR jscpd thresholds with a 1% warning, 2% failure, and pr-gate enforcement.
• Advisory and tooling updates (#262, @srothgan): Refresh dependency advisory/tooling locks and remove resolved cargo-deny advisory ignores.
• Claude Agent SDK update (#272, @srothgan): Bump the bundled bridge packages to Agent SDK 0.3.207, preserve new task metadata and terminal reason values, normalize the new permission-mode alias, and remove the unmatched mouse-capture restore action.
• Release skip on unchanged version (#269, @srothgan): Skip the release workflow with a green no-op when a Cargo.toml push leaves the crate version unchanged.

[0.13.4] - 2026-07-06 Changes

Features

• Bundled Bun bridge runtime (#245, @srothgan): Ship a private Bun runtime in each platform npm package so the Agent SDK bridge no longer needs a separately installed Node runtime to run.

CI and Dependencies

• Node 24 maintainer floor (#254, @srothgan): Raise root and Agent SDK npm engine metadata to Node 24 for source-build tooling.

[0.13.3] - 2026-07-04 Changes

Features

• ARM64 npm binaries (#243, @srothgan): Add Linux arm64 glibc and Windows arm64 MSVC platform packages to the npm release flow.

Fixes

• File mention completion (#242, @srothgan): Let Tab commit selected or literal @ file mentions with quoted paths and cleaner autocomplete boundaries.
• Release publication targeting (#238, #239, @srothgan): Verify reusable-workflow attestations and pin GitHub Release publishing to the target repository.

Release and Packaging

• Platform package READMEs (@srothgan): Generate concise platform-specific npm READMEs with version, install, target, and platform details.
• Dependency declarations (#240, @srothgan): Remove redundant direct npm dependencies while keeping runtime installs unchanged.

[0.13.2] - 2026-07-03 Changes

Features

• Supportability commands (#235, @srothgan): Add claude-rs doctor, logs, redacted debug bundles, crash and bridge failure reports, and read-only redacted config inspection/export commands for installation and runtime diagnostics.

Release and Packaging

• Platform npm packages (#232, @srothgan): Replace the install-time GitHub Release downloader with a root launcher plus platform-specific optional npm packages for macOS arm64/x64, Linux x64 glibc, and Windows x64 MSVC.
• Trusted Publishing release flow (#232, @srothgan): Publish platform packages before the root package from a protected npm-release environment, with package-content manifests, checksums, provenance, and binary attestations.
• Package validation (#232, @srothgan): Add generated package assembly, package layout verification, and tarball smoke tests so release candidates and npm releases validate the installed launcher and platform binary layout before publishing.
• Release publication guardrail (#233, #236, @srothgan): Create the GitHub Release as a draft, publish npm platform and root packages from explicit local tarball paths, then publish the GitHub Release only after npm publication succeeds.

Testing

• Bridge contract coverage (#234, @srothgan): Add Node-side NDJSON bridge contract tests and Rust-side bridge lifecycle failure coverage without requiring Claude credentials.
• Direct binary smoke checks (#234, #236, @srothgan): Validate release binary startup with --version and --help across supported platforms outside the npm package smoke path.

CI and Supply Chain

• Cargo Deny policy (#236, @srothgan): Add deny.toml and enforce Cargo dependency policy for advisories, licenses, duplicate-crate policy, and allowed sources.
• Workflow consolidation (#236, @srothgan): Replace the broad PR workflow set with pr-gate, separate PR title lint, reusable Agent SDK and release build workflows, scheduled deep checks, and dependency monitoring.
• Workflow action pinning (#236, @srothgan): Pin external GitHub Actions to full commit SHAs and align repository rules with the new required status checks.

Maintenance

• Focused app state modules (#231, @srothgan): Split app state, runtime session, startup, turn, transcript, and SDK inventory bookkeeping into focused modules while preserving public behavior.

Documentation

• Install architecture (#232, @srothgan): Document the optional-dependency install model, platform package troubleshooting, source-build bridge behavior, and release invariants for contributors.
• Diagnostics and security docs (#235, #236, @srothgan): Document supportability commands, redacted config exports, current repository security controls, and the paused Agent SDK billing change.

Notes

• 0.13.1 was skipped before npm publication after a failed release workflow. No 0.13.1 npm packages were published.

[0.13.0] - 2026-07-02 Changes

Features

• Fable 5 and Claude Agent SDK 0.3.198 migration (#229, @srothgan): Make Fable 5 the default model alias, preserve resolved model IDs from the SDK catalog, and refresh bridge metadata handling for current models, MCP request timeouts, and newer SDK status fields.
• Separate model and thinking effort config dialogs (#229, @srothgan): Split the combined /config model and effort picker into independent dialogs, keep effort choices filtered by the selected model, and explain the model-dependent effort behavior only in the effort dialog.
• Mention file autocomplete (#226, @srothgan): Move @ file matching off the UI path, support raw indexed file and folder mentions with spaces, preserve whole-mention replacement boundaries, and rank shallow project paths ahead of deep dependency matches unless the query explicitly targets the deep path.
• Atomic input placeholders (#227, @srothgan): Treat image badges and pasted-text placeholders as shared textarea atoms, keeping cursor movement, deletion, undo/redo, image attachment state, and paste expansion aligned through tui-textarea-2 0.12.0 atomic range support.
• Question and list rendering (#228, @srothgan): Render markdown lists with indentation instead of injected blank gaps, and show AskUserQuestion answers as structured results with selected options, descriptions, previews, and notes.

Documentation

• README banner (#217, @srothgan): Add a project screenshot banner to the README.

Fixes

• SDK metadata and MCP preservation (#229, @srothgan): Preserve MCP request_timeout_ms through status display, diagnostics, and dynamic server removal, and keep app-owned slash commands from being duplicated by SDK command snapshots.
• Inline chat resize transactions (#217, @srothgan): Treat terminal size as a draw-transaction snapshot, recover from mid-draw resizes with purge/replay, and clip stale inline viewport geometry before owned-region clears.
• Streaming markdown tables (#226, @srothgan): Preserve table rendering across streamed cache splits so partial assistant updates do not corrupt table layout.

Maintenance

• Dead test helper cleanup (#228, @srothgan): Remove stale test-only helpers that kept old production paths alive only through tests.
• Social discoverability (#219, @srothgan): Add Open Graph and Twitter Card meta tags with a social preview image to the docs site, and expand the npm package keywords to mirror the repo topics.

CI and Dependencies

• Workflow permission hardening (#229, @srothgan): Declare least-privilege GitHub Actions permissions for CI, audit, commit-lint, release dry-run, and Agent SDK workflows to resolve CodeQL code scanning alerts.
• Claude Agent SDK update (#229, @srothgan): Bump @anthropic-ai/claude-agent-sdk to 0.3.198 in the root package and bundled bridge package locks.
• CodeQL scanning (#228, @srothgan): Add a CodeQL workflow for repository code scanning.
• quinn-proto advisory fix (#220, @srothgan): Bump quinn-proto to 0.11.15 for RUSTSEC-2026-0185 (remote memory exhaustion from unbounded out-of-order stream reassembly).
• Security Audit workflow resilience (#220, @srothgan): Mark the cargo audit step continue-on-error so newly published advisories still report and file a tracking issue without failing the scheduled Security Audit run.
• Dependency updates (#221, #222, #224, #223): Bump uuid to 1.23.4, anyhow to 1.0.103, tui-markdown to 0.3.8, and knip to 6.23.0 in agent-sdk.

[0.12.4] - 2026-06-26 Changes

Features

• Claude Agent SDK 0.3.193 migration (#212, @srothgan): Refresh the bridge for the current SDK, add /rewind with conversation and code restore modes, render MCP resource directory listings, and surface new SDK system notices, rate-limit credit metadata, and SDK-created resume sessions.
• Deterministic Read syntax highlighting (#210, @srothgan): Preserve tool locations for Read output, add broader syntax coverage, and render a brighter dark-terminal theme with a dim line-number gutter.

Fixes

• Inline viewport bottom growth (#214, @srothgan): Scroll the terminal before autocomplete and composer expansion at the screen bottom so handed-off transcript rows are pushed up instead of overwritten.
• Runtime resize and notice hardening (#211, @srothgan): Prevent notice migration and terminal row-range panics, preserve resize replay repaint requests, and clamp inline geometry after terminal shrinks.

Maintenance

• Production module split (#215, @srothgan): Move inline module tests into sibling files and split keymap, agent model, app state, plugins, config, and MCP config code into focused child modules while preserving facade exports.

CI and Dependencies

• Dependabot and Agent SDK monitor cleanup (#201, #207, @srothgan): Add npm version updates for root and bridge packages, make the SDK monitor the single Agent SDK update path, bump the bridge TypeScript toolchain, and clear Hono advisories.
• Dependency updates (#196, #197, #198, #199, #200): Bump which to 8.0.4, ratatui to 0.30.2, time to 0.3.51, hono through 4.12.27, and rand to 0.8.6.
• Workflow action bump (#195): Bump actions/checkout to 7.

[0.12.3] - 2026-06-16 Changes

Documentation

• Agent SDK billing notice (@srothgan): Anthropic paused the Agent SDK credit change documented in (#165, @srothgan); SDK usage still draws from normal Claude subscription limits. Shrink the README warning to a compact note linking the support article.

Fixes

• Startup repaint and PowerShell rendering (#193, @srothgan): Smooth the startup repaint and fix PowerShell tool-call rendering.

CI and Dependencies

• SDK monitor and advisory checks (#186, #187, @srothgan): Add an Agent SDK update monitor and advisory quality checks.
• Rust dependency updates (#189, #190, #191, #192): Bump uuid to 1.23.3, time to 0.3.49, ignore to 0.4.26, and which to 8.0.3.
• Workflow action bump (#188): Bump actions/upload-artifact to 7.

[0.12.2] - 2026-06-14 Changes

Features

• Claude Agent SDK 0.3.177 migration (#180, #182, @srothgan): Refresh the bridge for new SDK metadata, task events, dialogs, retractions, retry errors, and MCP status.
• Opus 4.8 and effort controls (#180, @srothgan): Add /opus-version 4.8, /effort, xhigh, session-only max, and live /agent switching.
• MCP configuration management (#180, #182, @srothgan): Add scoped server removal and track dynamic, plugin-owned, persisted, and runtime-only servers.

UI

• Structured SDK tool rendering (#180, #182, @srothgan): Add readable renderers for new task, automation, workflow, MCP, search, project, artifact, and agent tool outputs.
• MCP tool-call display (#184, @srothgan): Show readable MCP titles with a dedicated icon while keeping raw tool names intact.
• Config dialog overlays (#180, @srothgan): Tighten fullscreen dialogs, confirmations, and small-screen overflow.

Fixes

• SDK compatibility hardening (#180, #182, @srothgan): Normalize retry errors, overage fields, unavailable models, mirror errors, resume task replay, and MCP snapshot refresh.
• Plugin and MCP scope accuracy (#180, #182, @srothgan): Filter plugin lists and stale MCP servers by the scopes that are actually active.

Diagnostics

• Timestamped runtime logs (#183, @srothgan): Write default diagnostics to per-run files under logs/runtime with bounded retention.

Documentation

• Commands and diagnostics manual updates (#180, #183, @srothgan): Document /effort, /opus-version 4.8, settings behavior, and diagnostics paths.

CI and Dependencies

• Agent SDK package refresh (#180, #182, @srothgan): Update the Agent SDK bridge packages and npm lockfiles.
• Rust dependency updates (#176, #177, #178, #179): Bump unicode-segmentation to 1.13.3, uuid to 1.23.2, reqwest to 0.13.4, and ratatui to 0.30.1.
• Pages workflow updates (#173, #174, #175): Bump actions/upload-pages-artifact to 5, actions/deploy-pages to 5, and actions/configure-pages to 6.

[0.12.1] - 2026-05-28 Changes

Documentation

• mdBook manual and GitHub Pages workflow (@srothgan): Add a repo-native manual and Pages deployment workflow.

Fixes

• CLI help examples (@srothgan): Remove the invalid installed-binary --features perf example.

[0.12.0] - 2026-05-21 Changes

Features

• Inline terminal chat runtime (#165, @srothgan): Replace the full-screen chat surface with inline terminal-owned rendering.
• Resolved action-based keymap (#166, @srothgan): Route shortcuts through semantic actions and generate help from the resolved keymap.
• macOS modifier key support (#159, @TomasWeisss): Support Command-key shortcuts in terminal modes.

Fixes

• Inline rendering stability (#165, @srothgan): Stabilize resume, resize, fullscreen return, slash notices, and active-turn state on the inline path.
• Tool-call and diff rendering (#152, #165, #166, @srothgan): Preserve diff indentation, show compact change counts, uncap plan markdown, and keep concrete tool output.
• Agent SDK bridge events (#165, @srothgan): Suppress ToolSearch events, protect the packaged bridge runtime, and accept fractional API retry delays.

UI

• Composer hints and Help tab (#165, #166, @srothgan): Move autocomplete into compact composer rows and Help into fullscreen config.
• Compact inline tools and todos (#165, @srothgan): Render todos inline and tighten standard tool body caps.

Documentation

• README billing and commands cleanup (#165, @srothgan): Document Agent SDK billing changes, custom slash commands, and remove the outdated Architecture section.

CI and Dependencies

• Agent SDK 0.3.146 refresh (#165, @srothgan): Update the Agent SDK bridge dependencies and package locks.
• Rust dependency updates (#151, #154, #155, #156, #157, #158, #160, #161, #162, #163, #164): Bump Rust dependencies and clarify the rand audit ignore.
• rustls-webpki advisory fix (#153): Bump rustls-webpki to 0.103.13 for RUSTSEC-2026-0104.

[0.11.3] - 2026-04-19 Changes

Fixes

• Plan approval Ctrl shortcuts (@srothgan): Replace plain y/n exit-plan approvals with Ctrl+y/Ctrl+n.

[0.11.2] - 2026-04-19 Changes

Features

• Project-local Opus version controls (#146, @srothgan): Add /opus-version to pin the Opus alias per project.

Fixes

• Model alias cleanup and Opus naming (#146, @srothgan): Replace Default with the explicit opus alias and normalize dated Opus labels.
• Dev versus installed bridge resolution (#146, @srothgan): Make cargo run use the repo bridge and installed builds use the bundled bridge.
• Tool-call diff rendering and scrollbar lane (#138, @srothgan): Reserve a dedicated scrollbar column and keep diff content out of it.
• Versioned short model names (#139, @srothgan): Show resolved model versions in short model names.
• Bridge script resolution precedence (#142, @srothgan): Prefer the bundled bridge script and keep repo-local fallback debug-only.
• Update notice warning message (#143, @srothgan): Move upgrade hints from the footer into a warning system message.
• Terminal ANSI output rendering (#144, @srothgan): Preserve command-emitted ANSI colors in terminal tool output.
• Draft-focused inline prompts (#145, @srothgan): Keep pending prompts from stealing draft focus and move prompt handoff to Tab.

CI and Dependencies

• Agent SDK 0.2.112 refresh (#141, @shyal): Bump @anthropic-ai/claude-agent-sdk to 0.2.112, update EXPECTED_AGENT_SDK_VERSION, and refresh 4.7 fixtures.

[0.11.1] - 2026-04-16 Changes

Features

• Folder-local 1M context controls (@srothgan): Add /1m-context enable|disable|status to persist CLAUDE_CODE_DISABLE_1M_CONTEXT in .claude/settings.local.json, preserve neighboring local env keys, surface status, and point 1M-context recovery guidance at the new folder-local fallback

[0.11.0] - 2026-04-16 Changes

Features

• Agent SDK 0.2.104 migration (#135, @srothgan): Upgrade the bundled Claude Agent SDK from 0.2.74 to 0.2.104 across the published package and local bridge; extend the Rust and TypeScript wire contract for current-model snapshots, runtime session state, API retry updates, settings parse errors, terminal reasons, task metadata, prompt suggestions, and refreshed tool metadata
• Live session capability synchronization (#135, @srothgan): Reconcile current model and permission-mode support against the active SDK session instead of assuming startup-time state, and keep session/runtime status aligned through connect, resume, and turn lifecycle changes
• Task patch updates and subagent grouping (#135, @srothgan): Propagate incremental task patches and parent tool linkage so subagent child tool calls collapse under their root task while still surfacing focused hidden permission prompts when user input is required
• Welcome session snapshot and rotating tips (#135, @srothgan): Replace the welcome model badge with a lightweight snapshot showing version, subscription, cwd, and session ID, and rotate curated startup tips across sessions
• Backgrounded tool state badges (#135, @srothgan): Surface assistant-backgrounded Bash commands and backgrounded task state directly in tool cards and summaries

Fixes

• Resume ordering and runtime stability (#135, @srothgan): Preserve resumed history turn ordering and tighten turn/session state handling so reconnects, tool updates, and completion events stay consistent
• External API provider auth handling (#135, @srothgan): Respect external API providers during auth validation instead of assuming the bundled Claude auth path
• Permission and tool-result rendering cleanup (#135, @srothgan): Normalize SDK permission display and tool-result metadata, hide redundant permission headers, and treat killed tool calls as terminal failures in transcript rendering
• Ctrl+V paste path split (#135, @srothgan): Make Ctrl+V exclusively trigger image paste while keeping normal text paste on the standard input path
• Collapsed in-progress subagent summaries (#135, @srothgan): Show substantially more context in collapsed in-progress subagent cards without expanding completed tool calls

Documentation

• Startup limitation note (#135, @srothgan): Document the current end-to-end startup latency constraint from the upstream Claude Agent SDK runtime in README.md

CI and Dependencies

• Bump @anthropic-ai/claude-agent-sdk from 0.2.74 to 0.2.104 in both the published package and bundled bridge (#135, @srothgan)
• Add dedicated agent-sdk CI for audit, lint, and knip, and gate audit failures on direct dependency advisories only (#135, @srothgan)
• Add @anthropic-ai/sdk 0.81.0, @biomejs/biome 2.4.12, and knip 6.4.1 to the bundled bridge toolchain (#135, @srothgan)

[0.10.0] - 2026-04-11 Changes

Features

• Clipboard image pasting (#104, @shyal): Paste images with Ctrl+V, send them as PNG image blocks, and render renumbered inline [Image #N] badges in the draft
• Live git branch tracking (#114, @srothgan): Replace git branch --show-current shell-outs with in-process HEAD parsing and a filesystem watcher so the footer updates while the app stays focused
• Terminal tab activity indicator (#115, @srothgan): Drive the OSC 2 tab title from app state with active and idle indicators and restore the plain cwd title on shutdown
• Resume subcommand and startup picker (#116, @srothgan): Replace the --resume flag with claude-rs resume, add a dedicated startup picker, and cap it to recent project sessions
• App-owned file index with live updates (#117, @srothgan): Move @ mention search to a shared file index with scan streaming, prewarm, and incremental watcher updates across cwd and gitignore changes

Fixes

• Inline turn-scoped limit notices (#118, @srothgan): Dedup rate-limit and plan-limit notices inside the active assistant turn instead of appending duplicate trailing system rows
• Rename watcher convergence (#120, @srothgan): Re-scan parent subtrees on file-index rename events, handle root-level renames, and refresh the yanked unicode-segmentation lockfile entry

Performance

• Structured logging and render-path optimization (#119, @srothgan): Standardize Rust and Agent SDK diagnostics, switch to JSON rolling logs, and cut chat hot-path cost with assembled render caching and cheaper spinner frames

Documentation

• Legal notice expansion (#113, @srothgan): Clarify the project’s relationship to Claude Code, the Agent SDK, Anthropic terms, and the recent source leak

CI and Dependencies

• Bump uuid from 1.22.0 to 1.23.0 (#106, @dependabot)
• Bump notify-rust from 4.12.0 to 4.13.1 (#109, @dependabot)
• Bump similar from 2.7.0 to 3.0.0 (#110, @dependabot)
• Bump tokio from 1.50.0 to 1.51.0 (#111, @dependabot)

Project

• Collaboration template cleanup (#121, @srothgan): Simplify PR and issue templates, collapse CODEOWNERS, and align CONTRIBUTING.md with the current workflow

[0.9.0] - 2026-03-26 Changes

Features

• Two-line footer replaces header (#102): Remove the header and consolidate location, branch, mode badges, permission counts, and MCP auth hints into a two-row adaptive footer

Fixes

• Unified viewport geometry handling (#101): Single geometry entry point with separate width/height semantics and tail invalidation on topology changes
• Centralized geometry state and wrapped panel measurement (#101): Immediate resize geometry refresh and wrapped-text measurement replacing fixed-height panel assumptions
• Topology invalidation and batch message dirtiness (#101): Tracked insert/remove/clear paths own tool index and terminal ref repair
• Active turn ownership across history pruning (#101): Keep active assistant turn out of retention drop candidates and remap ownership after pruning
• Scroll anchor preservation (#101): Delay anchor restore until heights are exact and preserve anchors across pruning and marker operations
• Unified message layout model (#101): Shared MessageLayout replaces split role-specific render/measure branches
• Turn cleanup normalization (#101): Single cleanup boundary for resume, cancel, auth-required, connection-failure, and fatal exits
• Chat focus ownership (#101): Rebuild focus from surviving state on transitions and render selected prompt choices in rust orange
• Streaming invalidation and selection snapshots (#101): Refresh selection snapshots on redraw and protect active streaming assistant in cache budgeting
• Session state reset at authority boundaries (#101): Scope async responses to the active session epoch and discard stale results
• Persisted authority reconciliation (#101): Rederive trust state from current cwd on reconnect and clear stale session identity on failure boundaries
• Tool index rebuilds and multi-index sync (#101): Gate scope updates on successful lookup and normalize interaction queues to prevent stale prompt drops
• Display-width-aware copy (#101): Slice copied text by display columns so emoji, CJK, and combining marks match visual selection
• Esc cancel and queued submit lifecycle (#101): Clear deferred submit on Esc and let manual cancel override auto-resubmit

Performance

• Offscreen row skip and wrapped-height culling (#101): Render from the first visible message’s structural offset and use exact wrapped row coverage for culling

[0.8.4] - 2026-03-23 Changes

Fixes

• Chat bottom-height drift: Stop rendering and measuring the trailing separator row after the final chat message so auto-scroll no longer lands on a persistent empty line beneath the last Claude response; add regression tests for last-message rendering and height measurement

[0.8.3] - 2026-03-23 Changes

Performance

• Unified layout invalidation and progressive remeasure (#98): Replace the dirty_from suffix watermark with per-message staleness tracking, separated prefix-sum dirtiness, and a visible-first remeasure plan; preserve scroll anchors across in-flight resize and global remeasure replacement; single-message updates do exact changed-message remeasure plus targeted prefix repair instead of invalidating the entire suffix
• Incremental history retention accounting (#98): Cache per-message retained-byte estimates and maintain a rolling total so retention enforcement stops rescanning the full message list every cycle; cache tool raw_input byte estimates to avoid repeated JSON serialization in hot paths
• Incremental render cache budget (#98): Replace per-frame full cache budget scans with incremental slot metadata, rolling byte totals, and a pre-sorted eviction set rebuilt only when over budget
• Derive tool collapse state at render time (#98): Remove per-tool collapsed field; tools_collapsed is the session-level source of truth read at render time so Ctrl+O no longer walks and mutates every tool-call block
• Index terminal tool-call refs (#98): Replace linear duplicate checks on terminal subscriptions with a HashSet membership index; route attach, detach, and rebuild through shared tracking helpers

Dependencies

• Bump aws-lc-sys from 0.38.0 to 0.39.0 and aws-lc-rs from 1.16.1 to 1.16.2 (fixes RUSTSEC-2026-0044, RUSTSEC-2026-0048)
• Bump rustls-webpki from 0.103.9 to 0.103.10 (fixes RUSTSEC-2026-0049)
• Bump pulldown-cmark from 0.13.1 to 0.13.3 (#97)

[0.8.2] - 2026-03-18 Changes

Fixes

• Startup service status handling: Keep startup Claude service warnings and errors as transcript messages only; status errors no longer clear the draft or block users from trying a request during partial or uneven outages

[0.8.1] - 2026-03-18 Changes

Fixes

• Startup session settings propagation: Pass configured model and defaultPermissionMode through the SDK’s top-level session startup options so new sessions start with the expected live model and permission mode instead of falling back to provisional defaults
• Welcome banner model sync: Keep the welcome banner and header aligned through Connecting..., provisional default, and the first authoritative model update; freeze the welcome banner once the session model is resolved while allowing the header to continue tracking live model changes
• Claude status relevance filtering: Query the status summary endpoint and only surface startup warnings for Claude Code and Claude API, avoiding false-positive outage banners caused by unrelated Anthropic components
• Config cleanup: Remove obsolete MCP callback overlay code and stale config UI expectations left behind by the MCP management changes

[0.8.0] - 2026-03-17 Changes

Features

• Agent SDK 0.2.74 migration (#83): Upgrade from SDK 0.2.63 to 0.2.74; inline session settings replace per-flag overrides; agent progress summaries rendered in task tool-call bodies; model capability badges (adaptive thinking, fast mode, auto mode) shown in settings overlay
• AskUserQuestion support (#83): Dedicated question/response bridge path with horizontal and vertical option layouts; multi-select state tracking; inline annotation editing; question progress indicator; shared focus cycling infrastructure with permissions
• MCP management tab (#89): Live MCP server list with connection status indicators and tool counts; /mcp slash command; server detail overlay with context-aware actions (reconnect, toggle, authenticate, clear auth); OAuth authentication flow with browser launch and manual callback URL entry; elicitation support for URL-based and form-based modes; stale status revalidation with 30-second cooldown auto-reconnect
• Usage tab with quota visualization (#88, closes #87): Dual-source fetching (OAuth API first, CLI fallback); gauge bars with color-coded utilization (green/yellow/red); 5-hour, 7-day, and per-model quota windows; extra credits panel; /usage slash command and r manual refresh; 30-second TTL caching; OAuth credential expiry validation
• Plugin management (#85): Three-section Plugins tab (Installed, Marketplace, Marketplace Sources) with CLI-backed operations; install/enable/disable/update/uninstall actions via overlay dialogs; marketplace source add/remove with text input; MCP capability badges; /plugins slash command; 5-second inventory cache with background refresh
• Status tab and /status command (#80): Session, account, model, and settings information display; lazy account snapshot fetching via SDK; login method labels (Claude Max, API key variants); session name resolution with custom title/summary/prompt fallback chain; memory path and active setting sources display
• Unified syntax highlighting (#84): Replace ansi-to-tui with syntect for theme-aware coloring across shell commands, code blocks, and terminal output; ANSI escape stripping state machine; automatic raw unified diff detection and semantic coloring; language-aware code highlighting with extension-based syntax detection
• Session management enhancements (#83): Repository-scoped session discovery with worktree inclusion; session rename and AI-generated title actions in Status tab; text overlay for rename input with immediate visual feedback
• Tool output metadata (#83): Structured metadata for Bash (assistant-backgrounded badge, token-saver state), ExitPlanMode (ultraplan badge), TodoWrite (verification-needed badge), and Write/Edit (git repository labels in diff headers); MCP resource content typing with URI, MIME type, and blob saved-path hints

Fixes

• Paste-handled Enter suppression (#83): Treat paste-handled Enter as fully consumed in key dispatch; prevent suppressed paste newlines from falling through to non-char cleanup; restores inline multiline paste insertion for sub-1000 character payloads
• Bell notification fallback (#83): Restore bell alongside desktop notifications on terminals without OSC 9 support; keep auto notification routing aligned with pre-settings behavior

UI

• Config tab activation helper (#88): Centralized activate_tab function for consistent tab-switch behavior across /plugins, /status, /usage, /mcp, and keyboard navigation
• Shared text input widget (#85): Reusable text_input_line() and render_text_input_field() components used by Language, Session Rename, and Add Marketplace overlays
• Setting stepping (#85): Left/Right arrow editing for enum settings (Theme, Notifications, EditorMode, DefaultPermissionMode) in config view

Performance

• Progressive resize height recomputation (#90): Replace synchronous full-remeasure on terminal width change with frame-budgeted progressive convergence; scroll anchor preservation across resize; per-message exactness tracking with expanding measurement frontiers around the visible window; measurement budget of max(12, viewport_height) messages and max(256, viewport_height * 8) wrapped lines per frame
• Background file walker for mentions (#81): Replace synchronous BFS with ignore crate WalkBuilder on a background thread; query refinement refilters from cache instead of restarting the walk; pre-computed lowercase path variants eliminate per-sort allocation; bounded channel (1024 entries) with 500-entry drain budget per tick
• Input redraw and cache optimization (#82): Split input versioning into cursor-only and content epochs; syntax highlighting and height measurement caches keyed on content version; key handlers return visibility signals to suppress redraws for non-visual events; Windows paste burst jitter tolerance in pending confirmation window
• Background bash terminal detachment (#86): Detach terminal references when Bash tools reach completed or failed state; skip polling for non-running tools; prevent late bridge progress updates from reopening finalized tools; clear execute terminal references during forced tool finalization
• Dev/test profile tuning (#83): Line-tables-only debug info and disabled incremental builds for faster compilation

Licensing

• Apache-2.0: Switch project license from AGPL-3.0-or-later to Apache-2.0; SPDX single-line identifiers replace full header blocks across all source files

CI and Dependencies

• Bump @anthropic-ai/claude-agent-sdk from 0.2.63 to 0.2.74 (#83)
• Replace ansi-to-tui with syntect 5.3.0 (#84)
• Bump tui-textarea-2 from 0.10.1 to 0.10.2 (#82)
• Add version comparison to release dry-run workflow to skip unchanged versions (#82)

[0.7.1] - 2026-03-12 Changes

Fixes

• npm rollback for installs and releases: Revert active package manager guidance, package scripts, and GitHub release workflows from pnpm back to npm; runtime reinstall guidance now recommends npm install -g
• Leading blank row before Claude text: Trim leading rendered blank rows before the first visible assistant text block while preserving paragraph spacing for later content
• Deferred Enter submit stability: Plain Enter now snapshots and restores the exact draft instead of mutating the input before submit, fixing hidden newline leaks when the cursor is in the middle of the text

[0.7.0] - 2026-03-12 Changes

Features

• Native /login and /logout commands (#67): Shell out to claude auth login/logout with TUI suspend/resume; credential verification reads ~/.claude/.credentials.json directly; skip redundant operations when already authenticated or not authenticated
• User settings system (#74): 14 persisted settings across three JSON files (~/.claude/settings.json, <project>/.claude/settings.local.json, ~/.claude.json); metadata-driven two-column config view with compact narrow-terminal fallback; toggle/cycle/overlay mutation with immediate persistence
• Workspace trust (#74): Startup gated on per-project trust acceptance; path normalization for Windows drive letters, UNC paths, and symlinks; trust state persisted in ~/.claude.json
• Session launch settings (#74): Saved preferences (model, language, permission mode, thinking mode, effort level) propagate into every new session via SessionLaunchSettings; available models flowed back from SDK for dynamic UI
• Cancel-and-resubmit (#68): Submitting while the agent is running cancels the current turn and auto-resubmits once ready; draft stays visible and editable throughout with cancellation spinner banner
• Desktop and bell notifications (#68, #74): NotificationManager tracks terminal focus via DECSET 1004; fires bell + OS-native desktop toasts on permission requests and turn completion when unfocused; channel-based delivery (disabled, bell, OSC 9, desktop) driven by user preference
• Compaction overhaul (#68): /compact keeps chat history and appends a success system message after the turn completes; input and keyboard blocked during compaction; auto-compaction clears silently without a banner
• Cache observability (#69): CacheMetrics accumulator with rate-limited structured tracing; warn-level alerts for high utilization and eviction spikes with cooldown; integration test suite covering the full stream-to-split-to-measure-to-prefix-sums pipeline
• Unified textarea input (#70): Replace snapshot-based input state plus shadow editor with one persistent TextArea as source of truth; fixes wrapped visual-row cursor navigation; & subagent autocomplete now eager, matching @ and / behavior
• Incremental mention search (#74): Replace repeated full rescans with incremental BFS (400 entries/tick budget) and 4-tier ranking; .gitignore awareness with global, local, and nested rule support; search threshold lowered from 3 characters to 1

Fixes

• Permission allow_always persistence (#68, #71): Synthesize persistent addRules fallback when the SDK omits suggestions, fixing silent degradation to one-time allow; allow_always fallback now persists to localSettings
• Paste burst reliability (#71): Reworked burst detection into a timing-based state machine (Idle/Pending/Buffering) with idle flush; retro-capture cleanup for leaked leading characters; enter suppression during and immediately after paste; CRLF normalized to LF in insert_str
• Bridge reject_once match arm (#68): Added missing match arm that caused spurious warning logs on every permission prompt

UI

• Help panel keyboard navigation (#67): Up/Down scroll and selection for Slash Commands and Subagents tabs; dynamic visible-item computation from wrapped text heights; fixed panel height across tabs; orange highlight for selected item
• Paragraph gap preservation (#74): TextBlock state with trailing spacing metadata preserves paragraph gaps in chat rendering
• Built-in slash entries (#74): /config, /login, /logout appear in slash help and autocomplete
• Input blocking during async commands (#67): General CommandPending status with dynamic spinner text used by /login, /logout, /mode, /model, /new-session, /resume

Performance

• Capacity-based byte accounting (#69): Replace heuristic message sizing with IncrementalMarkdown::text_capacity measurement
• Protected-bytes tracking (#69): Non-evictable streaming-tail blocks excluded from eviction targets in render budget enforcement
• Layout invalidation consolidation (#69): InvalidationLevel enum and invalidate_layout helper replace ad-hoc invalidation across event flows

Refactoring

• Codebase split (#68): ui/tool_call.rs, app/connect.rs, app/slash.rs, app/state.rs, app/events.rs split into submodule directories (4-9 files each); bridge.ts split into 8 files under bridge/; all public APIs preserved via re-exports
• Usage pipeline removal (#68): Delete entire usage_update pipeline (bridge/usage.ts, UsageUpdate types, session/message token tracking, footer cost display) across TypeScript and Rust
• Input state unification (#70): Remove rebuild/sync debt from snapshot-based input; route all input reads/writes through accessor + replace flows on a single TextArea instance

CI and Dependencies

• Bump uuid from 1.21.0 to 1.22.0 (#72)
• Bump which from 8.0.0 to 8.0.2 (#73)
• Switch tui-textarea-2 from local path dependency to crates.io 0.10.1 (#70)
• Switch remaining npm command surfaces to pnpm across workflows, docs, and scripts (#74)

[0.6.0] - 2026-03-03 Changes

Features

• Agent SDK 0.2.63 migration (#64): Upgrade from SDK 0.2.52 to 0.2.63; align bridge, wire types, and session APIs with the new SDK surface
• Fast mode support (#64): Wire fast mode state end-to-end from bridge to TUI; footer badge shows FAST or FAST:CD during cooldown; deduplicated state change emission
• Rate limit updates (#64): Parse and display rate limit events with readable user-facing summaries including overage and reset timing
• Available agents and subagent autocomplete (#64): Wire available_agents_update across bridge and rust layers; & ampersand autocomplete for subagents; new Subagents help tab with two-column layout
• Session resume via SDK-native APIs (#64): Replace legacy JSONL parsing with resume_session backed by listSessions and getSessionMessages; align to SDK session metadata fields
• Interactive plan approval (#61): Intercept ExitPlanMode and render structured Approve/Reject widget with arrow navigation, y/n quick shortcuts, and allowedPrompts display
• Write diff capping (#61): Truncate Write tool diffs exceeding 50 lines to head/tail window with omission marker; auto-scroll on oversized writes; plan files exempted
• Startup service status checks (#65): Query status.claude.com during startup; emit warning or error system messages; lock input on outage-level errors
• Subagent thinking indicator (#60): Debounced (1500ms) idle indicator between subagent tool calls to avoid flicker; suppress normal spinner when subagent indicator is active
• System message severity levels (#64): Replace SystemWarning with MessageRole::System plus Info/Warning/Error severity with matching label colors
• Slash command output in transcript (#64): Local slash command results now surface in assistant transcript

Fixes

• Context percentage formula (#61): Exclude output_tokens from context calculation – Anthropic input formula is cache_read + cache_creation + input only; context % now updates as soon as input_tokens arrive
• Stale task scope cleanup (#65): Clear active_task_ids on tool scope reset to prevent subagent misclassification after cancelled tasks
• Subagent indicator false positives (#65): Gate thinking indicator on active spinner state to prevent false idle rendering
• SDK rejection sanitization (#65): Harden bridge rejection replacement with exact and known-prefix matching only on failed tool results
• Saturating coordinate math (#65): Use saturating arithmetic for header, input, autocomplete, and todo padding to prevent overflow panics

UI

• Footer module extraction (#61): Move all footer logic into dedicated src/ui/footer.rs; clean up imports in mod.rs
• Autocomplete stabilization (#61): Stable popover width; shift left near right edge; UTF-8-safe case-insensitive highlight ranges
• Help overlay improvements (#64): Add subagents tab; move tab-switch hint into help title; rename footer hint from “Shortcuts + Commands” to “Help”

Refactoring

• Handler decomposition (#61): Split large connection/event/key/slash/message handlers into smaller helpers; remove clippy::too_many_lines suppressions; FocusContext builder-style API

CI and Dependencies

• Bump actions/upload-artifact from 6 to 7 (#62)
• Bump actions/download-artifact from 7 to 8 (#63)
• Migrate from npm package-lock.json to pnpm pnpm-lock.yaml in agent-sdk (#64)

[0.5.1] - 2026-02-27 Changes

Fixes

• Input smoothness during rapid keys: Restore frame rendering during non-paste active key bursts by narrowing suppression to confirmed paste bursts only; preserves paste placeholder anti-flicker behavior

[0.5.0] - 2026-02-27 Changes

Features

• Paste handling overhaul (#53): Character-count threshold (1000 chars) replaces line-count; placeholder label updated; session identity tracking prevents append across separate pastes; burst finalization scoped to newly pasted range only
• Turn error classification (#54): TurnError strings matched against known patterns (rate limit, plan limit, max turns, quota, 429); actionable recovery hint pushed as a system message in chat; unclassified errors preserve existing behavior

Fixes

• Typed AppError enum (#54): NodeNotFound, AdapterCrashed, AuthRequired, ConnectionFailed, SessionNotFound variants with per-variant exit codes and user-facing messages

Performance

• Unified cache budgeting + LRU history retention (#52): Single cache budget across all message blocks; LRU eviction for long sessions; reduces memory growth on extended conversations

UI

• Footer three-column layout: Update hint and context percentage now render in separate right-aligned columns simultaneously instead of either-or

[0.4.1] - 2026-02-27 Changes

Fixes

• Dynamic bridge log levels (client.rs): Bridge stderr lines are now routed to the correct tracing level – [sdk error]/panic lines go to error!, [sdk warn] lines to warn!, and ordinary SDK chatter to debug! – instead of unconditionally emitting error! for every line
• Height cache invalidated on interruption (events.rs): TurnComplete and TurnError now call mark_message_layout_dirty on the tail assistant message so the height cache is re-measured after a cancelled or failed turn, fixing stale layout after interruption

[0.4.0] - 2026-02-27 Changes

Features

• Agent SDK migration (#45, closes #23): Replace @zed-industries/claude-code-acp with the in-repo Agent SDK bridge; align permission suggestions with SDK session/always-allow scope
• Session resume (#46, closes #22): --resume is cwd-aware and restores full transcript state; input locked while resuming; recent sessions shown in welcome context
• Token and cost tracking (#47, closes #21): Footer shows live Context: XX%; assistant turns show per-turn (Xk tok / $X.XX); compaction spinner during SDK-reported compaction
• Slash command popovers and AskUserQuestion (#48): Variable-input slash commands show dynamic argument popovers; full AskUserQuestion flow with option rendering and answer propagation

Fixes

• TodoWrite flicker (#45): Ignore transient payloads without a todos array so the list no longer clears and reappears mid-turn
• Failed Bash rendering (#45): Compress failed tool output to a single exit-code summary line instead of the full stderr dump
• Ctrl+C determinism (#46): Copy only when selection is non-empty and clear it after; otherwise quit
• Submission pipeline (#47): Single queue gate for submissions; cancel active turn before dispatching queued action; wait for turn-settle before ready
• Persisted tool-result normalization (#48): Strip leading box-drawing prefixes from tool result summaries

Performance

• Streaming frame cost (#49): Generation-keyed tool call measurement cache with O(1) fast path; terminal output delta-append; skip invalidation for no-op updates

Internal

• Agent SDK bridge modularized into focused modules (commands.ts, tooling.ts, permissions.ts, usage.ts, history.ts, auth.ts, shared.ts) (#48)
• Perf instrumentation markers for key invalidation, measurement, and snapshot paths (#49)

[0.3.0] - 2026-02-25 Changes

Features

• Startup update check (#30): Non-blocking check via GitHub Releases API with 24h cache, footer hint, Ctrl+U dismiss, --no-update-check / CLAUDE_RUST_NO_UPDATE_CHECK=1 opt-out
• Shortcuts during connecting (#38): Navigation and help shortcuts work while ACP adapter connects; input keys remain blocked
• Global Ctrl+Q quit (#38): Safe quit available in all states including connecting and error
• Input height API and word wrapping (#40): Adopt tui-textarea-2 v0.10 TextArea::measure() for input sizing, switch to WrapMode::WordOrGlyph, remove custom InputWrapCache plumbing

Fixes

• Height cache recalculation (#39): Track dirty message index and re-measure non-tail messages when content or tool blocks change
• Error state and input locking (#39): Connection and turn failures surface immediately with quit hint; input blocked during connecting/error
• Scroll clamp after permission collapse (#39): Clamp overscroll when content shrinks; ease scroll position for smooth settling; consume Up/Down with single pending permission
• Permission shortcut reliability (#29): Ctrl+Y/A/N work globally while prompts are pending with fallback option matching
• Tool-call error rendering (#29): Improved error handling with raw_output fallback and cleaner failed-call display

CI and Dependencies

• Bump actions/upload-artifact 4 to 6, actions/setup-node 4 to 6, actions/download-artifact 5 to 7 (#31, #32, #33)
• Bump pulldown-cmark from 0.13.0 to 0.13.1 (#34)
• Unify cargo publish, binary build, GitHub release, and npm publish into one workflow (#30)
• Add revert to allowed semantic PR title types (#37)

Internal

• Attempted migration to claude-agent-acp (#29), reverted to claude-code-acp (#37) due to feature parity gaps
• Regression tests for height remeasurement, scroll clamp, permission keys, connecting shortcuts, and update check

[0.2.0] - 2026-02-22 Changes

Rename and Distribution

• Rename crate/package to claude-code-rust
• Rename command to claude-rs
• Update release workflows and artifacts to publish/build under the new names

[0.1.3] - 2026-02-21 Changes

Fixes

• Rescan files on each @ mention activation so new/deleted files are reflected during a session
• Add keywords to npm package.json for better discoverability

[0.1.2] - 2026-02-21 Changes

UX and Interaction

• Add OS-level shutdown signal handling (Ctrl+C/SIGTERM) so external interrupts also trigger graceful TUI teardown
• Keep in-app Ctrl+C key behavior for selection copy versus quit, while unifying shutdown through the existing cleanup path
• Make chat scrollbar draggable with proportional thumb-to-content mapping
• Ensure scrollbar dragging can reach absolute top and bottom of chat history

[0.1.1] - 2026-02-21 Changes

CI and Release

• Replace release-plz with direct cargo and npm publish workflows
• release-cargo.yml: publishes to crates.io on Cargo.toml version bump
• release-npm.yml: builds cross-platform binaries, creates verified GitHub Release, publishes to npm with provenance
• Triggers based on Cargo.toml version changes instead of tag chaining
• Tags created by github-actions[bot] for verified provenance
• Remove release-plz.toml and cliff.toml

[0.1.0] - 2026-02-20 Changes

Release Summary

Claude Code Rust reaches a strong pre-1.0 baseline with near feature parity for core Claude Code terminal workflows:

• Native Rust TUI built with Ratatui and Crossterm
• ACP protocol integration via @zed-industries/claude-code-acp
• Streaming chat, tool calls, permissions, diffs, and terminal command output
• Modern input UX (multiline, paste burst handling, mentions, slash commands)
• Substantial rendering and scrolling performance work for long sessions
• Broad unit and integration test coverage across app state, events, permissions, and UI paths

The only major parity gap intentionally excluded from this release is token/cost usage display because the upstream ACP adapter currently does not emit usage data.

Architecture And Tooling

• Three-layer runtime design:
  • Presentation: Rust + Ratatui
  • Protocol: ACP over stdio
  • Agent: Zed ACP adapter process
• Async runtime and event handling:
  • Tokio runtime with ACP work kept on LocalSet (!Send futures)
  • mpsc channels between ACP client events and UI state machine
• CLI and platform support:
  • Clap-based CLI (--model, --resume, --yolo, -C, adapter/log/perf flags)
  • Cross-platform adapter launcher fallback (explicit path, env path, global bin, npx)
  • Windows-safe process resolution via which

Core Features

• Chat and rendering:
  • Native markdown rendering including tables
  • Inline code/diff presentation and tool-call block rendering
  • Welcome/system/tool content unified in normal chat flow
• Input and commands:
  • tui-textarea-2 powered editor path
  • Multiline paste placeholder pipeline and burst detection
  • @ file/folder mention autocomplete with resource embedding
  • Slash command workflow with ACP-backed filtering and help integration
• Tool execution UX:
  • Unified inline permission controls inside tool-call blocks
  • Focus-aware keyboard routing for mention, todo, and permission contexts
  • Better interruption semantics and stale spinner cleanup
  • Internal ACP/adapter failures rendered distinctly from normal command failures
• Session and app UX:
  • Parallel startup (TUI appears immediately while ACP connects in background)
  • In-TUI connecting/auth failure messaging and login hinting
  • Header model/location/branch context
  • Help overlay and shortcut discoverability improvements
  • Mouse selection and clipboard copy support
  • Smooth chat scroll and minimal scroll position indicator

Performance Work

Performance optimization was a major release theme across recent commits:

• Block-level render caching and deduplicated markdown parsing
• Incremental markdown handling in streaming scenarios
• Prefix sums + binary search for first visible message
• Viewport culling for long-chat scaling
• Ground-truth height measurement and improved resize correctness
• Conditional redraw paths and optional perf diagnostics logging
• Additional targeted UI smoothing for scroll and scrollbar transitions

Reliability, Quality, And Tests

• Significant test investment across both unit and integration layers
• Current codebase includes over 400 Rust #[test] cases
• Dedicated integration suites for ACP events, tool lifecycle, permissions, state transitions, and internal failure rendering
• CI includes test, clippy (-D warnings), fmt, MSRV, and lockfile checks

Release And Distribution Setup

• Rust crate is now publish-ready for crates.io as claude-code-rust
• CLI executable name is claude-rs
• npm global package added as claude-code-rust:
  • installs claude-rs command
  • downloads matching GitHub release binary during postinstall
• Tag-based GitHub Actions release workflow added for:
  • cross-platform binary builds (Windows/macOS/Linux)
  • GitHub release asset publishing
  • npm publishing (when NPM_TOKEN is configured)
• release-plz remains in place for release PR automation and changelog/version workflows

Known Limitations

• Slash command availability is intentionally conservative for this release:
  • /login and /logout are not offered
  • they remain excluded until ACP/Zed support is reliable enough for production use
• Token usage and cost tracking is blocked by current ACP adapter behavior:
  • UsageUpdate events are not emitted
  • PromptResponse.usage is None
• Session resume (--resume) is blocked on an upstream adapter release that contains a Windows path encoding fix