Skip to content

Feat agent terminal#13899

Open
ZeroZ-lab wants to merge 19 commits intoCherryHQ:mainfrom
ZeroZ-lab:feat-agent-terminal
Open

Feat agent terminal#13899
ZeroZ-lab wants to merge 19 commits intoCherryHQ:mainfrom
ZeroZ-lab:feat-agent-terminal

Conversation

@ZeroZ-lab
Copy link
Copy Markdown
Contributor

What this PR does

This PR introduces an Agent Terminal execution capability for Cherry Studio.

A Terminal panel is added to agent sessions (xterm.js + node-pty) so the agent can run shell commands and stream output back to the UI, enabling full “reasoning → execution → feedback” workflows.

Before this PR:

  • Agents could only chat (text-only), with no ability to execute commands.

After this PR:

  • Adds an Agent Terminal panel to the session UI
  • Adds a main-process TerminalService to manage PTY lifecycle (create/write/resize/kill)
  • Streams command output to the renderer
  • Terminal instances are scoped per session for isolation
CleanShot 2026-03-30 at 15 38 41@2x CleanShot 2026-03-30 at 15 38 53@2x

Fixes #13887

Why we need it and why it was done in this way

We need a way for agents to perform real operations in developer workflows (running scripts, starting servers, debugging, etc.).

A terminal is the most general execution interface (CLI-first, broad coverage). Using PTY provides high fidelity, cross-platform behavior.

The following tradeoffs were made:

  • Introduces a native dependency (node-pty) and associated build complexity
  • Execution capability has security implications; this initial version prioritizes baseline functionality and can be hardened later (permissions/sandbox/approval)
  • Limits scope to core terminal I/O and session lifecycle to keep the first iteration stable

The following alternatives were considered:

  • Mock terminal (no real execution)
  • Tool-specific APIs (limited coverage; high maintenance)
  • Containerized/sandbox execution (heavier infra for first iteration)

Links to places where the discussion took place:

Breaking changes

None.

Special notes for your reviewer

Please pay attention to:

  • TerminalService lifecycle correctness
  • IPC channel design and message typing
  • Session isolation and terminal cleanup
  • Renderer stability/performance for long-running output

Checklist

This checklist is not enforcing, but it's a reminder of items that could be relevant to every PR.
Approvers are expected to review this list.

  • PR: The PR description is expressive enough and will help future contributors
  • Code: Write code that humans can understand and keep it simple
  • Refactor: You have left the code cleaner than you found it (Boy Scout Rule)
  • Upgrade: Impact of this change on upgrade flows was considered and addressed if required
  • Documentation: A user-guide update was considered and is present (link) or not required
  • Self-review: I have reviewed my own code before requesting review from others

Release note

Add Agent Terminal execution capability: run shell commands from agent sessions.

Design for adding a persistent interactive terminal panel to
Agent Session view using node-pty + xterm.js architecture.
Step-by-step plan for implementing terminal feature with
node-pty + xterm.js across 10 tasks.

Signed-off-by: GuanMu <ballmanjq@gmail.com>
…nels)

Signed-off-by: GuanMu <ballmanjq@gmail.com>
Signed-off-by: GuanMu <ballmanjq@gmail.com>
Signed-off-by: GuanMu <ballmanjq@gmail.com>
Signed-off-by: GuanMu <ballmanjq@gmail.com>
Signed-off-by: GuanMu <ballmanjq@gmail.com>
Signed-off-by: GuanMu <ballmanjq@gmail.com>
Signed-off-by: GuanMu <ballmanjq@gmail.com>
Signed-off-by: GuanMu <ballmanjq@gmail.com>
Signed-off-by: GuanMu <ballmanjq@gmail.com>
Replace PanelGroup with Group, PanelResizeHandle with Separator,
and adjust direction prop to orientation.

Signed-off-by: GuanMu <ballmanjq@gmail.com>
Signed-off-by: GuanMu <ballmanjq@gmail.com>
…sion management

- Removed outdated agent terminal design document.
- Added TerminalService to manage PTY instances and session-specific working directories.
- Enhanced SessionService to retrieve session details by ID.
- Updated AgentChat component to manage terminal visibility and errors per session.
- Refactored TerminalPanel to support dynamic theming and session management.
- Implemented tests for TerminalService and AgentChat components to ensure functionality.
@ZeroZ-lab ZeroZ-lab marked this pull request as ready for review March 30, 2026 07:42
@DeJeune
Copy link
Copy Markdown
Collaborator

DeJeune commented Mar 30, 2026

amazing work! Can you change the base to v2? We are about to freeze any PRs submitted to the main branch, switching to V2 will facilitate faster review and merge.

@DeJeune
Copy link
Copy Markdown
Collaborator

DeJeune commented Mar 30, 2026

https://www.npmjs.com/package/@lydell/node-pty only offer prebuilt packages for the current platform, consider switching to this one.

@ZeroZ-lab
Copy link
Copy Markdown
Contributor Author

@DeJeune
Sure, I'll change the base to v2 and switch to @lydell/node-pty.

Signed-off-by: GuanMu <ballmanjq@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature]: Add a simple system terminal execution capability for the agent (similar to Codex CLI).

2 participants