# Terminal

The Terminal tab is where you work with the coding agent. You describe what you want, and the agent reads and changes the files in your project, runs commands and reports back.

#	Control	What it does
1	Project directory	The folder the agent works in: `/workspace` itself or one of your projects. New terminals start here, and Sessions lists the conversations held in this directory.
2	Terminals	The terminals open in your workspace, each labelled with its conversation, project and process ID (PID). Switch between them here, or choose New TUI to open another one. Each keeps running while you look at another terminal or another tab.
3	Sessions	Opens a terminal on an earlier conversation from the selected project directory. Continue last session picks up the most recent one.
4	Restart	Ends the current terminal and starts it again the same way it was opened. Use it when a terminal shows Ended or Error: terminals are never restarted automatically. Your conversations are kept.
5	Disconnect	Ends the current terminal, after asking you to confirm. The conversation is kept, and you can reopen it from Sessions.
6	Full window	Expands the terminal to fill the browser window. Click it again to return.

Next to Restart, the status shows the state of the current terminal: Connected, Connecting…, Ended or Error. If the connection drops, your browser reconnects by itself. When no terminal is open, the tab shows a New terminal button instead, which starts the agent in the selected project directory.

# Inside the terminal

#	Element	What it is
7	Session tabs	The conversations open in this terminal. + New session starts a fresh one.
8	Prompt	Where you type your request.
9	Agent and model	The active agent (here Build), the model it is using and the provider serving it (Phoeniqs MaaS).
10	Shortcuts	The two shortcuts below.
11	Connected tools	How many tools (MCP servers) the agent is connected to. Type `/mcps` to list them.

# Keyboard shortcuts

Shortcut	What it does
`shift` + `tab`	Switches between the Build and Plan agents
`ctrl` + `p`	Opens the list of commands

# Build and Plan

The terminal comes with two agents you switch between with shift + tab:

Build, the default unless your company settings name another one. It changes files and runs commands, within the permissions it is configured with.
Plan, read-only. It explores the codebase and plans the work without changing anything. Use it to agree on an approach before letting Build implement it.

Your company settings can add agents, choose a different default, and require the agent to ask before it edits a file or runs a command. The full list of agents is under Settings → Agents. The model a new session starts with is set under Settings → Providers & Models.

# Adding files to a prompt

Paste a file into the terminal or drag it in, and it is uploaded to your workspace with its path added to the prompt. Images and PDFs appear as [Image 1] or [PDF 1]. Text and data files, and Word, Excel and PowerPoint documents, are added as a path the agent opens. Each file can be up to 10 MB.

Attached files are stored in a hidden .attachments folder in your workspace. Files older than 24 hours are removed the next time you attach one, so move anything you want to keep into a project.

# Leaving and coming back

Closing the browser tab, reloading the page or moving to another tab ends nothing. Your terminals keep running in the workspace, so the agent carries on with a long task while your laptop is closed. The next time you open the workspace, the running terminals are picked up again and listed under Terminals. Only Disconnect ends a terminal.

Conversations are stored on the workspace's persistent volume, so they also survive a restart, an upgrade and a redeployment of the workspace. Reopen them from Sessions. If your history looks empty after importing a workspace archive, the import replaced it with an older export; see Workspace data and restarts.

# What the agent can reach

Inside your workspace the agent works with:

Your project files, the checkouts under /workspace/<project>/, read and write. See Projects.
Git, acting as the credential for that host in Settings → Credentials. Commits and pushes carry that identity.
Installed tools, including git, svn, node, python and the codegraph command.
Code intelligence. On projects with CodeGraph enabled, the agent can answer structural questions about the codebase without reading every file. See CodeGraph.
The browser, a real web browser it can drive while you watch. See Browser.
Further tools you connect under Settings → MCP Servers.

# Running commands yourself

For a plain shell, open the integrated terminal in the Editor tab. It runs as the same user as the agent and sees exactly the same files, so there is no handover between your work and the agent's. A dev server you start there shows up in the Preview tab.

# Good to know

One disk, two writers. The agent and the editor share one filesystem. Holding a file open with unsaved changes while the agent rewrites it can overwrite one set of edits.
Restart terminals after an import. After importing a workspace archive, open terminals keep their view of the disk from before the import until you restart them.

Quick Start, your first agent task

../quick-start/

The editor

../editor/

Preview

../preview/

ai coding phoeniqs ai build terminal opencode agents sessions