Working with AI agents

Zshell's automation is primarily for AI coding agents. It gives them a safe way to work with Zshell's panes and coordinate other agents; it is not another command language you need to learn.

After you enable it, keep talking to your coding agent normally. It can create a background pane, start a delegated worker, run a command, wait for the result, and bring the answer back without taking focus from the pane you are using.

Turn it on once

Open Settings → Automation and enable AI. Then start a new terminal or restart any coding agent that was already running.

Zshell supports Codex, Claude Code, Gemini CLI, Grok Build, OpenCode, Cursor Agent, Aider, Amp, and Pi. If Zshell finds an existing agent setup that conflicts with this feature, it leaves that setup unchanged, returns the toggle to its previous state, and shows the error in Settings.

Ask in plain language

Tell your agent the outcome you want. For example:

Run the focused tests in a background pane and tell me what fails.

Delegate this bug to another Codex agent, then review its result.

Ask the agent working on the API whether the schema is ready, then pass the answer to the agent running the tests.

Start the dev server beside us, wait until it is ready, and give me the URL.

Check whether the background agent is finished. If it is blocked, tell me what it needs.

The agent handles Zshell's automation interface on your behalf. You do not need to type or memorize any Zshell automation commands.

Let agents coordinate across panes

You can split related work across several Zshell panes and ask your main agent to coordinate it. For example, one agent can work on an API while another updates tests. The coordinating agent can ask a specific worker for its findings, send a follow-up, pass the useful result to another worker, and bring the combined answer back to you. The workers can use different supported coding tools.

This removes the copy-and-paste step from parallel work. Each agent keeps its own conversation in its own pane, while the coordinating agent passes along only the question, update, or result the other worker needs.

Sending a follow-up does not mean the work is finished. The coordinating agent still waits for the worker, reads its result, and checks the outcome. A message from another agent is also never treated as your approval. Permissions, credentials, trust decisions, and destructive actions still come back to you.

Keep working while it runs

Delegated panes stay in the background unless you ask to see them. When a provider-native lifecycle integration reports state, Zshell shows it on the agent's pane and tab:

Zshell records a prompt it submits as Working, but it never scans rendered terminal text to guess what happens next. Blocked and Done transitions and their notifications require a provider lifecycle report. If an agent does not provide one, inspect its pane and the resulting project changes directly instead of relying on a guessed status.

When an integration reports that an agent finished or needs input, Zshell can also send a notification. Press Cmd+Shift+A to jump to the next reported agent that needs your attention.

A typical workflow

1. Start your usual coding agent in a Zshell terminal.
2. Ask it to delegate a bounded task, run something in the background, or coordinate another agent.
3. Continue working in your current pane while Zshell keeps the delegated work visible in the project layout.
4. Follow a provider-reported Working, Blocked, or Done badge when available. If the tool does not report lifecycle, open the pane to inspect its conversation or terminal output instead.
5. Review the resulting files in the Git panel, inspect the diff, and decide what to keep.

You stay in control

• Agent automation stays inside the current Zshell project and cannot reach panes in another project or window.
• Background work does not take focus unless you explicitly ask for it.
• Zshell never answers permission, credential, trust, or destructive-action prompts for you. A provider-reported blocked agent hands that decision back to you.
• Reported completion is a signal to review the result, not an automatic approval of the agent's changes.

If an agent does not use Zshell

• Confirm that Settings → Automation → AI is enabled.
• Open a new Zshell terminal if the current one existed before you enabled the setting.
• Restart an agent that was already running when you enabled it.
• Check Settings for an inline setup error.
• Ask explicitly for a "background Zshell pane" or a "delegated Zshell agent" if you want the agent to use this workflow for a task.