Trapeze

Your new coding bestie, now available in your favourite terminal.
Your tools, your code, and your workflows, wired into your LLM of choice.

Note

Trapeze is amarbel-llc's fork of charmbracelet/crush, renamed from crush to trapeze (see trapeze#1). Upstream documentation largely still applies; identity-bearing names (binary, module path, config dirs, env vars) are trapeze/TRAPEZE_* here.

Features

Multi-Model: choose from a wide range of LLMs or add your own via OpenAI- or Anthropic-compatible APIs
Flexible: switch LLMs mid-session while preserving context
Session-Based: maintain multiple work sessions and contexts per project
LSP-Enhanced: Trapeze uses LSPs for additional context, just like you do
Extensible: add capabilities via MCPs (http, stdio, and sse)
Works Everywhere: first-class support in every terminal on macOS, Linux, Windows (PowerShell and WSL), Android, FreeBSD, OpenBSD, and NetBSD

Installation

Build with Nix (the repo's source of truth — see justfile):

nix build github:amarbel-llc/trapeze

Or, download it:

Packages are available in Debian and RPM formats
Binaries are available for Linux, macOS, Windows, FreeBSD, OpenBSD, and NetBSD

Or just install it with Go:

go install github.com/amarbel-llc/trapeze@latest

Warning

Productivity may increase when using Trapeze and you may find yourself nerd sniped when first using the application. If the symptoms persist, join the Slack or Discord and nerd snipe the rest of us.

Getting Started

The quickest way to get started is to grab an API key for your preferred provider such as Anthropic, OpenAI, Groq, OpenRouter, or Vercel AI Gateway and just start Trapeze. You'll be prompted to enter your API key.

That said, you can also set environment variables for preferred providers.

Environment Variable	Provider
`HYPER_API_KEY`	Charm Hyper
`ANTHROPIC_API_KEY`	Anthropic
`OPENAI_API_KEY`	OpenAI
`VERCEL_API_KEY`	Vercel AI Gateway
`GEMINI_API_KEY`	Google Gemini
`SYNTHETIC_API_KEY`	Synthetic
`ZAI_API_KEY`	Z.ai
`MINIMAX_API_KEY`	MiniMax
`HF_TOKEN`	Hugging Face Inference
`CEREBRAS_API_KEY`	Cerebras
`OPENROUTER_API_KEY`	OpenRouter
`IONET_API_KEY`	io.net
`ALIBABA_SINGAPORE_API_KEY`	Alibaba (Singapore)
`GROQ_API_KEY`	Groq
`AVIAN_API_KEY`	Avian
`OPENCODE_API_KEY`	OpenCode Zen & Go
`VERTEXAI_PROJECT`	Google Cloud VertexAI (Gemini)
`VERTEXAI_LOCATION`	Google Cloud VertexAI (Gemini)
`AWS_ACCESS_KEY_ID`	Amazon Bedrock (Claude)
`AWS_SECRET_ACCESS_KEY`	Amazon Bedrock (Claude)
`AWS_REGION`	Amazon Bedrock (Claude)
`AWS_PROFILE`	Amazon Bedrock (Custom Profile)
`AWS_BEARER_TOKEN_BEDROCK`	Amazon Bedrock
`AZURE_OPENAI_API_ENDPOINT`	Azure OpenAI models
`AZURE_OPENAI_API_KEY`	Azure OpenAI models (optional when using Entra ID)
`AZURE_OPENAI_API_VERSION`	Azure OpenAI models

Subscriptions

If you prefer subscription-based usage, here are some plans that work well in Trapeze:

By the Way

Is there a provider you’d like to see in Trapeze? Is there an existing model that needs an update?

Trapeze’s default model listing is managed in Catwalk, a community-supported, open source repository of Trapeze-compatible models, and you’re welcome to contribute.

Configuration

Tip

Trapeze ships with a builtin trapeze-config skill for configuring itself. In many cases you can simply ask Trapeze to configure itself.

Trapeze runs great with no configuration. That said, if you do need or want to customize Trapeze, configuration can be added either local to the project itself, or globally, with the following priority:

.trapeze.json
trapeze.json
$HOME/.config/trapeze/trapeze.json

Configuration itself is stored as a JSON object:

{
  "this-setting": { "this": "that" },
  "that-setting": ["ceci", "cela"]
}

As an additional note, Trapeze also stores ephemeral data, such as application state, in one additional location:

# Unix
$HOME/.local/share/trapeze/trapeze.json

# Windows
%LOCALAPPDATA%\trapeze\trapeze.json

Tip

You can override the user and data config locations by setting:

TRAPEZE_GLOBAL_CONFIG
TRAPEZE_GLOBAL_DATA

LSPs

Trapeze can use LSPs for additional context to help inform its decisions, just like you would. LSPs can be added manually like so:

{
  "$schema": "https://raw.githubusercontent.com/amarbel-llc/trapeze/master/schema.json",
  "lsp": {
    "go": {
      "command": "gopls",
      "env": {
        "GOTOOLCHAIN": "go1.24.5"
      }
    },
    "typescript": {
      "command": "typescript-language-server",
      "args": ["--stdio"]
    },
    "nix": {
      "command": "nil"
    }
  }
}

MCPs

Trapeze also supports Model Context Protocol (MCP) servers through three transport types: stdio for command-line servers, http for HTTP endpoints, and sse for Server-Sent Events.

Shell-style value expansion ($VAR, ${VAR:-default}, $(command), quoting, nesting) works in command, args, env, headers, and url, so file-based secrets work out of the box. You can use values like "$TOKEN" or "$(cat /path/to/secret/token)". Expansion runs through Trapeze's embedded shell, so the same syntax works on every supported system, Windows included.

Unset variables expand to the empty string by default, matching bash. For required credentials, use ${VAR:?message} so an unset variable fails loudly at load time with message instead of silently resolving to empty:

{ "api_key": "${CODEBERG_TOKEN:?set CODEBERG_TOKEN}" }

Headers (both MCP headers and provider extra_headers) whose value resolves to the empty string are dropped from the outgoing request rather than sent as Header:. That keeps optional env-gated headers like "OpenAI-Organization": "$OPENAI_ORG_ID" clean when the variable is unset.

Provider extra_body is a non-expanding JSON passthrough; put env-driven values in extra_headers or the provider's api_key / base_url, all of which do expand.

Security note: trapeze.json is trusted code. Any $(...) in it runs at load time with your shell's privileges, before the UI appears. Don't launch Trapeze in a directory whose trapeze.json you haven't reviewed.

{
  "$schema": "https://raw.githubusercontent.com/amarbel-llc/trapeze/master/schema.json",
  "mcp": {
    "filesystem": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/mcp-server.js"],
      "timeout": 120,
      "disabled": false,
      "disabled_tools": ["some-tool-name"],
      "env": {
        "NODE_ENV": "production"
      }
    },
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "timeout": 120,
      "disabled": false,
      "disabled_tools": ["create_issue", "create_pull_request"],
      "headers": {
        "Authorization": "Bearer $GH_PAT"
      }
    },
    "streaming-service": {
      "type": "sse",
      "url": "https://example.com/mcp/sse",
      "timeout": 120,
      "disabled": false,
      "headers": {
        "API-Key": "$(echo $API_KEY)"
      }
    }
  }
}

Hooks

Trapeze has preliminary support for hooks. For details, see the hook guide.

Sharing a workspace across clients

When Trapeze is run against a shared backend (for example two TUIs talking to the same trapeze serve), clients are grouped into workspaces keyed by their resolved --cwd. Two clients with the same --cwd join the same underlying workspace, so they share the session list, message history, permission queue, LSP, and MCP state.

Joining is implicit: pointing a second client at the same working directory attaches it to the existing workspace. Each new invocation, however, starts in its own fresh session by default. To pick up the conversation another client already has open, use the session manager (the session picker) and select it. Sessions surface two signals there:

IsBusy is set while an agent turn is in flight for that session.
AttachedClients reports how many clients are currently viewing it.

A non-zero AttachedClients (often combined with IsBusy) is the cue that a session is "in progress" on another client and joining it will mirror that view live.

The first client to create a workspace fixes its process-wide flags. In particular, --yolo and --debug follow a first-wins rule: later clients that arrive at the same --cwd with different values for those flags do not change the running workspace. A debug log line is emitted recording the mismatch, and the workspace keeps the flags it was created with.

A workspace lives as long as at least one client has an SSE event stream open against it. When the last stream disconnects, the workspace is torn down. There is a short grace window right after POST /v1/workspaces so a client that has created the workspace but not yet opened its event stream does not get reaped before it can attach.

Ignoring Files

Trapeze respects .gitignore files by default, but you can also create a .trapezeignore file to specify additional files and directories that Trapeze should ignore. This is useful for excluding files that you want in version control but don't want Trapeze to consider when providing context.

The .trapezeignore file uses the same syntax as .gitignore and can be placed in the root of your project or in subdirectories.

Allowing Tools

By default, Trapeze will ask you for permission before running tool calls. If you'd like, you can allow tools to be executed without prompting you for permissions. Use this with care.

{
  "$schema": "https://raw.githubusercontent.com/amarbel-llc/trapeze/master/schema.json",
  "permissions": {
    "allowed_tools": [
      "view",
      "ls",
      "grep",
      "edit",
      "mcp_context7_get-library-doc"
    ]
  }
}

You can also skip all permission prompts entirely by running Trapeze with the --yolo flag. Be very, very careful with this feature.

Disabling Built-In Tools

If you'd like to prevent Trapeze from using certain built-in tools entirely, you can disable them via the options.disabled_tools list. Disabled tools are completely hidden from the agent.

{
  "$schema": "https://raw.githubusercontent.com/amarbel-llc/trapeze/master/schema.json",
  "options": {
    "disabled_tools": ["bash", "sourcegraph"]
  }
}

To disable tools from MCP servers, see the MCP config section.

Disabling Skills

If you'd like to prevent Trapeze from using certain skills entirely, you can disable them via the options.disabled_skills list. Disabled skills are hidden from the agent, including builtin skills and skills discovered from disk.

{
  "$schema": "https://raw.githubusercontent.com/amarbel-llc/trapeze/master/schema.json",
  "options": {
    "disabled_skills": ["trapeze-config"]
  }
}

Agent Skills

Trapeze supports the Agent Skills open standard for extending agent capabilities with reusable skill packages. Skills are folders containing a SKILL.md file with instructions that Trapeze can discover and activate on demand.

The global paths we looks for skills are:

$TRAPEZE_SKILLS_DIR
$XDG_CONFIG_HOME/agents/skills or ~/.config/agents/skills/
$XDG_CONFIG_HOME/trapeze/skills or ~/.config/trapeze/skills/
~/.agents/skills/
~/.claude/skills/
On Windows, we also look at
- %LOCALAPPDATA%\agents\skills\ or %USERPROFILE%\AppData\Local\agents\skills\
- %LOCALAPPDATA%\trapeze\skills\ or %USERPROFILE%\AppData\Local\trapeze\skills\
Additional paths configured via options.skills_paths

On top of that, we also load skills in your project from the following relative paths:

.agents/skills
.trapeze/skills
.claude/skills
.cursor/skills

{
  "$schema": "https://raw.githubusercontent.com/amarbel-llc/trapeze/master/schema.json",
  "options": {
    "skills_paths": [
      "~/.config/trapeze/skills", // Windows: "%LOCALAPPDATA%\\trapeze\\skills",
      "./project-skills",
    ],
  },
}

You can get started with example skills from anthropics/skills:

# Unix
mkdir -p ~/.config/trapeze/skills
cd ~/.config/trapeze/skills
git clone https://github.com/anthropics/skills.git _temp
mv _temp/skills/* . && rm -rf _temp

# Windows (PowerShell)
mkdir -Force "$env:LOCALAPPDATA\trapeze\skills"
cd "$env:LOCALAPPDATA\trapeze\skills"
git clone https://github.com/anthropics/skills.git _temp
mv _temp/skills/* . ; rm -r -force _temp

User-Invocable Skills

Skills can be made invocable as commands from the commands palette (Ctrl+P). Add user-invocable: true to the skill's YAML frontmatter:

---
name: my-skill
description: A skill that can be invoked as a command.
user-invocable: true
---

User-invocable skills appear in the commands palette with a user: or project: prefix:

Skills from global directories show as user:skill-name
Skills from project directories show as project:skill-name

When invoked, the skill's instructions are loaded into the conversation context.

To prevent the model from auto-triggering a skill (while still allowing user invocation), add disable-model-invocation: true:

---
name: my-skill
description: Only invocable by users, not the model.
user-invocable: true
disable-model-invocation: true
---

Skills with disable-model-invocation won't appear in the model's available skills list but can still be invoked manually by users.

Desktop notifications

Trapeze sends desktop notifications when a tool call requires permission and when the agent finishes its turn. They're only sent when the terminal window isn't focused and your terminal supports reporting the focus state.

{
  "$schema": "https://raw.githubusercontent.com/amarbel-llc/trapeze/master/schema.json",
  "options": {
    "disable_notifications": false, // default
  },
}

To disable desktop notifications, set disable_notifications to true in your configuration. On macOS, notifications currently lack icons due to platform limitations.

Initialization

When you initialize a project, Trapeze analyzes your codebase and creates a context file that helps it work more effectively in future sessions. By default, this file is named AGENTS.md, but you can customize the name and location with the initialize_as option:

{
  "$schema": "https://raw.githubusercontent.com/amarbel-llc/trapeze/master/schema.json",
  "options": {
    "initialize_as": "AGENTS.md"
  }
}

This is useful if you prefer a different naming convention or want to place the file in a specific directory (e.g., TRAPEZE.md or docs/LLMs.md). Trapeze will fill the file with project-specific context like build commands, code patterns, and conventions it discovered during initialization.

Attribution Settings

By default, Trapeze adds attribution information to Git commits and pull requests it creates. You can customize this behavior with the attribution option:

{
  "$schema": "https://raw.githubusercontent.com/amarbel-llc/trapeze/master/schema.json",
  "options": {
    "attribution": {
      "trailer_style": "co-authored-by",
      "generated_with": true
    }
  }
}

trailer_style: Controls the attribution trailer added to commit messages (default: assisted-by)
- assisted-by: Adds Assisted-by: Trapeze:[ModelID] as specified in the convention
- co-authored-by: Adds Co-Authored-By: Trapeze <trapeze@charm.land>
- none: No attribution trailer
generated_with: When true (default), adds 💘 Generated with Trapeze line to commit messages and PR descriptions

Custom Providers

Trapeze supports custom provider configurations for both OpenAI-compatible and Anthropic-compatible APIs.

Note

Note that we support two "types" for OpenAI. Make sure to choose the right one to ensure the best experience!

openai should be used when proxying or routing requests through OpenAI.
openai-compat should be used when using non-OpenAI providers that have OpenAI-compatible APIs.

OpenAI-Compatible APIs

Here’s an example configuration for Deepseek, which uses an OpenAI-compatible API. Don't forget to set DEEPSEEK_API_KEY in your environment.

{
  "$schema": "https://raw.githubusercontent.com/amarbel-llc/trapeze/master/schema.json",
  "providers": {
    "deepseek": {
      "type": "openai-compat",
      "base_url": "https://api.deepseek.com/v1",
      "api_key": "$DEEPSEEK_API_KEY",
      "models": [
        {
          "id": "deepseek-chat",
          "name": "Deepseek V3",
          "cost_per_1m_in": 0.27,
          "cost_per_1m_out": 1.1,
          "cost_per_1m_in_cached": 0.07,
          "cost_per_1m_out_cached": 1.1,
          "context_window": 64000,
          "default_max_tokens": 5000
        }
      ]
    }
  }
}

Anthropic-Compatible APIs

Custom Anthropic-compatible providers follow this format:

{
  "$schema": "https://raw.githubusercontent.com/amarbel-llc/trapeze/master/schema.json",
  "providers": {
    "custom-anthropic": {
      "type": "anthropic",
      "base_url": "https://api.anthropic.com/v1",
      "api_key": "$ANTHROPIC_API_KEY",
      "extra_headers": {
        "anthropic-version": "2023-06-01"
      },
      "models": [
        {
          "id": "claude-sonnet-4-20250514",
          "name": "Claude Sonnet 4",
          "cost_per_1m_in": 3,
          "cost_per_1m_out": 15,
          "cost_per_1m_in_cached": 3.75,
          "cost_per_1m_out_cached": 0.3,
          "context_window": 200000,
          "default_max_tokens": 50000,
          "can_reason": true,
          "supports_attachments": true
        }
      ]
    }
  }
}

Amazon Bedrock

Trapeze currently supports running Anthropic models through Bedrock, with caching disabled.

A Bedrock provider will appear once you have AWS configured, i.e. aws configure
Trapeze also expects the AWS_REGION or AWS_DEFAULT_REGION to be set
To use a specific AWS profile set AWS_PROFILE in your environment, i.e. AWS_PROFILE=myprofile trapeze
Alternatively to aws configure, you can also just set AWS_BEARER_TOKEN_BEDROCK

Vertex AI Platform

Vertex AI will appear in the list of available providers when VERTEXAI_PROJECT and VERTEXAI_LOCATION are set. You will also need to be authenticated:

gcloud auth application-default login

To add specific models to the configuration, configure as such:

{
  "$schema": "https://raw.githubusercontent.com/amarbel-llc/trapeze/master/schema.json",
  "providers": {
    "vertexai": {
      "models": [
        {
          "id": "claude-sonnet-4@20250514",
          "name": "VertexAI Sonnet 4",
          "cost_per_1m_in": 3,
          "cost_per_1m_out": 15,
          "cost_per_1m_in_cached": 3.75,
          "cost_per_1m_out_cached": 0.3,
          "context_window": 200000,
          "default_max_tokens": 50000,
          "can_reason": true,
          "supports_attachments": true
        }
      ]
    }
  }
}

Local Models

Local models can also be configured via OpenAI-compatible API. Here are two common examples:

Ollama

{
  "providers": {
    "ollama": {
      "name": "Ollama",
      "base_url": "http://localhost:11434/v1/",
      "type": "openai-compat",
      "models": [
        {
          "name": "Qwen 3 30B",
          "id": "qwen3:30b",
          "context_window": 256000,
          "default_max_tokens": 20000
        }
      ]
    }
  }
}

LM Studio

{
  "providers": {
    "lmstudio": {
      "name": "LM Studio",
      "base_url": "http://localhost:1234/v1/",
      "type": "openai-compat",
      "models": [
        {
          "name": "Qwen 3 30B",
          "id": "qwen/qwen3-30b-a3b-2507",
          "context_window": 256000,
          "default_max_tokens": 20000
        }
      ]
    }
  }
}

Logging

Sometimes you need to look at logs. Luckily, Trapeze logs all sorts of stuff. Logs are stored in ./.trapeze/logs/trapeze.log relative to the project.

The CLI also contains some helper commands to make perusing recent logs easier:

# Print the last 1000 lines
trapeze logs

# Print the last 500 lines
trapeze logs --tail 500

# Follow logs in real time
trapeze logs --follow

Want more logging? Run trapeze with the --debug flag, or enable it in the config:

{
  "$schema": "https://raw.githubusercontent.com/amarbel-llc/trapeze/master/schema.json",
  "options": {
    "debug": true,
    "debug_lsp": true
  }
}

Provider Auto-Updates

By default, Trapeze automatically checks for the latest and greatest list of providers and models from Catwalk, the open source Trapeze provider database. This means that when new providers and models are available, or when model metadata changes, Trapeze automatically updates your local configuration.

Disabling automatic provider updates

For those with restricted internet access, or those who prefer to work in air-gapped environments, this might not be want you want, and this feature can be disabled.

To disable automatic provider updates, set disable_provider_auto_update into your trapeze.json config:

{
  "$schema": "https://raw.githubusercontent.com/amarbel-llc/trapeze/master/schema.json",
  "options": {
    "disable_provider_auto_update": true
  }
}

Or set the TRAPEZE_DISABLE_PROVIDER_AUTO_UPDATE environment variable:

export TRAPEZE_DISABLE_PROVIDER_AUTO_UPDATE=1

Manually updating providers

Manually updating providers is possible with the trapeze update-providers command:

# Update providers remotely from Catwalk.
trapeze update-providers

# Update providers from a custom Catwalk base URL.
trapeze update-providers https://example.com/

# Update providers from a local file.
trapeze update-providers /path/to/local-providers.json

# Reset providers to the embedded version, embedded at trapeze at build time.
trapeze update-providers embedded

# For more info:
trapeze update-providers --help

Metrics

Trapeze records pseudonymous usage metrics (tied to a device-specific hash), which maintainers rely on to inform development and support priorities. The metrics include solely usage metadata; prompts and responses are NEVER collected.

Details on exactly what’s collected are in the source code (here and here).

You can opt out of metrics collection at any time by setting the environment variable by setting the following in your environment:

export TRAPEZE_DISABLE_METRICS=1

Or by setting the following in your config:

{
  "options": {
    "disable_metrics": true
  }
}

Trapeze also respects the DO_NOT_TRACK convention which can be enabled via export DO_NOT_TRACK=1.

Q&A

Why is clipboard copy and paste not working?

Installing an extra tool might be needed on Unix-like environments.

Environment	Tool
Windows	Native support
macOS	Native support
Linux/BSD + Wayland	`wl-copy` and `wl-paste`
Linux/BSD + X11	`xclip` or `xsel`

Contributing

See the contributing guide.

Whatcha think?

We’d love to hear your thoughts on this project. Need help? We gotchu. You can find us on:

License

FSL-1.1-MIT

Part of Charm.

Charm热爱开源 • Charm loves open source

Name		Name	Last commit message	Last commit date
Latest commit History 3,536 Commits
.agents/skills		.agents/skills
.github		.github
docs/hooks		docs/hooks
internal		internal
scripts		scripts
.gitattributes		.gitattributes
.gitignore		.gitignore
.golangci.yml		.golangci.yml
.goreleaser.yml		.goreleaser.yml
AGENTS.md		AGENTS.md
CLA.md		CLA.md
LICENSE.md		LICENSE.md
README.md		README.md
flake.lock		flake.lock
flake.nix		flake.nix
go.mod		go.mod
go.sum		go.sum
gomod2nix.toml		gomod2nix.toml
justfile		justfile
main.go		main.go
schema.json		schema.json
sqlc.yaml		sqlc.yaml
sweatfile		sweatfile
trapeze.json		trapeze.json
treefmt.nix		treefmt.nix

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Trapeze

Features

Installation

Getting Started

Subscriptions

By the Way

Configuration

LSPs

MCPs

Hooks

Sharing a workspace across clients

Ignoring Files

Allowing Tools

Disabling Built-In Tools

Disabling Skills

Agent Skills

User-Invocable Skills

Desktop notifications

Initialization

Attribution Settings

Custom Providers

OpenAI-Compatible APIs

Anthropic-Compatible APIs

Amazon Bedrock

Vertex AI Platform

Local Models

Ollama

LM Studio

Logging

Provider Auto-Updates

Disabling automatic provider updates

Manually updating providers

Metrics

Q&A

Why is clipboard copy and paste not working?

Contributing

Whatcha think?

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages