Zed Industries
Download

Terminal Threads

Terminal Threads are terminal-backed threads in the Threads Sidebar. Use them when you want to run an agent CLI or TUI directly in Zed.

Terminal Threads are different from External Agents. External Agents integrate with Zed through ACP and render as agent threads. Terminal Threads run the native command-line tool in a terminal that Zed organizes as a thread.

What Zed Owns

Zed owns the thread surface:

  • the terminal-backed thread in the Threads Sidebar
  • thread grouping by project
  • switching and organizing the terminal session alongside other threads

What the CLI Owns

The CLI or TUI running inside the terminal owns its own:

  • authentication
  • model/provider configuration
  • subscriptions or API keys
  • tool configuration
  • skills and instruction files
  • MCP configuration

Zed Agent profiles, Zed Agent tool permissions, Zed Skills, and Zed Agent MCP settings do not automatically apply to Terminal Threads.

Opening a Terminal Thread

Open the new-thread menu from the Agent Panel using the agent selector button on the left or the + icon in the top-right of the panel toolbar, then choose Terminal. The Terminal Thread opens in the panel body, just like switching to an agent thread.

You can open as many Terminal Threads as you like. Each gets its own entry in the Threads Sidebar.

Terminal Thread Titles

The terminal title in the toolbar updates automatically to reflect the running shell or process. You can also set a custom name by clicking the title or the pencil icon that appears on hover.

Notifications

When a terminal produces a bell character while not in focus, Zed notifies you the same way it does when an agent finishes: with a visual pop-up and an optional sound. Clicking the notification brings the terminal into focus and clears the indicator.

The same agent.notify_when_agent_waiting and agent.play_sound_when_agent_done settings apply.

Closing Terminal Threads

Unlike agent threads, Terminal Threads are closed rather than archived. They do not go to Thread History. To close one, hover over it in the Threads Sidebar and click the × button, or select it and press shift-backspace|shift-backspace.

CLI/TUI Setup Notes

Some agent CLIs and TUIs can send terminal signals, such as bell notifications or title updates, that Zed uses to show useful context in the sidebar.

Claude Code Notifications

Claude Code can notify you when it finishes a task or pauses for permission. To enable this, set preferredNotifChannel to "terminal_bell" in your Claude Code user settings:

{
  "preferredNotifChannel": "terminal_bell"
}

You can also set this from within Claude Code by running /config, selecting Local Notifications, and choosing Terminal Bell.

If you run Claude Code inside tmux, bell notifications may not reach the outer terminal unless passthrough is enabled. Add this to ~/.tmux.conf:

set -g allow-passthrough on

For more, see the Claude Code documentation.

Amp Notifications

Amp updates terminal titles automatically and can also notify you when it needs your attention. To enable notifications in Zed Terminal Threads, add AMP_FORCE_BEL=1 to your terminal environment settings:

{
  "terminal": {
    "env": {
      "AMP_FORCE_BEL": "1"
    }
  }
}

Restart Amp after adding the environment variable.

OpenCode Notifications

OpenCode can update terminal titles automatically. For Zed notifications, add an OpenCode plugin that emits a terminal bell when OpenCode needs your attention.

Create .opencode/plugins/zed-bell.js in your project, or ~/.config/opencode/plugins/zed-bell.js to use it globally:

export const ZedBell = async () => {
  return {
    event: async ({ event }) => {
      if (event.type === "session.idle" || event.type === "permission.asked") {
        process.stdout.write("\x07");
      }
    },
  };
};

Restart OpenCode after adding the plugin.

Pi Notifications

Pi can use an extension to emit a notification when it finishes a turn. Create .pi/extensions/zed-bell.ts in your project, or ~/.pi/agent/extensions/zed-bell.ts to use it globally:

import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

export default function (pi: ExtensionAPI) {
  pi.on("agent_end", async () => {
    process.stdout.write("\x07");
  });
}

Restart Pi after adding the extension, or run /reload if the extension is in one of Pi's auto-discovered extension locations.

Codex Terminal Titles

Codex can update the terminal title as it works, which Zed uses to show useful context for Codex Terminal Threads in the sidebar, such as the project, current status, branch, model, or task progress.

To configure this from within Codex, run /title and use the picker to choose which fields appear and in what order. Codex saves the selection to tui.terminal_title in ~/.codex/config.toml. You can also edit it directly:

[tui]
terminal_title = ["spinner", "project-name", "run-state", "thread-title"]

Credentials and Remote Projects

Credentials come from the terminal session and the CLI/TUI running inside it.

In remote projects, the CLI may read the remote shell environment and remote config files. In local Terminal Threads, it reads the local shell environment and local config files. Zed does not copy API keys from LLM provider settings into Terminal Threads.

When to Use Terminal Threads

Use Terminal Threads when:

  • you want the tool's native CLI/TUI experience
  • no ACP integration exists
  • you want subscription behavior owned by the CLI
  • you want the CLI to use its own native config files

For ACP-integrated agents, see External Agents.