Give your app a home

11 minute read · Projects & Git

Your project is the folder that contains your app. A workspace groups projects; a conversation holds the instructions and decisions around a piece of work. For a first app, one workspace, one project and one chat are enough.

• Use the workspace rail
• Open directly from search
• Choose how the project starts
• Keep the conversation attached to the right work
• Switch the project you are looking at
• Set workspace instructions and skills
• Return to the same project tomorrow
• Keep a workspace useful as the app grows
• Workspace, project and conversation menus
• Workspace settings sections
• Add existing folders through chat

Use the workspace rail#

The narrow rail on the left holds your workspaces. Hover an icon to see its full name, project count and current activity. Select it to return to that workspace. Switching does not reorder the icons. Drag them into the order you prefer, or right-click an icon for workspace actions. The selected workspace is marked; running work adds a coloured activity indicator, with a separate attention state when input is needed.

The activity count belongs to that workspace. A completed task you have not seen leaves an Unread result indicator; open its workspace to acknowledge it. Unread results in hidden workspaces also appear on More workspaces.

Right-click a workspace icon and choose Choose workspace icon… to use your own logo or picture. PNG, JPG and WebP files up to 8 MB are supported. Vortex crops the centre to a square and saves a small image with the workspace. Change workspace icon… replaces it; Remove workspace icon restores the initials. The full-name tooltip and activity indicator remain available. The image follows the workspace through normal account synchronization. In the browser demo it stays in memory and Reset removes it.

Use Workspace background in the same menu to choose a preset colour, Custom color…, Transparent or Automatic. The background is saved independently of the picture and also colours the initials when there is no image. Changing or removing a picture keeps the background; Automatic restores the theme colour. Opaque pixels in an uploaded picture keep their own colour. The selected marker and activity badge remain visible.

You can also ask the agent: “Use this picture as the icon for my workspace.” Attach a PNG/JPG, use a generated image already in the conversation, or point to an image inside the selected project. The agent can set, replace or remove the icon directly and check the saved result. You can also ask “Make this workspace’s icon background dark blue” or “Make its background transparent”; this keeps the picture unless you ask to change it too. If several workspaces have the same name, identify the intended one first. Creating a new picture is a separate image-generation action; changing the icon uses the supplied image.

The rail shows as many workspaces as fit above +. Use More workspaces to open the remaining entries and arrange the full list. You can keep the workspaces you use most near the top without a long scrolling rail. + creates a workspace. Home and Chats have their own fixed icons above the list. The Tools icon sits below Chats and above the workspaces; select it to open Database, Terminal, Files, API, Mail or Signals. Tools remain reachable when the project/chat sidebar is hidden.

Open directly from search#

Open Vortex Search → Workspaces to find a workspace by its name or an included project name and return to its saved location. This category lists workspaces, not one entry per project folder. From inside a project, the same search can open a saved database, FTP/SFTP connection, SSH host or Signals app over the current chat. See search and keyboard controls.

Choose how the project starts#

Give the workspace a recognizable name, such as Personal projects, and the project a specific app name. Moving a project between workspaces changes its organization; it does not relocate the physical checkout. Reordering the sidebar also leaves the folder untouched. A worktree created for a chat belongs to its parent project while keeping its own branch and directory.

Keep the conversation attached to the right work#

Open the project before starting a task that should change it. If a conversation can access several projects, tell the agent which one is the target and inspect the selected project context. For example: “In Small Stories, add an article editor. Leave the shared component library unchanged.” Selecting a workspace is not blanket permission to edit every folder on the computer.

On the new-chat screen, the project name defaults to the active project. Click that name to choose a different available project in the workspace before sending the first message. The starting project gives the chat its initial context; it does not move an existing conversation to another checkout.

A standalone conversation can later be bound to a real project. Its conversation history stays available. Plain chats have no project settings. Open or attach the intended project before configuring its folder, instructions or selected skills.

Two chats in the same project can work in the same checkout and edit the same files. Open an isolated worktree when changes need independent branches and checkouts. Use Chat menu → Project & worktree… to choose a project's main folder or an existing worktree, or explicitly create one. See parallel chats and worktrees for the complete flow.

Switch the project you are looking at#

Open Files or Source Control. Directly below the panel's heading, inside the card, the badges show this workspace's project folders and active, unmerged worktrees. Choose a badge to browse that checkout. Selecting a project in the left sidebar changes the same active project.

Project colours are assigned automatically from their names and coordinated within the workspace. The sidebar and panel badges use the same identity colour, adapted to your chosen palette and light or dark theme. Worktrees have their own colour and fork icon; colour alone is not the selection indicator, the raised segment is. Merged or removed worktrees no longer appear among the active badges.

Browsing another checkout updates Files and Source Control. When adding a terminal, choose its project separately from the current workspace. It does not change an existing chat's starting folder or redirect a running agent. To change where the next chat message starts, use that chat's Project & worktree… menu. Terminal tabs are shared only within this workspace. Another workspace shows its own tabs; switching back restores the existing sessions, which retain their working directories and running commands. Whether the project terminal is open, and an open Workspace settings or Runtime dialog, are also remembered for each workspace.

Resize the tool panel, editor or terminal once: those dimensions carry across projects and worktrees in the same workspace and window on this device. Another workspace keeps its own sizes. Open files, unsaved drafts and terminal sessions keep their project context; reusing panel dimensions does not move them into another checkout.

Set workspace instructions and skills#

Open Workspace settings → Instructions & skills to save instructions for every project and chat in the workspace and choose skills from your personal skills library. Add Context files for a particular project, such as its conventions document. Instructions can explain the app's conventions, the checks it needs and the scope an agent should preserve. Selected skills add relevant reusable guidance; they do not grant permissions or supply missing tools. See Workspace settings.

Review the selection for the workspace rather than enabling every skill by default. Keep secrets in the saved connection settings instead of instructions. See personal skills and settings for the library and agent permissions for action boundaries.

Return to the same project tomorrow#

Reopen the existing entry, confirm its local folder and use Start app if the process has stopped. On another device, bind the synchronized project to that device's checkout. If the path is missing, choose or clone the correct folder instead of creating a duplicate project record. Preview and parallel work explain the next steps.

Keep a workspace useful as the app grows#

Group related projects together, such as a customer website and its internal dashboard. Give each chat a specific result: “Article search” is easier to revisit than several entries called “New chat.” Pin ongoing work and archive conversations you want to retain without keeping them prominent. Moving or reordering entries changes their organization, not the project files.

When work crosses projects, name both the responsibility and the boundary: “Read the API response in the server project, then update only the dashboard to match it.” Use linked tasks for a separate project conversation that needs its own instructions and result. Check both sides of the interaction before calling the change complete.

A missing folder, a stopped process and a locked Vault need different fixes. Choose the correct checkout for a missing path, use Start app for a prepared project whose process has stopped, and unlock the account's existing Vault for encrypted cloud data. Do not delete and recreate the workspace to clear one of those errors. Your saved organization, chats and local checkout are separate pieces of the work.

Workspace, project and conversation menus#

Workspace settings sections#

For a renamed local checkout, change its folder binding under Local app and verify files and startup. Do not assume a cloud-synchronized project can use another computer's absolute folder path. See device folders and sync.

Add existing folders through chat#

Ask “Add this existing folder as a workspace” and provide its path, or name an existing workspace and the folders to add. Vortex registers those folders without moving files or scaffolding over them. The agent verifies the saved entry. Added projects become available to agent work on the next turn; registration does not expand the active run's file permissions.

Use workspace folders in the left rail to group related workspace icons. Drag one workspace onto another to create a group, expand or collapse it, and use its menu to manage the grouping. Grouping changes navigation, not the locations of the project folders.

Play and Preview each let you choose a project from the current workspace. Their selection is separate from the conversation's working context. Switching back restores the relevant pages; non-web projects show only applicable controls. See runtime and Preview.

For comparison with a project outside this workspace, add a read-only workspace reference. For an existing conversation, ask to associate it with a project: the change is applied after active and queued work finish, and a pending choice can be cancelled.