Make the next step clear.

Set up your first project

Before you start: the native desktop app requires macOS. Obtain a trusted pre-release build from the maintainer, or use an authorized source checkout. Local workspace creation needs no provider login. Install and sign in to the provider's own CLI separately when you want Chat or other agent work. Having Commandem installed is not provider readiness.

Install or inspect an existing build

1. For a supplied app, place it in Applications and launch it. Keep any supplied CLI on your PATH; the app and CLI identities must agree.
2. For an authorized source build, use the repository's documented Go and Xcode toolchain. From the primary integration checkout at the reviewed main revision, make install installs the CLI and ./menubar/build.sh release install builds and installs the desktop app. To request two SwiftPM jobs in that same app invocation, use COMMANDEM_SWIFT_JOBS=2 ./menubar/build.sh release install; omit a separate prebuild. This requests SwiftPM jobs, not a hard limit on WMO threads or measured CPU use. Linked workbenches may build and test, but installation from them is refused by default; a maintainer-only override is a separate deliberate action. These change installed artifacts: do not run them while a study depends on the existing binary.
3. Inspect your CLI and dependencies with the commands below. Check the app build separately. “Relaunch to update” means the running app may still be older than the bundle on disk; choose a safe relaunch time.

commandem version
commandem --help
commandem doctor --deps

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

Register and open an existing project

1. Use Add project… in the app, or run commandem add /path/to/repository for an existing folder. This registers the project; it does not create an agent turn.
2. Select the project and open Chat. Choose the provider, account, model and permission mode before sending a prompt. Inspect any privacy or tool-approval decision instead of treating it as an authentication error.
3. Send a bounded first task only when you are ready to use that provider's quota. Expect the conversation to belong to the selected provider/account; a different engine cannot natively resume that session.

Expected result: the project appears in the sidebar. When you open Chat, its pane shows your chosen engine/account. If it fails: check PATH and dependency diagnostics; check provider sign-in for agent work. Do not create duplicate project registrations to fix a missing CLI.

The examples below were checked in fictional local state, not against your credentials. No public installer, hosted service, or physical-machine sign-in is certified by this handbook.

Step-by-step first project guide →

Configure accounts and a two-agent default view

Before you start: use a build containing complete Saved Views and provider-account isolation. A named account owns provider-managed authentication and sessions. An API profile configures an endpoint; it does not inherit CLI sessions. Loadouts remember reusable choices and account names, never account credentials. A Saved View saves a project's pane configuration, not its transcript.

Profiles and provider accounts

1. Open Settings → Profiles → Manage Profiles…, select a provider, and use its Manage profiles… control for named accounts. Use an account label, not an email address.
2. For the CLI equivalent, inspect commandem account --agent codex --help. commandem account --agent codex add demo-codex creates an isolated account root; commandem account --agent codex login demo-codex starts the provider-owned sign-in flow. Neither a model name nor creating the root proves sign-in succeeded.
3. Select the account in the relevant chat pane and confirm its identity before sending. A project override and a pane selection are not a global account switch. Changes during an active turn may wait for that turn to finish.
4. Open Settings → Loadouts for reusable configurations. Inspect role bindings below; keep any account failover explicit and check the actual run receipt.

commandem account --agent codex list --json
commandem roles --json

Save both panes as the project default

1. Select a project, arrange the split, and configure each pane's view, provider, account, model, effort, mode and workbench choice. Arrange the complete displayed chat/file tab order and selected tab, including any reordered original chat. Finish active turns before applying a different saved layout.
2. Open Saved Views… from the window menu or command palette. Choose Save current view…, give it a short name, and inspect both configuration summaries.
3. Choose Set as project default. Leave and reopen the project: the split direction/divider and pane choices should restore. Automatic tab restoration fills only a pane with its original chat alone; otherwise its existing tabs stay in place.
4. Use Open to restore the affected panes’ complete saved tab order and configuration manually after saving file edits and finishing active turns, or Use ordinary default view to remove the default assignment without deleting the saved view.

If it fails: a legacy layout must be re-saved before becoming a default. A missing account/project or an active turn blocks application; no replacement account is silently substituted. Unreadable/newer storage is preserved and saving is disabled.

Saved Views contain no credentials, prompts or session identities. Newly created chat slots start fresh with saved configuration; an existing chat reused by the layout may retain its conversation. Saved Views do not copy session identities or clone conversations. File tabs store paths rather than edited contents. Named accounts are supported for Claude, Codex and Gemini; Antigravity account isolation is unavailable. Native session resume remains provider/account-specific.

Account and Profile guide → · Save a two-agent project default

Separate intent from completion

• Plan: Campaigns hold objectives; Missions hold bounded work and its acceptance criteria.
• Monitor: inspect run state, approvals, quota and verification signals together.
• Replay and receipts: inspect the recorded outcome and evidence, not just an agent's completion sentence.
• Experiments: compare declared outcomes; an unfinished or unscored cell is not a result.

commandem queue --json
commandem queue --receipts --json

A run process finishing is not proof that its objective passed. Inspect its reason and gate evidence. Guided dispatch and acceptance examples are planned.

Run and inspect a real verification gate →

Leave a note or comment, then review delivery

Before you start: choose your audience before writing. A Private Note is a local scratchpad; a Local Comment attaches to a Project, Campaign or Mission; a Board Message addresses another project; Work in Chat starts an agent turn and can send context to the provider. None of the first three is an agent turn or proof of external delivery. Not sure which one you want? Compare all five →

Keep a discussion local

1. Open the project's Notes pane for private scratchpad text. For a shared project-target discussion, open its Comments thread or the Campaign/Mission comment control, not a GitHub issue link.
2. Confirm the target and destination. Local is the built-in comment default; saved project/global defaults can change the selected destination, so inspect it rather than assuming.
3. Write and save the comment. Use the durable Mission/Campaign ID to identify a target; a displayed row number can change when the roadmap is reordered.

commandem comment destination PROJECT --json
commandem comment thread PROJECT --json
commandem comment thread PROJECT --mission-id m-xxxxxxxx --add "Please review the acceptance criteria."

Replace PROJECT and the placeholder Mission ID with your real local target. The add example writes local discussion state; it does not authorize a remote send. Private Notes and legacy activity-feed comments are separate from the target thread.

Send or recover an external delivery

1. Select an available adapter/destination deliberately. Review its audience, binding, exact payload and current permissions before approving delivery. Unsupported capabilities remain unavailable; do not make a repository public to bypass missing access.
2. Open Sync Activity to inspect the delivery state and receipt. A queued or locally saved item is not “sent.”
3. For an eligible failed Local Markdown or configured Obsidian-folder delivery, reopen the original retry review after relaunch, inspect the exact binding and content, then apply that reviewed retry. A stale review must be rebuilt; do not create a second comment as a substitute.
4. If Note branches conflict, inspect both retained versions and the explicit resolution. A local conflict decision is not a remote provider write.

commandem sync collaboration --json

This reviewed source supports Local Markdown and configured Obsidian-folder retry recovery; other adapter recovery and signed physical-device/private-repository certification remain limited. Never widen an audience just to make a provider accept a comment.

Notes, comments and delivery guide →

Review context before changing engines

Before you start: know the source provider/session/account and the destination engine/account. Native resume requires compatible ownership. A cross-provider context handoff is a new destination session with reviewed evidence. It is not foreign native resume.

1. Finish the active turn, then choose the destination provider/account. Keep the source conversation intact.
2. Review the proposed transition. Inspect candidate provenance, exclusions, privacy decisions and the bounded context preview. Remove unrelated evidence rather than treating a graph edge as permission to copy everything.
3. Approve only the exact current preview, or choose a clean start with no bridge payload. A changed source, destination or privacy decision invalidates the earlier review.
4. Inspect the resulting delivery/transition receipt and destination identity. An accepted handoff does not prove the model understood or completed the task; use feedback and verification separately.

commandem transition plan --help
commandem transition preview --help
commandem transition review --help

Use installed help for the source-session, destination-account and request-file flags; do not invent a session ID or copy credentials into a request. The CLI's plan/preview/review stages keep the review logic shared with the app.

If it fails: unavailable native resume requires a reviewed handoff or a clean start. A stale or privacy-refused preview must not be forced through by reusing its old review.

Matrix remains deterministic when no trained model is active. A graph index or labeling queue is not an active GNN. Provider training/retention controls Commandem cannot read remain unknown; inspect those provider controls directly.

Reviewed handoff guide →

Clear notifications and recover safely

Notifications: clear/read state and preferences

Before you start: clearing unread observations, silencing alerts and resolving the underlying failure are different actions.

1. Open the in-app Notifications view. Choose Clear All to clear the current shared unread observations, or Clear Board to mark board messages read while preserving their history. The view's context menu also offers Clear All Notifications and Clear Board Notifications.
2. Check the in-app, Dock and menu-bar counts against that same state. Clearing does not fix a failing project or delete historical messages; a genuinely new observation can become unread again.
3. Open Settings → Notifications. Configure the feed, badge, banner and sound surfaces separately. Per-type Critical requests sound and banner; Alert requests banner; Silent stays in the feed and badge count; Off hides that type.
4. If macOS suppresses banners/sounds, inspect its notification permissions and Focus settings. Commandem's “Critical” priority is not Apple's separately entitled Critical Alerts capability.

If it fails: refresh the feed and check for a newer observation or a lagging installed build. A persistent count mismatch is a diagnostic issue, not a reason to erase message history. Scheduled modes are not certified by this guide.

Quota, capacity and delivery

• Quota: inspect the named account and reported reset. A different model is not necessarily a different quota pool. Preserve the rejected prompt; change accounts explicitly if appropriate.
• Model capacity: distinguish saturation from account exhaustion. Retry on another supported model only after checking its account and context; do not infer a reset from a capacity error.
• Delivery: inspect the original binding, deadline and receipt in Sync Activity. Review the eligible retry for the same operation, not a duplicate comment.
• Stale build: inspect CLI and app identity separately; choose a safe relaunch time and avoid replacing a study's frozen binary.

Provider reset times are evidence, not guaranteed capacity. A stopped process or an unscored experiment cell is not a successful outcome. Preserve failure records and keep credentials/private transcripts out of diagnostic captures.

Troubleshooting by symptom →

Feature reference and installed CLI contract

Search the complete declared-feature reference: every project tab, Settings category, Home widget, navigation shortcut, static Settings control and visible CLI command has a reviewed target. Read Settings, source defaults or the CLI index for precise configuration context and boundaries.

Use commandem <verb> --help to inspect the flags your installed binary supports. Search covers these seven handbook groups, including links to detailed guides. It does not search every page or all repository documentation. Procedures above were checked against the reviewed source; physical-device sign-in, screen-reader usability and live private-provider writes require separate acceptance.

Privacy: what stays local and what can leave
Security: guardrails and named limits
Playground: a simulation, not a real agent run

No hosted handbook account, analytics dependency or remote search is required. Do not publish private diagnostics, change repository visibility, or assume an unfinished provider feature is supported.

Provider capability reference →