Skip to main content

Create, open, import, and manage recent projects

When to use this guide​

Use this guide to start a project, open an existing project from disk, clone a team repository, or organize App Hub's recent-project list.

Before you start​

  • Complete these tasks in the desktop App Hub. App Hub does not rename projects, delete workspaces from disk, or open runtime pages.
  • A valid workspace root must contain exactly one *.the project file. Open project accepts that file, not a directory.
  • Importing from Git requires a system Git installation; creating and opening local projects do not.
  • Before moving or deleting a workspace, confirm that a recoverable Git commit or backup exists.

Create a project​

  1. Select New project in the App Hub sidebar.
  2. Enter the App name.
  3. Under Create in, choose a parent directory. Theseus creates a new folder named after the App inside it.
  4. Under Modules, select Motion and Vision only when needed. Leaving both unchecked creates a standard project. Selecting a module creates initial configuration without assuming site hardware.
  5. Select Create project. Theseus creates the complete project and opens the editor.

A new project does not initialize Git automatically. When version control is needed, select Initialize repository in the editor's Versions panel. Configure a remote repository later according to the team's workflow.

Open a local project​

  1. Select Open project in the App Hub sidebar. The system file picker opens immediately.
  2. Go to the workspace root and select its *.the file.
  3. Wait for the editor window to appear. App Hub closes after the editor is shown and returns when the editor closes.

Theseus uses the original directory and does not copy or move it. Explorer, Finder, or a command-line file open can also pass a .the file to Theseus; a successful open updates the same recent-project list.

Import from Git​

The repository root must be a complete Theseus project. Import does not guess a project inside subdirectories.

  1. Select Import project in the App Hub sidebar.
  2. If the page shows Git not found, select Download Git to install Git for Windows, then select Recheck.
  3. Enter the Repository URL. Fill in Branch when a specific branch is required; leave it blank to use the repository's default branch.
  4. Under Clone to, choose a parent directory. Theseus creates a workspace folder named after the imported App there.
  5. Select Clone and open, then wait for the status to move from cloning to opening the project.
  6. If authentication fails, enter the username and access token in the prompt and retry. Do not put credentials in the repository URL. Enable Save credentials to system Git only when the team's credential policy permits it.

After a successful import, the editor's Versions panel should show the expected branch and remote.

Use the recent-project list​

App Hub records only .the paths that were opened successfully and sorts them by last-opened time. You can search, switch between grid and list views, and reopen a project in any of these ways:

  • Double-click its card or list row.
  • Select it and press Enter.
  • Use the card's Open editor action.
  • Select Open editor from its context menu.

To organize the list, select Remove from recent projects from the project's context menu. This removes only the App Hub record and never changes files on disk. Opening the same .the later returns it to the top of the list.

Wait for package preparation​

Creation, local open, and Git import establish the workspace and editor window; App Hub does not restore packages. After the editor opens, Theseus asynchronously prepares the versions locked by the project.

During preparation:

  • Files, Source, Versions, and Settings remain available, and ordinary source can be viewed, edited, and saved.
  • Design, Page Preview, Flow, and editing features that depend on packages show a waiting state and load automatically when preparation finishes.
  • When a download is needed, a lower-right task notification shows the current stage and progress. If the required content is already on this device, preparation may finish quickly without showing it.

If preparation fails, the waiting view retains the specific error and provides Retry and Open package settings. Do not hide an error by repeatedly closing the project, and do not hand the App off to a site while preparation is failing.

Manage packages in Settings​

Open Settings → Packages:

  • Installed shows the packages required by the current App, their installed versions, and explicit problem states such as missing lock, version mismatch, missing content, or invalid content.
  • Source shows content currently available from the selected package source. Use Install, Update, or Change version as appropriate; Theseus does not silently substitute another version.
  • Required packages cannot be removed. Optional packages expose Remove.
  • Switch to Sources to enable or disable sources. The built-in Theseus source needs no sign-in; sign in to the correct Qixin account before creating or using personal or organization sources.

Theseus manages package versions automatically, so no additional tool is required. Package changes are project changes; when committing to a shared repository, make sure the complete project change is included in the same commit.

What success looks like​

  • The new project opens normally in the editor.
  • A local open keeps the original path and moves the project to the top of the recent list.
  • After Git import, Versions shows the correct branch and remote.
  • After package preparation succeeds, Design, Page Preview, Flow, and semantic features no longer show a waiting state or error.
  • Removing a project from the recent list leaves its directory unchanged.

Common issues​

The file picker shows the directory, but it cannot be opened directly​

This is expected. Open the workspace root and select the exact .the file. Do not select the directory or keep more than one .the in the same root.

Package preparation fails after opening​

Keep the original error and select Retry first. If it fails again, open Settings → Packages to inspect the problem state, then verify network access, Qixin sign-in, package-source availability, and that the project came from the correct commit. When project package information is invalid, restore the correct version from source control instead of guessing.

A package source is unavailable​

The Installed view remains useful for checking local state. When a download or version change is required, verify the Qixin account, organization membership, and source reachability, then select Refresh in the Source view.

Git import keeps failing authentication​

Confirm that the repository URL and branch exist, that the token has read access, and retry through the authentication prompt. Do not embed a username or token in the URL.

How AI can help​

AI Command Center operates only on the App that is already open. It cannot replace App Hub for creating, opening, importing, or managing recent projects. After opening the editor, try:

Read-only inspect the current App's workspace structure, package status, and latest Build problems. List anything that blocks editing or running, with a human verification order. Do not modify files.

Do not send Git credentials, tokens embedded in private repository URLs, or package-source credentials to AI.

What a person must confirm​

  • The App name, workspace path, Git repository, and branch belong to the correct customer and project.
  • Personal or organization package-source use complies with authorization and delivery requirements.
  • A recoverable commit or backup exists before manually moving or deleting a workspace from disk.
  • An App with failed preparation does not proceed to equipment debugging or production handoff.