The Autonomous Agent

AITerm has two Pro agent modes for multi-step tasks. Both run every command through the same security gate as everything else, and both keep you in control.

• /agent <task> — manual step-through. AITerm proposes one command at a time and runs each only after you approve it. Works on any shell.
• /auto <task> — Autopilot. Provably-safe in-project steps can run automatically; anything risky pauses for your approval. Autopilot needs an integrated zsh/bash shell so AITerm can track when each command finishes; if you don't have one, AITerm tells you to use /agent instead.

Agent help from the app

The following sections are generated from AgentHelpCatalog.swift.

One input, you're in control

Type a shell command and it runs. Type plain English and AITerm streams back an editable command with a risk badge — whatever sits in the bar when you press Return is exactly what runs. Return runs, Esc discards. A leading space forces a literal command; a leading ? or :, or a trailing ?, forces an AI translation.

Quick AI helpers (Free)

/fix reads the last command's failure (plus your repo, branch, language) and proposes a correction shown struck-old vs green-new — it only runs when you press Return. If the AI asks you something, reply with /fix <your answer>. /explain gives a read-only, plain-English explanation of the last command and output — it never runs anything.

The agent (Pro)

/agent <task> — manual step-through. The AI proposes each command with its risk badge; it runs only when you press Return. Works on any shell.

/auto <task> — Autopilot. It runs on its own, but only auto-executes provably-safe steps that stay inside your project folder (reading and listing files, read-only git, and similar inert steps). Anything that could delete data, reach the network, run a build or script, or act outside the folder pauses for your one-tap approval. /auto needs an integrated zsh/bash shell; without one it points you to /agent.

The Autopilot panel

On a paused step: Approve (Return) · Edit · Skip · Stop. A step counter shows n / 15. The Trust this session toggle lets your project's build and dependency commands (npm install, cargo build, make…) auto-run for the rest of this run — only exact, safe build forms, never an arbitrary command, and your Safety Profile still applies. A run ends three ways: the AI reports it's done (green summary), it hits the 15-step ceiling, or you press Stop. After 3 failures in a row it pauses and offers a fix.

Staying in control

Risk badges — green safe runs; amber caution runs; red destructive runs on Return; the red Irreversible tier is the only one that always stops for an explicit confirmation first. Click any badge for the reason, a safer alternative, and a rollback command.

Safety Profiles (AI menu) only ever tighten the gate, never loosen it: Personal (default, never hard-blocks) → Work (confirm destructive) → Production (confirm caution and destructive, block Irreversible) → Locked Down (confirm anything above safe, block destructive and up). They apply to agent steps too — so on Production an Irreversible step is blocked, and on Locked Down anything destructive is blocked outright, even in Autopilot.

Direct terminal typing — click inside a pane's terminal to type raw on the shell line; the AI gate steps aside (an "AI gate off" indicator shows). It returns to the AI bar when you click the bar, get a proposal, or after 15s idle. Doing this during an agent run pauses the agent; returning focus to the AI bar resumes it.

Dry Run (Settings) runs nothing — every command shows "🔎 Dry run — not executed". It's a per-session Settings toggle, not a slash command.

Good to know

Switching AI providers mid-run pauses the agent ("Provider changed — run paused. Re-confirm to continue.") so the next step doesn't silently hit a different model. Free vs Pro: /fix and /explain are Free; /agent, /auto, and /runbook are Pro (using one triggers an upsell, not an error).

The agent panel

When a run starts, a panel appears above the input bar showing the task, a checklist of completed steps (green check for success, red ✗ for a failure), and a status line that changes with the run:

• "Sketching a plan… (Esc to stop)" — at the start of a run, the agent is writing a short outline of the task before it proposes the first step. Press Esc or Stop to end the run while it waits.
• Planning the next step… — the agent is thinking.
• "Paused — you have the terminal. The agent continues when you're back in the AI bar." — you clicked into the terminal. Nothing is requested or typed while you work there; a step that arrives meanwhile waits for you.
• "Waiting — the terminal was busy." or "Waiting — the terminal has unsent text." — the agent only types a step into the terminal when its prompt is idle and empty. Let the running program finish, or discard the half-typed text with ⌃C in the terminal (in fish, ⌃C and then Return on the emptied line), then approve the step again (in /agent, press Return on it). Text you type into the terminal while a command is running counts too: the shell puts it on its next command line, so the agent waits for that ⌃C even if the line has since run or looks empty. This check needs AITerm's shell integration, which zsh, bash and fish have. In any other shell, and in fish until you run a first command, the agent can only tell when a full-screen program such as vim or less is open, so clear any half-typed text in the terminal before you approve a step.
• "Review the command below, then press Return to run it (Esc to stop)." — the proposed command is loaded in the input bar. Edit it if you want, press Return to approve and run it, or Esc to stop the run.
• A file write waiting for review shows its own card instead, with Approve and Skip buttons — see File writes.
• If an approved step needs a confirmation and you choose Cancel, the step comes back for review instead of ending the run, and nothing is sent to the terminal. Use safer alternative puts the safer command in the input bar as your edit of the step — press Return to run it instead.
• Running… — the approved step is executing.
• "Paused after a failure — fix the command, retry, or stop." — see below.
• A green checkmark with a summary when it finishes, or "Stopped." if you stopped it.

The panel's top-right button is Stop during a run and Dismiss once the run has finished or stopped. Closing the run's pane, tab or window, opening a workspace, starting a runbook or starting another /agent or /auto run ends it the same way: a step waiting for your approval is recorded as declined in the Security Log, and a step still running gets ⌃C. In /auto, a Trust this session toggle lets your project's exact build/dependency commands (like npm install, cargo build, make) auto-run for the rest of that run — only those exact safe forms, never an arbitrary command, and your Safety Profile still applies.

The plan checklist

At the start of a run the agent sketches a short plan, shown under Plan in the panel. It is an advisory outline, not a script:

• An item ticks off only when a step succeeds. A failed, blocked or skipped step never ticks one off.
• At most 8 items are shown; a longer plan ends with a line such as "+3 more".
• Once the run finishes or is stopped, no item is shown as in progress.
• The plan never decides what runs. Every step is still proposed one at a time and goes through the same approval and safety checks. If the model returns no usable plan, the run simply starts without one.

The scope line

When a step that deletes, moves or changes permissions is waiting for your approval, a one-line summary of what it would touch appears with it. AITerm works this out by looking at the files on disk; it never runs the command to find out. For example:

• "Would delete 3 paths."
• "Would move 1 path → /Users/you/project/archive." — a move also names the full path it goes to.
• "Targets not found — nothing to delete."

When it cannot see the full scope, it warns you instead of guessing. The examples below are for a delete; a move says "move" instead, and a permissions change says "change permissions on".

• "⚠︎ Can't preview the full scope (globs) — this may delete files." — a pattern that spans folders, such as */*.log, or that sits inside a symlinked folder is not expanded. A pattern in a single folder, such as *.log, is expanded and counted.
• "⚠︎ Can't preview the full scope (symlinked folder) — this may delete files." — AITerm does not look inside a folder reached through a symbolic link.
• "⚠︎ Can't preview the full scope (globs or symlinked folders) — this may delete files." — the command has both.
• "⚠︎ Can't preview the scope (shell expansion) — this may delete files." — the command uses variables, backticks or {a,b} lists.
• A count that says "at least" means AITerm stopped counting at 1,000 paths, so the real number may be larger.
• A count that ends with "⚠︎ plus unexpanded globs (scope may be larger)", "⚠︎ plus symlinked folders (scope may be larger)" or "⚠︎ plus unexpanded globs or symlinked folders (scope may be larger)" means some targets were counted and others could not be.

For a command that has its own dry-run mode (such as git push), the line reads "Dry-run available — preview the effect before running." instead.

The scope line is a summary, not a file-by-file diff. It goes away if you edit the command into something else.

File writes

Besides shell commands, the agent can propose writing a whole text file — creating a new one or replacing an existing one. A file write always pauses for you, in /agent and in /auto, even with Trust this session on.

The card shows:

• The full path of the file. A relative path is taken from the folder your shell is in when the agent proposes it; changing folders afterwards does not move the write.
• A risk badge and a one-line summary: "New file, 3 lines", a note such as "Overwrites an existing file: +1 / −0 (2 → 3 lines)" for a change to an existing file, or "Replaces entire file (… → … lines)" when the file is too large to compare line by line.
• Any warning from your Safety Profile — a write inside a .git folder, for example, reads "Writes inside .git — hooks and config there run as code on your next git command" — and, when the file lands outside the project, "Outside the project directory — writes into" followed by the folder.
• The exact text that will be written, in a scrollable box. When the file is longer than the box, "More lines below — scroll the box" appears above it.
• One line saying what the buttons do: "Approve writes this file now. Skip tells the agent you declined." A write is approved only with a click — pressing Return does not approve it.

• The contents box shows up to 400 lines or 64 KB. For a longer file it says exactly how much it is showing — for example "Showing the first … of … lines — approve only if you trust the rest."
• An existing file larger than 4 MB is not opened for a preview, so the agent cannot overwrite it.

There is no Edit button: to change what gets written, Skip the step and tell the agent what you want. Skip records the step as skipped and tells the agent you declined that write, so it chooses something else. Approve writes the file; Stop ends the run.

Every write goes through the same security gate as commands, and AITerm checks the file again at the moment it writes:

• Writes into protected places are refused — system folders (including /tmp and /var, which live under /private on macOS), your SSH, cloud and shell startup files, ~/Library/LaunchAgents, AITerm's own settings folder, and any .git folder. Under the Personal profile such a write is not refused but opens a "Confirm file write" dialog; Cancel is the default button, and only Write anyway writes. Other profiles can also ask you to confirm a risky write, such as replacing an existing file. If you cancel, the card comes back with "Write declined — review it again, skip, or stop."
• AITerm will not write through a symbolic link or a hard link, over a folder, or into a folder that does not exist yet ("The parent directory does not exist.") — it never creates folders.
• It only writes text: "The existing file isn't UTF-8 text, and this tool only writes text." means it will not replace a binary or differently encoded file. The file it writes always ends with a line break.
• If the file changed after the card appeared, nothing is written and the card is shown again with the current contents. A write that would change nothing is refused.
• Replacing a file keeps its permissions, so a private file stays private and a script stays executable. Extended attributes and access-control lists are not kept.
• With Dry Run on, nothing is written: you see "🔎 Dry run — not written" and the step is recorded as skipped. You are not asked to confirm a write that Dry Run will not make.
• Every approved, refused or dry-run write is recorded in the Security Log.
• A file write cannot be undone from the agent panel, and after one, Undo last step is not offered for the steps before it either.

Undo last step

After a run has finished or been stopped, an Undo last step button can appear in the panel. It offers to reverse the run's last step — for example rmdir newdir after mkdir newdir.

• It covers only the last step, and only once. There is no undo for the whole run.
• It only works in the folder that step ran in. From anywhere else, AITerm tells you which folder the step ran in and asks you to go back there first.
• Undo never runs anything by itself. It loads the reverse command into the input bar so you can read it. Press Return to run it, or Esc to leave it — Undo stays available until you press Return.
• An unedited Undo goes through the agent's stricter safety check — the same always-enforced check every agent step uses, even with Enforce Security Restrictions turned off. If you edit the command first, it becomes an ordinary command and gets the regular checks for anything you type.
• Pressing Return uses it up, even if a safety check then blocks the command or you cancel a confirmation.
• Running any other command before you use it removes the offer, because the reverse command may no longer be right.
• While the task is still running, a greyed-out Undo last step button appears only when the last step so far can be undone. Hover over it to see "Available when the task ends".

Only a few kinds of step have a reverse at all: mkdir <folder> (undone with rmdir), renaming one file or folder with mv, git commit (undone with git reset --soft HEAD~1) and switching branches with git checkout or git switch. Anything else, such as rm or make, has no undo.

Even among those, some steps can never be undone, so no button appears after them:

• A step that failed, or one whose folder AITerm could not tell.
• Anything run with sudo or doas.
• mkdir -p.
• git commit --amend, and git commit with --dry-run, --porcelain, --short or --long, which don't commit.
• A git checkout / git switch that creates or resets a branch (-b, -c, -B, -C), forces (-f, --force, --discard-changes) or merges (-m, --merge), and a git checkout of a file or folder.
• A mv into an existing folder, a mv that may not have happened (such as mv -n or mv -i), and a mv that left a file at the old name or nothing at the new one.
• A rename that only changes letter case, such as mv readme.md README.md, on a case-insensitive disk (the macOS default). Afterwards the folder looks the same whether the rename happened or the file already had that name, so AITerm cannot tell which reverse would be right.

A read-only last step like ls or git status does not hide the undo for the step before it.

What auto-runs vs. what pauses

In /auto, only clearly-safe, in-project steps run on their own — things like reading a file, cd within the project, creating a directory under the project, or read-only git. Anything that deletes, reaches the network, runs over SSH, uses shell operators, or is otherwise risky pauses for your approval. In /agent, every step pauses for approval by design.

Even a safe step never runs on its own while you have the terminal, while a program is running in it, or while its prompt holds text you typed but did not send — it waits on the card, so nothing is ever typed on top of your work.

Limits and failure handling

• A run stops when it finishes, when you stop it, or when it reaches the 15-step ceiling (the panel shows a n / 15 counter).
• After 3 failures in a row, the run pauses and offers a fix — you can edit the command, retry, ask AI to fix it, or stop.
• If the shell refuses a step — a syntax error, or an unclosed quote you cancel at the continuation prompt — the step is recorded as failed and the agent is told the shell did not run it, so it can correct itself.

Taking over mid-run

If you click into the terminal and start typing while an agent is running, the agent pauses and holds its current step. When you return focus to the input bar — or switch to another tab or pane — it resumes from where it paused. A step that was waiting for your approval, including a file write, is still waiting for you, and a step that arrived while you were typing waits on the card instead of running. Pressing Esc stops the run entirely.

Related pages: Slash Commands Reference, Safety and Security, Runbooks.