Aliases & Launch

One shell command per project, with the right directory, the right workflow, and the right profile.

Where to configure

Open a profile, go to the Settings tab, and scroll to Launch Configuration → CLI Aliases.

How an alias works

Each alias is a generated shell script under ~/.claudeworks/bin/. When you run it:

1. ClaudeWorks sets CLAUDE_CONFIG_DIR to the profile's config directory.
2. If the alias has a directory set, it cds there first.
3. It runs claude with the configured launch action: none, /workflow, or a prefilled prompt.

Anatomy of an alias

• The name is the command you type, like ship-api or debug-mobile. It can't collide with another alias from another profile. Conflict detection flags this at save time.
• The directory is optional. If set, the alias cds there before launching. Uses your imported projects list.
• The launch action has three options:
  • None just opens Claude Code in the profile.
  • /workflow auto-runs the profile's /workflow command once the session starts.
  • Custom prompt shows a textarea. Whatever you write is passed via claude -p "..." so the session opens already working on it.

Example

# Added in Profile "work" → Settings → CLI Aliases
ship-api      cd ~/code/api     then  /workflow
debug-mobile  cd ~/code/mobile  then  custom prompt "investigate crash on login"

With this setup, running ship-api in any terminal opens a Claude Code session inside ~/code/api using the work profile's config directory, with /workflow already running.

The default profile and bare claude

One profile can be marked as Default under Settings → Launch Configuration → Set as Default Profile. That profile installs a bare claude alias, so plain claude in any shell runs inside its config directory.

Adding the alias directory to your PATH

Aliases live at ~/.claudeworks/bin/. For your shell to find them, add that directory to PATH:

# zsh, append to ~/.zshrc
export PATH="$HOME/.claudeworks/bin:$PATH"

# bash, append to ~/.bashrc
export PATH="$HOME/.claudeworks/bin:$PATH"

ClaudeWorks shows a hint in the Aliases section if the directory isn't on PATH.

Conflict detection

If two profiles declare the same alias name, both rows show a warning at save time. ClaudeWorks won't write a conflicting alias script. Rename one of them first.

Launch Prompt (editor only)

Separate from aliases, the Launch Prompt field under Launch Configuration applies only to launches from the editor's Launch button. It's passed via claude -p "..." when you click Launch. Aliases have their own per-alias prompts, so this field is for one-off editor launches.

Launch Flags

Three toggles affect every launch from this profile:

• --dangerously-skip-permissions skips the permissions prompt. Use with caution.
• --verbose enables extra Claude Code logging.
• Custom flags is a free-form text field appended to the claude command.