Quickstart
Start your first Cusp session in the desktop app or the terminal.
This guide takes you from a fresh install to an agent that has read your project and made a change. You need Cusp installed and an API key for any supported provider, or a local model server running.
Paste a key
Open Cusp. On the welcome screen, paste an API key from any provider: Anthropic, OpenAI, Google, OpenRouter, DeepSeek, Moonshot, Z.ai, and so on.
Cusp works out the rest:
- It recognizes the provider from the key prefix (
sk-ant-,sk-or-,AIza,xai-, …) or from the base URL if you entered one. - It probes the endpoints in parallel to see which wire protocols answer. Probes don't spend tokens.
- It lists the available models and picks a main model for the agent and a small, fast one for titles and summaries.
The key goes into your OS keychain. Cusp stores only a reference to it.
For a gateway or a self-hosted endpoint, enter the base URL as well. For Ollama or LM Studio, enter the local URL (http://localhost:11434 or http://localhost:1234); no key is needed.
Pick a folder
Choose Open Folder… (⌘O on macOS, Ctrl+O elsewhere) and select a project. Cusp reads its instruction files (CUSP.md, CLAUDE.md, AGENTS.md) and any .cusp/ or .claude/ configuration it finds.
The first time you open a folder, Cusp asks whether you trust it. Until you do, the project's settings can't add hooks, environment variables, MCP servers or allow rules.
Ask
Type what you want in the composer and press Enter. A good first prompt is a question about the code:
How does authentication work in this project? Point me to the main files.Then ask for a small change:
Add a --verbose flag to the CLI entry point and log the resolved config when it's set.While the agent works you see a thinking indicator with elapsed time and tokens. Each tool call appears in the transcript. When the agent wants to edit a file or run a command, Cusp asks first. You can allow it once, for the rest of the session, or always.
When the turn ends, Cusp shows a one-line summary: how long it took, how many tools ran, and the tokens used.
Run Cusp without the UI
Headless mode runs one prompt, prints the result and exits. It works in scripts, git hooks and CI:
cusp -p "Summarize the changes on this branch in three bullet points"Pipe input in, and get structured output out:
git diff main | cusp -p "Review this diff for bugs" --output-format jsonHeadless runs can't stop to ask you anything. Tool calls that would need approval are denied unless you pre-approve them:
cusp -p "Fix the failing unit tests" \
--allowedTools "Bash(npm test *)" Edit \
--max-turns 30See the CLI reference for every flag and the JSON output format.
Pick a different model
Cusp picks a model for you, but you can change it at any time.
- In the desktop app, use the model picker in the composer.
- In the CLI, type
/modelto choose from a list, or/model openrouter:z-ai/glm-5.3to switch directly. - From the command line, start with
cusp -m anthropic:claude-sonnet-5-5.
Effort controls how long the model reasons before answering. Set it with /effort high or --effort high. See Models and effort.
Write a project guide
Run /init in a new project. Cusp reads the codebase and writes a CUSP.md at the repository root with build, test and lint commands, an architecture overview, and conventions. If the project already has a CUSP.md, AGENTS.md or CLAUDE.md, it improves that file instead. Every later session starts with this context. See Memory.