Using the workspace

Projects

Start a new project in Duscode, with an optional GitHub repository, open one of your GitHub repositories or an existing folder, see finished sessions and manage your list of projects.

One Duscode serves all your projects, and you can work in several at once: the sidebar lists every open project with its sessions (see Several projects at once). Click New project at the left of the top bar to open Projects, a section of the app's dialog that lists all your projects (the open one marked Open now), opens one of your GitHub repositories or a folder, or starts a new project. A project's facts are in Project details, in its ⋯ in the sidebar (see Project details). With no project open yet, Duscode opens Projects for you.

Open a repository from GitHub

Click Open a repository in Projects (or on the Open a project to start screen) to pick one of your repositories from GitHub, GitLab or Bitbucket. Each shows its host's mark, and you can filter by host. Connect hosts in Settings → Apps & connectors.

• The list shows each repository as owner/name, with a lock for private ones and On this computer when it's already cloned here. Type in Search repositories… to filter it.
• Pick one: the first time, Duscode clones it with your own gh into your projects folder (Cloning…), then switches to it. Afterwards it opens the existing folder.
• Refresh list asks GitHub again. Manage opens github.com to choose which repositories GitHub shares.
• Duscode uses the GitHub CLI signed in as you. If it isn't installed or signed in, the list says so: run gh auth login once in a terminal, then Refresh list.

Open an existing project

From a terminal:

duscode ~/code/my-app

If Duscode is already running, this opens the folder in the running Duscode, in a new browser tab, and returns at once. duscode open ~/code/my-app does the same and prints the project's link.

A link such as http://localhost:4317/code?open=/home/you/code/my-app opens a folder too. If it isn't one of your projects yet, Duscode asks before adding it.

Or, in Projects, use Continue an existing project. Type a Folder path and click Open folder, or click one of the folders listed from your projects folder. Windows paths such as C:\… and \\wsl.localhost\… are converted for you under WSL.

The first time you open a project, Duscode suggests an architecture and asks you to confirm it. See Architecture blueprints.

Start a new project

Under Start a new project:

1. Enter a Project name, for example My shop.
2. Check the Location. It defaults to ~/projects if that folder exists, otherwise ~/duscode-projects. The folder name comes from the project name, for example ~/projects/my-shop.
3. Optionally tick Also create on GitHub (see below).
4. Click Create project.

Duscode creates the folder, a git repository on main and an empty first commit, so worktree sessions work straight away. It also hides /.duscode/ from git in the new repository. Then it asks which architecture to build with, and Dus creates the project with that stack's official starter.

Duscode won't create a project in a folder that already exists and isn't empty. Open that folder instead, or choose another name.

Also create on GitHub

Tick Also create on GitHub to create a GitHub repository for the new project and push the first commit. Dus can then push branches and open pull requests from the first session.

• Private by default. Choose Public if you want.
• The owner is your GitHub account. If you belong to organisations, you can pick one.
• It uses your own GitHub CLI login. Duscode doesn't store a GitHub token or ask for one. If gh isn't installed or isn't signed in, the option is greyed out and says how to fix it: install it from cli.github.com and run gh auth login.
• The option is off every time. Publishing is a choice you make per project.

GitHub never stops the local project from being created. If the GitHub step fails, the project is created anyway and its row shows GitHub failed with Retry. If the repository name is already taken on GitHub, you're offered Connect instead: the existing repository becomes origin and the first commit is pushed (never forced).

Your projects

Your projects lists every project you've opened, newest first. Each row shows its path, its architecture, a GitHub link if it has one, and warnings such as no git or folder missing. Projects on a Windows drive under WSL show a speed warning.

Click a project to see:

• New session here starts a session in its own worktree in that project, and opens it.
• Open opens the project and adds it to the sidebar.
• Its Finished sessions: merged, with a pull request, closed or discarded. Each shows its status icon, its last activity and its cost. Pick one to read it. With more than six, Search sessions filters by name or branch.

A project's live sessions (needing you, in progress, done but not finished) are in the sidebar, not repeated here.

The link button on a project or a session copies its link. See Links to projects and sessions.

Click × to remove a project from the list. Only the list entry is removed, no files are deleted. The list is kept in ~/.duscode/projects.json.