Launchers, CLI accounts, and add-ons

A launcher saves the command and settings you use to start a terminal program. Create it once, then use it in any repository or worktree. Each launch starts in the directory you choose in Repositories.

Launchers can open a shell, run your own scripts, or start an AI command-line application. A provider add-on connects an AI CLI to features such as account status, usage, session history, and resume. The CLI is installed separately; the add-on supplies the integration with Logonomic.

Contents:

• Launch in a repository or worktree
• Start with an installed CLI
• CLI version requirements
• Find and create launchers
• Choose the right runner
• Environment syntax and account isolation
• Profiles, accounts, and colors
• Provider overview and setup
• Quota refresh and sign-in observations
• Install and maintain CLI add-ons
• Troubleshooting launcher setup

Launch in a repository or worktree

Expand the repository in Repositories, then click the program's tile under LAUNCHERS. If several launchers share an icon, hover over a tile to check its Launch … tooltip. The terminal opens in that repository or worktree.

The launcher determines the command, environment, and account for the new terminal. Editing it later affects new launches. An existing terminal keeps its original startup recipe, including when restarted; start a new session to use your edited settings. To return to earlier work, see resume and continuation.

If you edit or delete a launcher while a launch is being prepared, the request may report that the launcher changed. Finish the edit and launch again.

Start with an installed CLI

Before adding an AI launcher:

1. Install the CLI using the provider's instructions.
2. Open it in a normal terminal and complete sign-in or credential setup.
3. Check that its command works from a fresh terminal. If you installed it or changed PATH after opening Logonomic, restart Logonomic.
4. Use Scan for installed CLIs, or add the launcher manually below.

Use the provider's CLI to sign in, sign out, renew credentials, or select its model. Logonomic's Check sign-in status observes the login. Repository-host sign-in for GitHub or GitLab is separate from AI CLI authentication.

Keep the CLI and its add-on up to date. Available integration features depend on the installed CLI's capabilities and your command configuration. A wrapper script may open the CLI successfully while preventing exact resume or delegated tasks; a simple invocation of the installed program is the easiest configuration to maintain.

CLI version requirements

Some integration features require a minimum CLI version:

Newer versions remain eligible when they provide the required capabilities. Claude Code, Qwen Code and Grok Build integrations check the required command or event behavior rather than relying on a single version number. The provider notes below explain the launcher and configuration requirements that also apply.

Find and create launchers

Open Launcher Configurations. Click a saved entry to expand its editor; click it again to close it.

Scan for installed CLIs

Click Scan for installed CLIs to find supported tools and their discoverable profiles and add their launcher configurations. Existing launchers and your customizations are preserved; exact script/environment/runner duplicates are skipped. The result reports how many configurations were added or skipped. Remove any unwanted additions from the normal launcher list.

Scanning remains available when you already have launchers. If an open launcher edit is still Saving…, adding the discovered configurations waits for it to finish. For missing configurations or a partial scan, read the provider errors and see Troubleshooting launcher setup.

On Linux, launcher resolution uses absolute directories from the inherited PATH, plus an existing ~/.local/bin. Set a launcher-specific PATH in Environment if needed.

Create a launcher manually

1. Click + (New launcher).
2. Replace the new entry's numbered name with something descriptive, such as Codex work or Project shell.
3. Enter the command or script in Script and choose its runner.
4. Add any variables in Environment. For a separate account, use the provider's profile variable described below.
5. Optionally click the icon to choose another image.
6. Let Saving… finish, then close the editor.

Edits save automatically. If a save fails, read the error. The editor retains the complete draft, including when you open another launcher. Resolve a temporary storage problem, then use Retry save.

If the saved configuration changed elsewhere or the save outcome is uncertain, choose Reload stored configuration. Reload keeps your edits and incorporates stored changes to fields you did not edit. If both versions changed a field differently, choose Keep draft or Use stored for each conflict. Review the reconciled draft, then use Retry save; reloading by itself does not save the changes.

Reload also applies valid stored account and usage-history changes. If it reports an operation still running, wait for that operation to finish, then choose Reload stored configuration again.

If the launcher was removed elsewhere, use Save as new Launcher to save the retained draft as a new entry. Choose Discard draft only when you want to abandon the edits.

An empty Script opens the chosen shell; Direct requires a program and reports Script is empty. otherwise.

The name and icon help you recognize a launcher. The Script, runner, and Environment determine what it executes. Available for read-only review controls whether an identified account is offered for those tasks; see account availability.

Delete a launcher

Click the entry's trash button (Delete launcher). Pending edits are saved first, and there is no separate deletion confirmation.

Deleting a launcher removes its saved recipe. Running terminals, the external CLI, credentials, and provider conversations remain. Keep a suitable launcher for an account you want to use again: deleting its last launcher can remove that profile from the available launch and resume choices.

Choose the right runner

Choose a shell runner for a script, or Direct for one program with arguments. New launchers default to PowerShell on Windows and bash on Linux.

A Windows launcher opened on Linux may show PowerShell (unavailable) or cmd (unavailable). Choose an available runner and adapt its script.

For a shell terminal, leave Script empty. To use PowerShell 7, choose Direct and enter pwsh or its full path. For other common cases:

PowerShell and cmd keep the shell open after an ordinary script ends. Recognized AI CLI launches do not receive that keep-open behavior. A nonempty Bash script ends when its commands finish. On Linux it uses a non-login shell; on Windows it uses Bash's login-command behavior.

Direct command lines

Enter one executable followed by its arguments:

"C:\Tools\example\example.exe" --mode interactive

/opt/example/bin/example --mode interactive

Double quotes group paths or arguments containing spaces. Three consecutive double quotes represent a literal double quote. Single quotes do not group arguments, and malformed quoting is rejected.

Direct does not expand aliases, variables, shell functions, redirection, or operators such as &&. Put variables in Environment and use a shell runner when you need shell features. For provider launchers, keep the CLI in the directory Logonomic supplies: a script that changes directory can prevent session attribution or exact resume.

Environment syntax and account isolation

Enter one KEY=value assignment per line. For example, a separate Codex profile on Windows might use:

CODEX_HOME=C:\Users\YourName\.codex-work
EXAMPLE_MODE=interactive

On Linux:

CODEX_HOME=/home/yourname/.codex-work

This syntax is the same for every runner. Omit $env:, set, and export, and leave paths unquoted even when they contain spaces. Quotes become part of the value. Names must begin with an ASCII letter or underscore and contain only ASCII letters, digits, and underscores.

Blank lines are ignored; comments are not supported. Use each name once and, on Windows, avoid case variants such as Path and PATH. The first = separates the name and value; further = characters belong to the value. An empty value sets an empty variable. Lines are trimmed, but spaces immediately after = remain part of the value.

You can expand inherited variables using %NAME% on either platform:

CODEX_HOME=%USERPROFILE%\.codex-work
PATH=C:\Tools\Example;%PATH%

On Linux, use %HOME%/.codex-work for the home-relative example and : as the PATH separator. Expansion happens once against Logonomic's inherited environment; assignments cannot refer to other lines in this field. Unknown references stay unchanged. $HOME, $env:USERPROFILE, and ~ are not expanded here. Absolute paths are the clearest choice for account profiles.

These settings affect new launches from this launcher. They do not change your system environment or running terminals. Environment text is saved as ordinary launcher configuration, so use the provider's credential storage for secrets.

Profiles, accounts, and colors

A CLI profile holds an external tool's settings, login, and conversations. A Logonomic profile holds Logonomic's own settings and saved data. One Logonomic profile can contain launchers for several CLI profiles and providers.

Two launchers can share a CLI profile, and two separate CLI profiles can use the same provider login while keeping separate conversation histories. The launcher command and environment select the profile; its native credentials determine the login.

Create separate work and personal launchers

1. Create and authenticate the two native CLI profiles using the provider's supported workflow.
2. Create a launcher for each, with names such as Claude work and Claude personal.
3. Set the appropriate profile variable from the provider table in Environment, using an absolute path.
4. Start each launcher and verify the account in the CLI itself.
5. Where supported, use Check sign-in status and Refresh now from its status-bar badge to update Logonomic.

Choose the other launcher when starting work with another account. To change the login inside a profile, use the provider's CLI and refresh its status. Logonomic does not move existing conversations between profiles.

Shared names and accents

Account colors connect launcher icons, sessions, usage rows, and supported Companion views. Launchers for the same identified CLI profile share a saved accent; the first launcher for that profile supplies its shared account name. Launchers without an identified account receive their own accent.

The icon picker changes the symbol. A recognized provider's image takes precedence over a built-in fallback; an explicitly chosen add-on image takes precedence over automatic recognition. A missing add-on image can fall back to a basic icon without changing the command. The palette supports 360 distinct accents; exhaustion reports Could not allocate a distinct account accent.

Duplicate-account badges

Profiles recognized as the same login can share one quota badge. A duplicate launcher may show This account is already listed under “…”. You can keep both profiles for their separate settings and conversations.

An unedited, automatically discovered default-profile launcher can be hidden when a named profile uses the same login. It remains saved and can return if that relationship changes. Manually created or edited launchers remain visible.

Account availability

Turn on Available for read-only review to offer the identified account for read-only review tasks. It defaults to off and is shared by launchers using the same account profile.

Interactive launches, explicit implementation/delegation tasks, and account or usage checks work independently of this switch. The provider must support the requested task, and its native permissions still apply. Use task controls to stop a running implementation task.

The switch appears only for an identified account or supported usage scope. If it is missing, check the profile environment and provider integration. OpenCode does not expose one global account through this integration.

Provider overview

Use these tables to compare the integrations covered by this guide. Your installed add-on, CLI, and launcher configuration determine which operations are available; follow the linked provider notes for their prerequisites.

Sessions and tasks

Resume means exact resume; Continue means continue in destination; Task means an implementation task; Review means read-only review; Activity means activity reporting.

Continue in destination means that the launcher can start a new conversation with the earlier session's brief as its first message. Codex and Claude supply that capability in these integrations. The menu uses the installed add-on's capabilities and the launcher's configuration to determine eligibility.

Exact resume needs a recorded provider conversation identity, its retained native conversation, the correct account/profile, and a usable original worktree. Opening a terminal or keeping a history entry does not guarantee that resume will be available. Activity reporting also depends on the provider's hooks and events; it is not a complete transcript of every action.

Titles and summaries are separate from activity status. Managed agents can report them through the supplied title and summary commands. A working activity indicator does not guarantee a current summary: check its update or review time. Your own title takes precedence. See Titles, summaries, and worktree reports for what these reports mean.

Implementation tasks use the launcher's native tool permissions. Read-only review is a separate capability, offered by Claude here, and also requires the account's review availability switch. See sessions and coordination for the workflows.

Accounts and usage

The following provider notes cover setup and less common resume/task problems.

Codex

Set CODEX_HOME to select a profile. Scanning checks the selected home and neighboring .codex... folders containing authentication files. It offers a generic configuration if it finds Codex without a profile. Discovered configurations use PowerShell on Windows and Direct on Linux.

Codex's settings choose the model, approval policy, and sandbox, including for delegated tasks. Unattended work needs permission for its intended operations. Structured implementation and review tasks require a non-bare Git checkout.

For exact resume, use a verifiable installed executable and avoid arguments that choose another session. A conflicting telemetry log exporter can also prevent confirmation that the requested conversation opened.

Continuation needs a supported invocation without an existing prompt, incompatible session arguments, or image-attachment arguments. Text beginning with ! cannot be used as its ordinary first message. Codex's own setup, including Windows sandbox setup, may still require your attention.

Claude Code

Set CLAUDE_CONFIG_DIR to select a profile. Scanning checks the selected profile and neighboring .claude... folders with .credentials.json. Discovered configurations use cmd on Windows and Direct on Linux.

Make Node available in the launch environment for activity hooks and exact resume. Claude can open without it, but activity reporting may be reduced. Read-only reviews and implementation tasks use Claude's native options and permissions; a dedicated launcher is useful for different task settings.

Continuation requires a plain supported invocation. Existing prompts, print mode, resume/continue selectors, main-thread --agent, and inline JSON --settings can prevent it. Claude also interprets some first messages as special input, including slash commands, leading dashes, one-word text, and paste references; those cannot be guaranteed as ordinary continuation text.

Kimi

Scanning offers a Direct configuration from the resolved kimi, kimi-code, or kimi-cli executable. Set KIMI_CODE_HOME for a separate profile.

Logonomic adds managed hooks to the profile's config.toml, preserving other configuration. If you edited a managed definition incompatibly, preparation reports a conflict; resolve it before retrying. Custom agents also need access to the session guidance file under the profile's scratch/logonomic directory.

Exact resume requires the session selector and working SessionStart hooks. Delegated tasks need Kimi's supported agent protocol and permissions for the work. Use Kimi itself to renew credentials if quota checks require it.

OpenCode

Use OpenCode's native provider/model configuration. Because it can use several backends, this integration supplies no combined global account, quota, sign-in state, or usage total.

For activity reporting and exact resume, use a verifiable installed OpenCode with Direct or a plain Windows PowerShell invocation. Resume cannot use options that select another session, folder, interface, or plugin configuration.

Logonomic preserves your OpenCode configuration. Unattended tasks retain native permissions: their own task controls are allowed once, while other operations requiring interactive approval are rejected. Configure the required file and command permissions in OpenCode before submitting work.

Antigravity

Use the native agy executable. Package-runner forms such as npx agy and bunx agy are not the native integration. Antigravity has one profile per operating-system user; GEMINI_CLI_HOME does not create isolated accounts.

To enable activity and title hooks:

1. Find assets/hooks-windows.json or assets/hooks-linux.json in the installed Antigravity add-on, matching your platform.
2. Open ~/.gemini/config/hooks.json, creating it if necessary.
3. Merge the packaged logonomic-hook-relay member into the JSON object, preserving other members. For a new file, use the complete packaged object.
4. When updating, replace the previous complete member rather than adding a duplicate. Save valid JSON and start a new session through Logonomic.

Logonomic does not edit this global hook file automatically. The subscription is inactive outside Logonomic launches. On Windows, managed launches disable Antigravity's background self-updater for that process to avoid extra terminal windows; an explicit setting in your launcher script can override this.

Exact resume needs one literal native command, without another session selector, one-shot prompt, unrelated commands, dynamic shell expansion, or your own --log-file. For delegated tasks, task_tools_not_permitted names the entries needed in native permissions.allow. Grant those controls and the permissions needed for the task itself.

Grok Build

Set GROK_HOME to select a profile; an empty override uses .grok. Sign-in checking uses Grok's native account status. Renew expired credentials through Grok. Quota checking supports the public xAI account route; custom, team, or proxy authentication can leave quota unavailable while interactive use works.

Logonomic manages hooks/logonomic.json under the selected home and refuses to overwrite a conflicting file. Title and coordination guidance may arrive at the first root tool call. A turn without one may not receive it, and Grok's stop hook does not reliably establish turn completion.

Delegated agent mode accepts supported model, reasoning-effort, and --always-approve selections. Interactive --permission-mode, --allow, and --deny options have no equivalent there and are refused. A denied tool can fail the task with tool_permission_denied.

Forked histories can make usage attribution ambiguous. The diagnostic usage_fork_attribution_unavailable leaves the last accepted totals intact; see usage history and repair.

Qwen Code

Scanning offers a Direct qwen configuration. A standalone installation can supply its own runtime; an npm installation needs the runtime required by its package.

Set QWEN_HOME for a profile. Native .env bootstrap settings can also select the home, with explicit environment values taking precedence. Related options include QWEN_RUNTIME_DIR, QWEN_CODE_MCP_APPROVALS_PATH, and QWEN_CODE_TRUSTED_FOLDERS_PATH. Changing the runtime directory does not move the global history used for usage totals. The account row identifies the profile; authentication is checked by Qwen when it runs.

Logonomic adds managed hooks to settings.json, preserving unrelated settings. An explicit disableAllHooks or modified conflicting managed definition must be resolved before integration can proceed.

Tasks require Direct with supported model, authentication, and approval options. Exact resume also accepts a plain Windows PowerShell invocation; include & before a quoted executable path. Dynamic expressions, unrelated commands, or arguments altered by a Windows script shim can prevent resume. Unattended tasks retain native permissions and reject non-control operations that need interactive approval.

Quota refresh and sign-in observations

Click an account's logo on the left of the status bar to open its menu. Hover over the adjacent quota bars or status label to read details.

• Refresh now checks quota and supported account information.
• Check sign-in status checks authentication without requesting quota.
• Automatic refresh checks at startup and about every five minutes, with one retry after about 30 seconds if a check fails.
• Manual refresh keeps checks on demand for that launcher.

Automatic is the default. Refresh mode is saved per launcher, so another automatic launcher for the same login can still request checks. These checks can invoke the native CLI and make network requests.

Signed in and Not signed in reflect the latest successful native check. Unknown means the check could not establish either state; unavailable means the provider or invocation cannot supply it. After a failed check, an older successful observation may remain with (out of date). Use the native CLI to repair login problems, then refresh.

Quota can show Loading, Not checked yet, Not logged in, N/A, or remaining allowances. N/A does not mean zero quota: hover for the reason. Failed refreshes can leave older values visible with a warning. For how to read the bars and compare them with recorded consumption, see usage, notes, and insights.

Install and maintain CLI add-ons

Use a complete published package for your operating system and architecture. The integrations in this guide package Windows x86-64 and Linux x86-64 separately. Add-ons contain executable code with your account's access, so choose a distributor you trust.

Package locations

Logonomic looks in these locations, in precedence order:

1. The optional development root.
2. cli-addons/packages in the active Logonomic profile's local-data folder.
3. cli_addons beside the actual desktop executable.

Each package is an immediate child directory containing its manifests and complete contents:

<Logonomic profile local-data folder>/
  cli-addons/
    packages/
      logonomic.cli.example/
        logonomic-cli-addon.json
        package.files.json
        ...complete package contents...

See profiles and storage to locate the active data folder. A CLI profile such as .codex-work is a different location. In portable installations, bundled add-ons can be inside the runtime directory rather than beside the outer launcher.

Install or update a user package

1. Obtain the complete matching package and finish work using that provider.
2. Exit the relevant Logonomic instance normally; see terminal closing behavior.
3. Extract the package to a temporary folder outside the package roots.
4. Place its directory in the active profile's cli-addons/packages. For an update, first move the old directory outside all package roots.
5. Check that the manifests are directly inside the package directory, without an extra archive wrapper folder. Preserve executable permissions on Linux and leave indexed files intact.
6. Restart Logonomic and use or create the provider's launcher.

Packages are selected when Logonomic starts. Replacing files does not update live sessions, and Scan for installed CLIs discovers and adds launcher configurations.

Replacement, duplicates, and removal

The highest-precedence package with a given identity wins, regardless of its version number. Keep only one copy of an identity at each level: a neighboring old or backup directory can make both unavailable. Keep backups outside all package roots.

An invalid higher-precedence package blocks that identity rather than using a lower copy. To return to the bundled package, close Logonomic, remove the user or development override from its root, and restart. Removing a user package leaves the CLI and its profiles intact; saved launchers may lose integrated features until a compatible package is available.

For missing files, hash mismatches, duplicate identities, or platform errors, restore a complete matching package and restart. An individual unavailable capability, such as quota, does not necessarily affect interactive use.

Advanced package-root settings

Most installations need no overrides. For a custom deployment, the active profile supports:

[cli_addons]
development_root=C:/path/to/development-packages
installation_root=C:/path/to/installation-packages

Use absolute paths to roots containing package directories. An absent development_root disables that override; an absent installation_root uses the normal bundled location. An explicitly empty installation_root disables that location. The user package root stays tied to the active profile.

Change settings with Logonomic closed. This is INI syntax; default Windows preferences may use the registry. See application preference storage.

Configuration and package limits

An integrated launcher's Script and Environment each allow 4,096 UTF-8 bytes. For larger ordinary scripts, save the logic in a file and launch it, bearing in mind that wrappers may prevent provider integration.

For custom package inventories, each root allows 256 candidate directories and Logonomic admits at most 64 packages. A package allows 4,096 files, 512 MiB per file, and 2 GiB total; the selected set allows 8 GiB. If a package exceeds a limit, obtain a suitable package rather than deleting indexed contents.

Troubleshooting launcher setup

Follow any specific storage-recovery instructions shown with an error. Keep the profile files while investigating; a failed save does not call for deleting the whole launcher store. See profiles and storage.