Give your app a home

7 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.

• 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 project instructions and skills
• Return to the same project tomorrow
• Keep a workspace useful as the app grows
• Workspace, project and conversation menus
• Project settings sections

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.

Open an isolated worktree when two changes need independent checkouts; simply opening two chats keeps them on the same files unless you choose isolation. 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. Merged or removed worktrees no longer appear among the active badges.

Browsing another checkout updates Files, Source Control and the context for new project terminals. 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. Existing terminal sessions retain their working directories.

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 project instructions and skills#

Use project settings to save instructions for the work in that folder and choose skills from your personal skills library. 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.

Review the selection for each project 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#

Project settings sections#

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