Appearance
Settings and links
The desktop app has its own small settings window, separate from your workspace settings. Open it from the tray menu. Every change saves as you make it.
Until the app has a session, the window shows the sign-in step instead: sign in from the Truetask window and the rest unlocks.
Workspace and session
Workspace holds the URL the main window loads. Changing it signs you out and clears the stored session token, so only do it when you are actually moving to another workspace.
Session shows who you are signed in as, with a Sign out button.
Agents
Agents reports whether Claude Code is installed and whether its runtime is running, and offers Connect an agent to open the connect window.
Sign-ins happen in each vendor's own flow, so Truetask never sees your credentials. See Desktop agents.
Clone roots
Clone roots are the folders where your repositories live.
This is the safety boundary for native launches: the app only resolves a repository that sits inside one of these folders. With no clone roots configured, native coding tool launches refuse to run and say so.
Add folders with Add folder, and remove one with the cross on its row.
Clone on demand is a single checkbox: Offer to clone missing repositories into the first clone root (asks every time). It is off by default, and even when on it always confirms before cloning.
Tool binaries and approvals
Tool binaries overrides the executable used for each tool. Clear a field to restore its default.
| Tool | Default |
|---|---|
| Codex CLI | codex |
| Claude Code | claude |
| Cursor | cursor |
| VS Code | code |
| Zed | zed |
| Claude agent adapter | empty, which means automatic |
The first time a Truetask link asks to launch a tool, the app asks you to allow it, naming the tool and the repository. Once allowed, a shield appears on that tool's row. Click the shield to revoke the approval, and the next launch asks again.
Quick capture shortcut
The shortcut that summons the palette defaults to Alt+Space, shown as Option+Space on macOS.
Click the recorder, then press the combination you want. Esc cancels. A combination needs at least one modifier unless it is a function key, because it has to work globally. A reset button appears whenever the shortcut is not the default.
Behavior
Three checkboxes, and all three matter if you want agents to work while you are away.
| Setting | What it does |
|---|---|
| Launch Truetask at login | Starts the app when you log in. |
| Keep running in the tray when the window is closed | Closing the window leaves the app in the tray instead of quitting. |
| Keep the computer awake while an agent works | Stops the machine sleeping through an agent run. |
A scheduled run that starts on your computer with nobody at the keyboard needs the app running and the coding tool signed in, so the readiness checks in the web app point at these three.
How truetask:// links work
The app owns the truetask:// scheme. Two link shapes exist, and anything else is rejected.
truetask://open
Opens a coding tool on a local checkout.
| Parameter | Meaning |
|---|---|
tool | One of claude_code, codex_cli, cursor, vscode, zed |
repo | The repository remote |
branch | Optional branch to check out |
sha | Optional commit to verify |
prompt_id | Optional prompt identifier |
Every link goes through the same five steps: parse, approve, resolve, verify, launch.
- Parse. Only the parameters above are accepted, and each is sanitized. A malformed link is refused with a native dialog.
- Approve. A tool you have not approved before asks once, and the answer is remembered.
- Resolve. The repository is found inside your clone roots. If it is missing and clone on demand is on, the app offers to clone it into the first clone root.
- Verify. The branch and commit are checked against the resolved repository, including after a fresh clone.
- Launch. The tool starts with arguments only, never through a shell.
Editors start directly. Terminal agents are never started headless: the app opens a real terminal at the checkout running a generated launcher script, with the prompt text passed in a file rather than on the command line. That is Terminal.app on macOS, the first available terminal emulator on Linux, and a PowerShell console on Windows.
Prompt text cannot travel in an operating-system link. A link that needs one says so and asks you to start the launch from the Truetask app instead, where the prompt is handed over directly. See Coding tools.
truetask://capture
Opens the palette with a task prefilled. It accepts title, description, board and url, each length-limited and sanitized, and the URL arrives as a link chip rather than as text.
Navigation
The main window stays on your workspace's origin. External http and https links open in your default browser instead of inside the app, truetask:// links are handled in place, and any other scheme is blocked.
Where things are stored
| What | Where |
|---|---|
| Shell configuration | A JSON file in the per-operating-system app config directory, for example ~/Library/Application Support/com.truetask.desktop/ on macOS |
| Your workspace token | The operating system keystore under the service com.truetask.desktop: Keychain on macOS, Credential Manager on Windows, Secret Service on Linux |
The token never sits in the configuration file, and the palette's own API calls are made by the shell so it never reaches the page.