Set up your first project

Before you start

You need macOS 14 or newer for the desktop app and a trusted pre-release build or authorized source checkout. Local workspace creation does not require a provider login or an agent turn. Install and authenticate the provider CLI only when you want Chat or other agent work. The portable CLI and desktop app have different platform limits. See release availability and requirements.

No public installer is certified yet.

A website screenshot is not a download. Do not install a package from an unverified third-party mirror.

Inspect the existing installation

commandem version
commandem --help
commandem doctor --deps

Check the app build separately. A running app may predate the bundle on disk. A dependency check reports readiness evidence; it does not sign you into a provider or prove that a turn will succeed.

Create a workspace without a coding setup

Open New project (guided) and choose a starter under Documents and simple workspaces. Give it a name and location, review the files it will create, then select Create project.

Starter	Initial content
Documents	documents/, notes/ and references/ folders, a README and shared agent guidance.
Simple workspace	A README, notes/ and shared agent guidance. Add other files as needed.
Blank	Only commandem.toml and local Git metadata. No starter files or instructions.

All three register a local folder. They create no commits, remote repositories, coding tools, hooks or queued builds, and run no agent. After creation, choose Open Files to add content or Open Chat to prepare a conversation. Sending a prompt is a separate action that can spend provider quota.

The CLI offers the same choices. These examples create three separate folders:

commandem new --list
commandem new writing --template documents
commandem new scratch --template simple
commandem new empty --template blank

If the choices are missing in the app, check that both the app and CLI are updated. The picker hides workspace starters that the installed CLI cannot create. Explicit engineering Health still checks for coding requirements; these starters do not fabricate passing checks for a document folder.

Partial creation: If registration fails after files are created, preserve the folder. Fix the registry problem, then use Add project or the quoted commandem add recovery command shown in the error. Do not delete drafts or create duplicate folders to hide the failure.

Register and open an existing project

Choose an existing folder or repository you control. In the app, use Add project..., or run commandem add /path/to/project.
Select the project and open Chat. Inspect the provider, named account, model and permission mode before sending.
Confirm the account is signed in through its own provider flow. Registering a folder and creating an account root do not authenticate it.
Send one bounded request when you are ready to spend provider quota. Inspect approvals rather than treating them as login failures.

1. Register

The folder appears in Commandem. No agent turn starts.

2. Identify

Provider, account and permission mode are explicit.

3. Verify

The response belongs to that identity; completion needs independent evidence.

Expected result and recovery

The project appears in the sidebar and Chat shows the selected engine/account. If it does not, inspect PATH, dependency evidence and provider sign-in first. Do not create duplicate registrations to repair a missing executable.

Source builds change installed artifacts when you run make install or ./menubar/build.sh release install. Do not replace a binary while a research study depends on it. For non-installing contribution checks, see contributor setup.

CLI examples are checked in fictional local state. Physical-machine sign-in and public packaging require separate acceptance.