Feature Proposal: Terminal CLI for Programmatic Terminal Control

[rabsef-bicrym]

Summary

This proposal introduces a Terminal CLI to Zed that enables programmatic control of the integrated terminal—creating, managing, reading, and organizing terminal panes from the command line. A working implementation is ready for review.

Demo

Screen.Recording.2025-12-22.at.9.20.57.PM.mov

Motivation

Many developer workflows benefit from programmatic control of terminals inside the editor:

• Launch dev servers, test runners, and workers from scripts or tooling
• Read build logs and application output without leaving the workspace
• Organize terminals for multi-process workflows
• Handle interactive prompts while keeping terminals visible and in-context

AI assistants are one use case for this, but the core value is broader automation and scripting around terminals in the workspace.

Complementing the Agent Panel's Terminal Tool

Zed's Agent Panel terminal tool is intentionally one-shot and stateless. It cannot run long-lived processes and does not preserve terminal state between calls. The Terminal CLI fills that gap by enabling:

• Persistent terminals that maintain state across interactions
• Long-running processes like dev servers and watchers
• Output monitoring over time
• Layout management for multi-service workflows

Possible Follow-ups (Non-blocking)

If this CLI is accepted, a future Zed extension could wrap these commands in an MCP server to expose persistent terminals to the Agent Panel. This would allow agents to create visible terminals and monitor long-running tasks without blocking on one-shot commands.

Prior Art

iTerm2 provides similar functionality through its Python API, gated behind an experimental feature flag.

Groundwork PRs

Over the past week, I submitted three PRs as groundwork for this feature:

1. #45180 (merged) - Fixed RevealStrategy::NoFocus so terminals can be created without stealing focus. Closes RevealStrategy::NoFocus and RevealStrategy::Never do not respect focus settings when terminal pane has focus #45179.

2. #45282 (merged) - Fixed scrollbar arithmetic underflow panics with saturating_sub. Closes Terminal scrollbar panics on arithmetic underflow #45281.

3. #45280 (closed) - Added Pane::add_item_behind for background tab creation. Closes Pane::add_item lacks API for adding items without tab activation #45279. This was closed by @probably-neb with the feedback: "without usage code, I can't test that it works and I don't see the benefit in merging code that is just unused." I responded that I'd return with a CLI PR providing that usage—this is that PR.

The Feature

A zed terminal subcommand with the following operations:

Command	Description
create	Create a new terminal (with cwd, command, env, title options)
send	Send text input to a terminal
key	Send special keys (enter, ctrl-c, etc.)
read	Read terminal screen content
list	List all terminals with entity IDs
close	Close a terminal
split	Split a pane in a direction
move	Move a terminal between panes
layout	Get/set terminal panel layout
focus	Focus a specific terminal
idle	Check if terminal has running foreground process
cwd	Get terminal's current working directory
title	Set/clear terminal title override

Security: Disabled by default. Users must explicitly enable with:

{ "terminal": { "cli_enabled": true } }

ZED_TERM_ID is always present in terminals; the CLI uses it when enabled.

Demo

Here's a demo script that creates a spiral of numbered terminal panes, animates movement through them, and showcases layout reorganization:

Click to expand demo script

#!/bin/bash
# Terminal CLI Demo - Spiral Animation
set -e

DELAY=${DELAY:-1.5}
[[ "$1" == "--fast" ]] && DELAY=0.5

CLI="zed"
[[ -f "./target/debug/cli" ]] && CLI="./target/debug/cli --zed ./target/debug/zed"

term() { $CLI terminal "$@"; }
step() { echo ">>> $*" >&2; term "$@"; sleep "$DELAY"; }

show_marker() {
    local id=$1 num=$2
    term send "$id" "clear && echo '╭─────╮' && echo '│  $num  │' && echo '╰─────╯'"
    term key "$id" enter
}

echo "=== Terminal CLI Demo: Spiral Animation ==="

# Identify ourselves
LIST_OUTPUT=$(term list)
MY_ID=$(echo "$LIST_OUTPUT" | jq -r '.workspaces[].terminals[] | select(.you_are_here == true) | .entity_id')
echo "My terminal ID: $MY_ID"

# Create shadow tab (holds pane open during moves)
SHADOW_ID=$(step create --in-pane-of "$MY_ID" --no-activate --title "Shadow" | jq -r '.entity_id')
show_marker "$SHADOW_ID" "6"

# Create spiral pattern via splits (1-5 spiraling outward)
TERM_RIGHT=$(step split "$MY_ID" --direction right | jq -r '.entity_id')
show_marker "$TERM_RIGHT" "1"

TERM_BOTTOM=$(step split "$MY_ID" --direction down | jq -r '.entity_id')
show_marker "$TERM_BOTTOM" "2"

TERM_LEFT=$(step split "$MY_ID" --direction left | jq -r '.entity_id')
show_marker "$TERM_LEFT" "3"

TERM_UP=$(step split "$MY_ID" --direction up | jq -r '.entity_id')
show_marker "$TERM_UP" "4"

TERM_CENTER=$(step split "$MY_ID" --direction right | jq -r '.entity_id')
show_marker "$TERM_CENTER" "5"

echo "Spiral created!"

# Traverse spiral OUT (center → outer)
step move "$MY_ID" --to-pane-of "$TERM_CENTER"
step move "$MY_ID" --to-pane-of "$TERM_UP"
step move "$MY_ID" --to-pane-of "$TERM_LEFT"
step move "$MY_ID" --to-pane-of "$TERM_BOTTOM"
step move "$MY_ID" --to-pane-of "$TERM_RIGHT"

# Traverse spiral IN (outer → center)
step move "$MY_ID" --to-pane-of "$TERM_BOTTOM"
step move "$MY_ID" --to-pane-of "$TERM_LEFT"
step move "$MY_ID" --to-pane-of "$TERM_UP"
step move "$MY_ID" --to-pane-of "$TERM_CENTER"
step move "$MY_ID" --to-pane-of "$SHADOW_ID"

# Layout reorganization showcase
step layout --tile-horizontal   # Stack vertically
step layout --tile-vertical     # Arrange side-by-side
step layout --consolidate       # Collapse to tabs

# Cleanup
step focus "$MY_ID"
for id in "$SHADOW_ID" "$TERM_RIGHT" "$TERM_BOTTOM" "$TERM_LEFT" "$TERM_UP" "$TERM_CENTER"; do
    step close "$id"
done

echo "=== Demo Complete ==="

Implementation

The PR is ready for review. It includes:

• Full CLI implementation with parsing/serialization tests
• Documentation additions to docs/src/command-line-interface.md
• The previously-declined add_item_behind method, now with concrete usage

PR link: #45558

[crsren]

zed terminal create / read /send would let agents spawn other agent sessions. I'm largely using Zed to manage multiple Claude Code sessions (alongside git/file UI) at this point, and terminal control would help a ton with orchestration.

[rabsef-bicrym]

I cannot wait to get exactly that kind of orchestration across my Claude Team all in Zed. Exactly the vision.

[gianpaj]

Would this allow the Zed Agent to kick off a background task, such as starting a Next.js server and tailing the logs?
Claude's code can do this, but I feel like Zed Agent is not able to do this

Claude can easily

[rabsef-bicrym]

It's actually a bit different from "background task." This allows control of the Terminal display at the bottom (usually) of Zed. It can add new panes, tabs, etc. (see demo video).

Claude Code likes the background task and that's great but it means at minimum additional keystrokes to see for yourself what's happening.

With this, the coding agent (CC or ZA, or whatever) can divide the Terminal display in half, add a new pane to the right of itself and run, e.g., your server - and show you the boot sequence, or whatever.