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
- Modes
- Approving what it does
- Keys
- What you can type
- Slash commands
- Trust
- Background tasks and subagents
- MCP servers
- Memories
- The footer
- The line session
- If something goes wrong
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.
| Mode | Footer | What it does |
|---|---|---|
| ask (the default) | ? for shortcuts | Reads and searches without asking; asks before each edit and command. |
| auto | auto mode on | Edits and runs commands without asking. Risky commands, requests off this machine, saving a memory and connector tools that may change something still ask. |
| plan | plan mode on | Reads 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:
- Yes: this once.
- Yes, and don't ask again for that tool this session: not offered when there is a warning, because those are asked every time.
/clearforgets these. - No, and tell AstraCode what to do differently (Esc): stops the turn, so what you type next is the instruction. For a subagent's request it is just No, and refuses only that step.
Keys
| Key | What it does |
|---|---|
| Enter | Send. |
\ then Enter, Ctrl-J, Option-Enter or Alt-Enter | A new line. Shift-Enter too, in terminals that report it. |
| Esc | Stop the run and keep what it has done, or close a menu. Background tasks keep going. |
| Ctrl-C | Stop the run; with no run, clear the input; on an empty input, press twice within 1.5 seconds to leave. |
| Ctrl-D | Leave, when the input is empty. |
| Shift-Tab | Cycle ask, auto and plan. |
| Up, Down | Go through history, or move in a menu. |
| Ctrl-R | Search history; Ctrl-R again for the next match, Enter sends it, Tab puts it in the input. |
| Tab | Accept a completion in the / or @ menu. |
| Ctrl-O | Show or hide tools' full output. |
| Ctrl-T | Show or hide the todo list. |
| Ctrl-B | Send the agent or command running in the foreground to the background. |
| Ctrl-G | Edit the message in $VISUAL, $EDITOR or vi. |
| Ctrl-V | Paste an image from the clipboard (macOS only; elsewhere, mention the file with @). |
| Ctrl-L | Redraw 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 input | Show the keys. |
| 1 to 9 in a menu | Pick that item. |
What you can type
| Start with | What 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
| Command | What it does |
|---|---|
/help | Keys, commands, and your own commands and skills. |
/clear | Start a new conversation; also forgets this session's "don't ask again" answers. |
/compact | Summarise the conversation to free context. |
/context | How 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. |
/rewind | Go back to before one of the last nine messages, restoring The code and the conversation or The conversation only. |
/undo | Undo the last message: its edits, what its commands did, and the reply. |
/model | AstraOne (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. |
/plan | Switch to plan mode. |
/memory | List what it remembers about this project. /memory add <text> adds one; /memory rm <n> removes one. |
/init | Ask 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. |
/diff | The uncommitted changes (git diff HEAD). |
/tasks | Background agents, commands and monitors. /tasks <id> shows one, /tasks stop <id> stops one, /tasks stop-all stops them all. |
/agents | The agents it can start: built in and yours. |
/mcp | Your 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. |
/status | Version, folder, model mode, approval mode, theme and colour depth, gateway, and the session's id and message count. |
/theme | Choose the text style again, previewed as you move. |
/login | Sign in again, for example as another account, without leaving. |
/logout | Sign out and leave; the next start signs in again. |
/exit, /quit | Leave. |
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
- The agent can start subagents (built in: general-purpose, explore, plan and verify; or yours) and long commands in the background. The footer shows how many are running.
- When one ends, its report wakes the agent at the prompt, at most three times in a row without a message from you.
- Esc stops the turn but not the background. Leaving stops everything still running and says what it stopped.
- Your own agents come from
.astracode/agentsand.claude/agentsin the project,~/.astracode/agentsand~/.claude/agents, and--agentsfor one session.--agent <name>runs the whole session as one of them. See Subagents and background tasks. - A project's agent file that declares its own MCP servers asks before starting them, once per machine; the answer is kept in
agent-mcp.jsonin the config folder.
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 footer
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:
| Command | What it does |
|---|---|
/help | The commands. |
/clear | Start over. |
/trust | Trust 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-D | Leave. |
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
- The conversation exits straight away with code 1: the first run was not finished, or you answered No, exit to the trust question.
- Ctrl-V does nothing on Linux or Windows: image paste is macOS only; mention the file with
@. - `/mcp` says there are no servers: add them under
mcp.serversin the CLI's own settings file, not the editor's. - Everything else: CLI problems.
← AstraCode CLI Scripts and CI →
All documentation
Get started
Using the editor
- Tab completion
- Edit and ask about a selection
- Reviewing the agent's changes
- Git: commit messages, branch review and conflicts
- Dictation
- Layout, themes and the settings page
Agent
- Agent overview
- Agent, Plan, Ask and Debug
- Approvals and permissions
- Plan mode
- Debug mode
- Tools
- Browser tools
- How the agent checks its work
- Checkpoints and undo
- Running several agents at once
- Subagents and background tasks
- Remote agents in GitHub Actions
- Infrastructure as code
Context
Workspaces
Connectors
- Connectors (MCP servers)
- Connector configuration reference
- Use AstraCode from Claude, ChatGPT and other apps
Extending AstraCode
CLI
Account and usage
- Usage and limits
- Bring your own key
- What AstraCode sends and keeps
- Reporting a problem and getting help
Troubleshooting
- Troubleshooting
- Sign-in problems
- Install and update problems
- Chat panel problems
- Agent run problems
- Connector problems
- Dictation problems
- Usage, billing and network errors
- CLI problems