cassady/docs/workflows.md

Workflows

This page shows common Cassady workflows. Exact tool calls depend on the model and the prompt; use these examples as patterns rather than scripts.

Start in a workspace

cd /path/to/project
cass

Or choose a workspace explicitly:

cass --cwd /path/to/project

Ask for read-only exploration first:

Explain the structure of this repository. Do not edit files yet.

Inspect and explain code

Start in read-only mode or press Shift-Tab until the status shows read-only.

Find where configuration is loaded and summarize the precedence rules.

Cassady can use ls, read, and grep to inspect the workspace and bundled docs.

Apply a focused edit

Use workspace-edit mode:

cass --workspace-edit

Then ask for a precise change:

Update the README install section to mention both cass and cassady. Keep the rest unchanged.

Cassady may use edit or write. Edit results include a diff-like summary. If an exact-text edit fails, ask Cassady to re-read the file and retry with a smaller unique replacement.

Run tests or builds

Shell is denied in read-only mode and requires approval in workspace-edit mode.

Run the smallest relevant Rust test for this change, then summarize the result.

When the approval prompt appears, press y to approve or n/Esc to deny. Shell commands run with sh -c from the launch cwd and default to a 30-second timeout unless the model requests another timeout.

Manage provider login

Add or update provider configuration from the shell:

cass login

Inside an idle chat:

/login

Remove saved provider configuration:

cass logout

Inside an idle chat:

/logout

Logout removes selected providers from Cassady's config and removes their associated model entries. It does not delete environment variables, local Codex auth, or external provider accounts.

For ChatGPT Codex, run codex login or sign in with the Codex app before cass login. Cassady validates ~/.codex/auth.json and uses that local token source instead of asking for an API-key environment variable.

Switch model

Inside a chat:

/model MODEL_ID

Autocomplete lists models from ~/.cass/models.json. Switching models is allowed only when idle. Cassady persists the last used provider, model, and reasoning effort into config.json.

You can also launch with a model override:

cass --model MODEL_ID

Prefer fast mode

Inside a chat:

/fast

Use /fast on, /fast off, or /fast status when you want an explicit action. Cassady saves the preference in config.json, but fast mode is active only when the current provider/model supports it. ChatGPT Codex models, including gpt-5.5, are treated as fast-capable.

Switching to an unsupported provider/model keeps the preference but makes /status show fast mode as unavailable. Switching back to ChatGPT Codex enables it again.

Resume a chat

List chats for the current directory:

cass --resume

Resume a specific chat:

cass --resume CHAT_ID

Inside the UI:

/resume CHAT_ID

/resume autocomplete lists saved chats for the current directory.

Start fresh without leaving

/new

This creates a new chat for the same cwd and model while preserving your current configuration.

Branch or restore a conversation point

Press Esc twice while idle, or type:

/branch

Use the menu to select a related branch or a checkpoint from a user message, assistant message, tool-call request, or tool result. Branching creates a new chat from that point and leaves the original chat available in the same menu. Choose conversation-only branching to leave files untouched, or choose branch-plus-files to restore Cassady-tracked write/edit snapshots with conflict checks.

Check status

/status

The status block includes chat id, state, model, mode, cwd, record count, and the current status message.

Cancel and continue

While a turn is running:

• Press Esc or Ctrl-C to request turn cancellation.
• Press Ctrl-C twice within 1.5 seconds to exit.

Cassady records cancelled tool calls and a cancellation message so the conversation can continue cleanly.

Ask Cassady to edit its config

Config files live under ~/.cass, outside a normal project workspace. To inspect them, use full-access or edit them manually. After manual changes, run:

cass check

For OpenAI-compatible providers this checks API key environment variables. For ChatGPT Codex this checks local Codex auth and points you back to codex login if the token is missing or expired. Prefer cass setup or cass login for provider/model changes when possible.