Create workspace view showing project selection, repository list, and task input
A workspace is a host-side folder plus a Git branch where you work with Codex. Each workspace can include one or more repositories and supports multiple conversation threads. Workspaces run on the selected registered host. The host owns the workspace folder, Git worktree, terminal, Codex process, and preview/dev-server access.

​
What Happens When You Create a Workspace

Understanding what happens behind the scenes helps you work more effectively:
1

Host worktree is created

Jaidu asks the selected host to create a git worktree - a separate working directory with its own branch. This keeps your changes isolated from your main codebase. Your original repository remains untouched.
2

Working branch is created

A new branch is created based on your target branch (e.g., main). The branch name is generated from your branch prefix settings and task name.
3

Codex thread starts

Codex is ready to receive your instructions. It can read files, make changes, and run commands within your workspace on the selected host.
4

Setup scripts run (if configured)

If your repository has setup scripts configured (e.g., npm install), they run automatically to prepare the environment.
Where do workspaces live? Worktrees are created on the selected host. You can configure the workspace directory in Settings → General.

​
Creating a New Workspace

1

Open the Create View

Click the + button at the top of the workspace sidebar, or use the command bar (Cmd/Ctrl + K) and select New Workspace.
Workspace sidebar showing the plus button for creating new workspaces
2

Select a Project

Choose a project from the Project dropdown in the right panel. Projects group related repositories together.
Project dropdown showing selected project
If you haven’t created a project yet, see Creating a New Project below.
3

Add Repositories

Repository selection showing selected repo with branch dropdown and list of available repositories
Select which repositories to include in your workspace:
  • Recent repositories - Click any repo from the list to add it
  • Browse repos on disk - Find repositories not in the recent list
  • Create new repo on disk - Initialise a new git repository
You can add multiple repositories to a single workspace if your task spans multiple codebases. Each repository maintains independent git state.
4

Set Target Branches

For each selected repository, set the target branch - this is the branch your changes will eventually be merged into (e.g., main or develop).Click the branch dropdown next to each repository to change the target branch.
Target branch vs Working branch - what’s the difference?
  • Target branch = Where your changes will eventually be merged (e.g., main). You set this.
  • Working branch = Where your changes are made. Auto-created from target using your branch prefix settings.
Your changes are made on the working branch and don’t affect the target until you create and merge a PR.
5

Describe Your Task

In the chat input at the bottom, describe what you want to accomplish. Be specific about:
  • What feature or fix you need
  • Any constraints or requirements
  • Files or areas of the codebase to focus on
Clear, detailed task descriptions help Codex understand your requirements and produce better results.
6

Select a Codex Configuration

Choose which Codex configuration to use for the workspace. Available options depend on the variants you have configured.
See Agent Configurations for details on configuring Codex variants.
7

Create the Workspace

Click Create to start the workspace. Codex will begin working on your task immediately.

​
Creating a New Project

If you need to create a new project before setting up your workspace:
1

Open the Project Dropdown

In the create workspace view, click the Project dropdown.
Project dropdown showing Create new project option and list of existing projects
2

Select Create New Project

Click + Create new project at the top of the dropdown list.
3

Enter Project Details

Create Project dialog with name field
Enter a name for your project and click Create.
4

Continue with Workspace Creation

Your new project is automatically selected. Continue adding repositories and configuring your workspace.
After creating a project, you can configure additional settings like setup scripts, dev server scripts, and cleanup scripts in the project settings. See Projects & Repositories for more details.

​
Workspace Settings

Once a workspace is created, you can configure additional settings:

​
Working Branch

The workspace automatically creates a working branch for your changes. You can view and change this in the Git section of the details sidebar.

​
Dev Server

If your project has a dev server script configured, you can start it using:
  • The Play icon () in the context bar
  • The command bar: Cmd/Ctrl + K → Start Dev Server
Configure dev server scripts in your project settings. See Projects & Repositories for setup instructions.

​
Workspace Notes

Use the Notes section in the details sidebar to document important information about the workspace - requirements, decisions, or anything you want to remember.

​
Fork Branch From A Workspace

Use Fork Branch when you want to continue from the current workspace state in a new isolated workspace.
  1. Open a non-Main Chat workspace.
  2. Open the command bar (Cmd/Ctrl + K).
  3. Go to Workspace Actions.
  4. Select Fork Branch.
If the workspace has uncommitted or untracked changes, Jaidu asks whether to create a local checkpoint commit first. The fork starts from that commit boundary. The child workspace:
  • uses the same repositories as the parent workspace;
  • sets each repository target branch to the parent workspace branch;
  • records branch lineage so the Branch Graph can show the parent/child relationship;
  • starts with its own fresh thread history in a new host-side folder/worktree.
Branch/fork is a workspace operation. It is not available from Main Chat because Main Chat is bound to the project root and does not create a temporary branch by itself.

​
Archiving Workspaces

When you’re done with a workspace, archive it to keep your workspace list clean: From the navbar:
  • Click the Archive button () in the top left of the navbar
From the command bar:
  1. Press Cmd/Ctrl + K
  2. Go to Workspace Actions → Archive
Archived workspaces can be viewed by clicking View Archive at the bottom of the sidebar.
Use the Pin feature to keep important active workspaces at the top of your list.

​
Troubleshooting

Possible causes:
  • The repository hasn’t been added to a project yet
  • The folder isn’t a git repository (no .git folder)
  • The path isn’t accessible
Solutions:
  1. Click Browse repos on disk to manually locate the repository
  2. Ensure the folder contains a .git directory
  3. Check that jaidu-agent has permission to access the folder on the selected host
Possible causes:
  • Git worktree creation failed (usually due to uncommitted changes in the original repo)
  • Branch name conflict
  • Disk space issues
Solutions:
  1. Commit or stash any uncommitted changes in your original repository
  2. Try a different target branch
  3. Check available disk space (worktrees require space for a full copy of tracked files)
Possible causes:
  • Codex is not installed or configured
  • API key issues
  • Network connectivity problems
Solutions:
  1. Check that Codex is installed: run the CLI command manually in terminal
  2. Verify API keys are configured in Settings → Agents
  3. Check your internet connection
Possible causes:
  • Script has errors
  • Missing dependencies
  • Wrong working directory
Solutions:
  1. Test the script manually in terminal first
  2. Check the Logs panel for error messages
  3. Ensure paths in the script are relative to the repository root