Docs › CLI › The conversation

The conversation

Work with the agent in a full-screen terminal session: keys, slash commands, modes, approvals, trust, background tasks, MCP servers and memories.

On this page

Run astracode-agent in a project folder and it opens a full-screen conversation there. Type a request and press Enter; the agent reads, edits and runs commands, asking first as your mode says, and shows each edit as a diff.

Terminal

astracode-agent                               # a new conversation in this folder
astracode-agent "why does the login test fail?" # start with a request
astracode-agent --continue                    # this folder's last conversation (-c)
astracode-agent --resume                      # choose one of the last nine (-r)
astracode-agent --cwd ../api                  # another folder

When you leave, it prints Resume this conversation with: astracode-agent --continue. Conversations are kept per folder in the CLI's config folder.

Modes

Shift-Tab cycles three modes. The footer shows which one is on.

ModeFooterWhat it does
ask (the default)? for shortcutsReads and searches without asking; asks before each edit and command.
autoauto mode onEdits and runs commands without asking. Risky commands, requests off this machine, saving a memory and connector tools that may change something still ask.
planplan mode onReads and writes a plan, then asks Ready to build the plan, with Yes, and let it edit without asking (auto), Yes, and ask before each edit (ask) or No, keep planning.

/plan switches to plan mode directly. An agent started with --agent that is a planning agent starts in plan mode.

Approving what it does

When the agent needs your say, it asks Allow AstraCode to do the action, with a warning above when the action is one that is asked about in every mode. Pick with the arrow keys and Enter, or the number:

Keys

KeyWhat it does
EnterSend.
\ then Enter, Ctrl-J, Option-Enter or Alt-EnterA new line. Shift-Enter too, in terminals that report it.
EscStop the run and keep what it has done, or close a menu. Background tasks keep going.
Ctrl-CStop the run; with no run, clear the input; on an empty input, press twice within 1.5 seconds to leave.
Ctrl-DLeave, when the input is empty.
Shift-TabCycle ask, auto and plan.
Up, DownGo through history, or move in a menu.
Ctrl-RSearch history; Ctrl-R again for the next match, Enter sends it, Tab puts it in the input.
TabAccept a completion in the / or @ menu.
Ctrl-OShow or hide tools' full output.
Ctrl-TShow or hide the todo list.
Ctrl-BSend the agent or command running in the foreground to the background.
Ctrl-GEdit the message in $VISUAL, $EDITOR or vi.
Ctrl-VPaste an image from the clipboard (macOS only; elsewhere, mention the file with @).
Ctrl-LRedraw the screen.
Ctrl-A, Ctrl-E, Ctrl-U, Ctrl-K, Ctrl-W, Ctrl-Y, Alt-B, Alt-F, Alt-Backspace, Ctrl-_Line editing as in a shell: start, end, delete to start, delete to end, delete a word, paste it back, word back, word forward, delete a word back, undo an edit.
? on an empty inputShow the keys.
1 to 9 in a menuPick that item.

What you can type

Start withWhat it does
/A slash command (below), or one of your commands and skills.
@Mention a file; it is attached. A .png, .jpg, .gif or .webp is sent as an image.
!Run the rest in your shell ($SHELL, else /bin/sh), for up to 120 seconds. The last 8,000 characters of its output go with your next message.
#Save the rest as a memory for this project. ## is sent as ordinary text.

Slash commands

CommandWhat it does
/helpKeys, commands, and your own commands and skills.
/clearStart a new conversation; also forgets this session's "don't ask again" answers.
/compactSummarise the conversation to free context.
/contextHow much of the context is used; suggests /compact above 60%.
/resume [id or latest]Pick up one of this folder's conversations; with no argument, choose from the last nine.
/rewindGo back to before one of the last nine messages, restoring The code and the conversation or The conversation only.
/undoUndo the last message: its edits, what its commands did, and the reply.
/modelAstraOne (the default, the best result for the cost) or AstraOne, most capable. If your plan does not include one, it says so and keeps the current one.
/planSwitch to plan mode.
/memoryList what it remembers about this project. /memory add <text> adds one; /memory rm <n> removes one.
/initAsk the agent to write, or improve, an AGENTS.md for this repository from its code and configuration.
/review [branch]Review this branch's changes, as astracode-agent review does.
/diffThe uncommitted changes (git diff HEAD).
/tasksBackground agents, commands and monitors. /tasks <id> shows one, /tasks stop <id> stops one, /tasks stop-all stops them all.
/agentsThe agents it can start: built in and yours.
/mcpYour MCP servers, each with its tool count or why it failed.
/export [file]Save the conversation as Markdown; by default astracode-conversation-YYYY-MM-DD.md in this folder.
/statusVersion, folder, model mode, approval mode, theme and colour depth, gateway, and the session's id and message count.
/themeChoose the text style again, previewed as you move.
/loginSign in again, for example as another account, without leaving.
/logoutSign out and leave; the next start signs in again.
/exit, /quitLeave.

An unknown command says Unknown command /x. /help lists them. There is no /trust here: this session only ever runs in a folder you trusted (see below).

Trust

The full-screen conversation asks once per folder whether you trust it, and does not open without a yes. Trusted, the agent may change files and run commands there, and the folder's rules, hooks, skills, commands and agents load. Your answer is kept in trustedFolders in the CLI's settings file. --trust or ASTRACODE_TRUST=1 answers the question for one run without remembering it.

To use the agent in a folder you do not want to trust, pipe into it (see the line session below): there the folder starts read-only, and /trust trusts it later. More on what trust allows: Workspace trust.

Background tasks and subagents

MCP servers

The conversation starts the servers under mcp.servers in the CLI's settings file (~/.config/astracode/settings.json by default), and installed plugins' servers you approved. The file is read from your home only, never from the project, because mcp.servers names commands that run on start:

~/.config/astracode/settings.json

{
  "mcp.servers": [
    { "id": "memory", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-memory"] }
  ]
}

The entry shape is the editor's; see the configuration reference. The CLI cannot sign in to a remote server through a browser, and reads no project MCP file. -p, acp, review and the line session start no servers from this file.

Memories

A memory is a note the agent is given in every later session in this project. Add one with # note or /memory add, list them with /memory, remove one with /memory rm and its number. The agent can propose one too, and always asks first. They are kept in ~/.astracode/memories, shared with the editor. Memories are only used in the full-screen conversation. See Memories.

The bottom line shows the mode, the agent the session runs as, how many background tasks are running, the model mode when it is not the default, and how much of the context is used, coloured from 50% and red from 80%.

The line session

When stdin or stdout is not a terminal, for example when you pipe into astracode-agent, it runs a plain line-at-a-time session instead. It skips the first run and goes by the trusted list: an untrusted folder starts read-only and says so, naming what it did not load. Commands there:

CommandWhat it does
/helpThe commands.
/clearStart over.
/trustTrust this folder, remember it, and load its rules, hooks, skills, commands and agents from the next request.
/plugin ...The plugin commands. A sensitive option is not typed here, where it would be echoed.
/exit, /quit, Ctrl-DLeave.

Approvals are answered by typing y, n or a (always, for that tool this session). Ctrl-C stops the run in progress.

If something goes wrong

← AstraCode CLI Scripts and CI →

All documentation

Get started

Using the editor

Agent

Context

Workspaces

Connectors

Extending AstraCode

CLI

Account and usage

Troubleshooting

Reference