Skip to main content

Create, open, import, and manage 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 project list.

Before you start​

  • Complete these tasks in the desktop App Hub. A project's context menu can rename its list label, but it does not rename the directory, .the file, or project document. App Hub does not delete workspaces from disk.
  • A valid project root must contain exactly one *.the file. Use Open project to select a project file, or Open folder to select a project directory or an ordinary folder.
  • 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.
  4. Select Create project. Theseus creates <App name>/<App name>.the and the complete blank workspace, then opens the editor. New projects start with no enabled modules; enable them later in Settings when needed.

The CLI uses the same SDK creation path. From the intended parent directory, run theseus new <appName> to create exactly ./<appName>/<appName>.the; there is no parent-directory or project-filename option.

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 or File menu, or press Cmd/Ctrl+O.
  2. Select the *.the project file; its root directory must contain exactly one valid project file.
  3. Theseus registers the project and opens its editor directly.

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. Newly opened projects appear at the top of their section; reopening a listed project also moves it to the top.

Opening a project editor, selecting a project in App Hub, or opening one of its conversations prepares the page editing environment in the background. You can continue chatting while preparation runs, before opening a page.

Open an ordinary folder​

Select Open folder in App Hub and choose a local directory to start an AI conversation there. Folders share the project list, including aliases, pins, ordering, and conversation restoration.

Without a valid .the, you can chat, work with files, execute commands, and use Git. Build, Run, and Open editor are absent, and Theseus project tools and bundled engineering workflows are unavailable. Recognition checks only the selected directory root. Multiple or invalid .the files display an error while the directory remains available for chat.

Import from Git​

Ordinary Git repositories can also be imported without a .the file. Theseus does not search subdirectories for projects.

  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 repository there.
  5. Select Clone and open, then wait for cloning to finish and the directory to be selected in App Hub.
  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 import, start an AI conversation and check the branch in task details. Open editor is available only when the directory contains a valid .the project.

Manage projects from the sidebar​

Resizable dividers in App Hub and the editor highlight on hover and while dragging without changing thickness. Drag them to resize adjacent panels. Mouse hit areas are 4px wide; panel dividers retain larger touch targets.

The top sidebar actions—New chat, New project, Open project, Open folder, Import project, and Learn—use compact spacing to leave more room for projects and conversations below.

Hover over a project or conversation to view its details. In the dark theme, these cards use a lighter charcoal surface, a thin gray border, and a subtle shadow. The entire project row switches its highlight immediately, without a color fade, and stays highlighted when the pointer moves over its trailing actions or those actions receive keyboard focus.

In the dark theme, the sidebar uses a charcoal background, a lighter gray selection, and soft gray text. Group labels and supporting information use a muted text tone. Conversation hover and selection backgrounds span the full row, including the left indentation, while the text stays indented.

App Hub uses the current theme’s background with a static, muted Theseus logo watermark while restoring the last viewed conversation at startup. With no saved location or a deleted conversation, it opens a new conversation. Manage projects from the sidebar and search names or paths in the heading's project picker.

Expand a project in the sidebar to see its conversations, or use New chat beside it to start a task. For the full editor, right-click a project and select Open editor, or use the same action in the project's information card or the current conversation's toolbar.

If a project folder is deleted or moved, its entry stays in the sidebar with its usual folder icon and a dimmed appearance. The New chat button beside it is disabled and shows “This project folder was deleted or moved” on hover. You can still expand the project and open existing conversations; the conversation list keeps its normal appearance and contents.

For each entry, App Hub records a display name, a project-file or directory location, and its pin state. It records no opened-at timestamp. From now on, creating, opening, or importing a project from Git moves it to the top of its section. Other entries keep their relative order; existing lists are not reordered in bulk.

Drag projects to arrange them. Expand a project to drag its AI sessions into the preferred order. While dragging, rows stay in place, the dragged entry dims, and a thin line marks the insertion point. A compact floating preview follows the pointer with the project icon and name or the conversation title. Other entries do not show hover highlights, row actions, or tooltip cards during dragging. The entry moves only when you release it. Project order and each project's session order are persisted and do not follow modification time.

Select Rename project from a project's context menu to change only its list label. The directory, .the filename, and project document are unchanged. Remove project removes only the App Hub record and never changes files on disk; opening the same .the later adds it as a new entry at the top.

In the App Hub sidebar, hover over a project and select More project actions, or right-click the project, then select Pin. Pinned projects move to the Pinned section; select Unpin from the same menu to return one to the regular project section. Pinning changes only the grouping in this device's project list and never modifies project files.

Hovering over a project opens an information card on its right with the project name, current conversation and activity status, workspace path, and an Open editor action. If a collapsed project still has a running, queued, or input-blocked conversation, its row keeps an activity indicator on the right.

Wait for package preparation​

Open folder and Git import register a directory in App Hub; New project and Open project open an editor. Selecting a valid project or opening its editor prepares the versions locked by the project in the background. Once ready, switching back to the project or opening its editor reuses the prepared environment during the same Theseus run; dependency changes trigger preparation again.

During preparation:

  • Files, Source, Versions, and Settings remain available, and ordinary source can be viewed, edited, and saved.
  • Design, Flow, and editing features that depend on packages show a waiting state and load automatically when preparation finishes.

If preparation fails, one short-lived lower-right notification appears and can be dismissed immediately. The waiting view retains the exact Restore error and provides Retry. Do not hide an error by repeatedly closing the project, and do not hand the App off to a site while preparation is failing.

Set language and appearance​

Open System Settings from App Hub:

  • General: choose the interface language and manage account, startup, and update settings.
  • Appearance: choose the theme and interface font.

Open the interface font list and select a font installed on this computer. The choice is saved immediately and applied to all open App Hub, Editor, and AI panels. Select System default to restore the default font. Missing fonts or characters use the system font; no fonts are downloaded. Code fonts and runtime pages are unchanged.

Manage packages in Settings​

Open Settings → Packages:

  • Project dependencies only lists packages and versions declared by the current App. It does not preflight the lock or local content; Restore runs the operation directly and reports its failure unchanged.
  • Registry searches the fixed Theseus Registry by package name or namespace and lets you add an explicit version.
  • Check updates only discovers available versions. Update all and per-package Update download and verify content before committing the project dependency and locked version together.
  • Remove deletes only the current App dependency and lock entry; shared local content remains available to other Apps.

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.

The same operations are available from the project directory through the CLI:

theseus package search <query> [--prerelease]
theseus package list [--outdated]
theseus package add <namespace.package>[@version] [--prerelease]
theseus package update [<namespace.package>[@version] ...] [--prerelease] [--dry-run]
theseus package remove <namespace.package>
theseus package restore [--locked]

Add and update select the latest stable release when no version is provided. --locked never creates or changes the lock and fails when the project and lock differ.

What success looks like​

  • The new project opens normally in the editor.
  • A local open keeps the original path; created or opened projects appear at the top of their section, while listed projects keep their display name.
  • After Git import, Versions shows the correct branch and remote.
  • After package preparation succeeds, Design, Flow, and semantic features no longer show a waiting state or error.
  • Renaming a list label or removing a project leaves its directory, .the file, and project document unchanged.

Common issues​

Project actions are missing after opening a directory​

Select the workspace root containing exactly one valid .the file. Theseus does not search child directories; multiple or invalid project files show a recognition error.

Package preparation fails after opening​

Read the exact Restore error retained by the waiting view and select Retry. If it fails again, follow that error to check network access, Theseus Registry availability, the project file, or dependency lock. When project or dependency-lock data is invalid, restore the correct version from source control instead of guessing.

The Theseus Registry is unavailable​

The Project dependencies view remains available offline for project declarations. Search, update checks, add, and update require the fixed Theseus Registry. Locked restore stays offline when all required content is already installed.

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 the project list. After opening the editor, try:

Read-only inspect the current App's workspace structure, latest package-preparation error, 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 or tokens embedded in private repository URLs to AI.

What a person must confirm​

  • The App name, workspace path, Git repository, and branch belong to the correct customer and project.
  • Package ids, versions, and the corresponding project-metadata changes belong to the same intended change.
  • 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.