Configuration

Config file: ~/.config/cctabs/config.toml

Created automatically on first run of cctabs config.

Options

[claude]
# Extra flags passed to every `claude` invocation.
flags = ["--allow-dangerously-skip-permissions"]

[defaults]
# Default workspace to open new sessions in. Inert on Tabby, which has no
# workspace concept — kept for config compatibility.
# workspace = ""

# Colour for every tab opened by new/resume/fork.
# color = ""

claude.flags

Flags appended to every claude command launched by cctabs new, cctabs resume, and cctabs fork.

The default config ships with --allow-dangerously-skip-permissions enabled — remove it if you prefer manual permission prompts.

Other examples:

[claude]
flags = ["--model", "sonnet", "--allow-dangerously-skip-permissions"]

defaults.workspace

If set, cctabs new will open tabs in this workspace by default (without needing -w).

[defaults]
workspace = "work"

defaults.color

Colour applied to every tab opened by cctabs new, resume and fork.

[defaults]
color = "blue"

Accepts Tabby's palette names — blue, green, orange, purple, red, yellow — plus none, or a hex value like "#0275d8". Precedence runs --color → the backend preset's own color → this. Empty (the default) leaves tabs uncoloured.

Colours survive a reboot: cctabs restore re-applies them, because it recreates a dead tab rather than reviving it and a fresh tab starts uncoloured. A tab whose colour wasn't recorded takes whatever the config implies for its backend, so this rule keeps holding for sessions captured before colours existed.

Requires a tabby-cctabs plugin advertising the tab-color capability; an older plugin warns once and opens the tab uncoloured rather than failing.

Backends

A backend preset is a named set of environment variables (plus an optional model) applied when a tab launches. Use it for a different model provider — or for a different Claude account entirely, e.g. keeping a client's usage separate from your own.

cctabs backends                      # list presets
cctabs new scratch ~/Dev/app -b kimi # launch a tab on one

Presets ship built in (Ollama-backed: kimi, qwen-cloud, gpt-oss, …) and can be added under [backends.<name>]. Two forms:

# A different model/provider — base_url + auth_token shorthand:
[backends.my-preset]
description = "My custom preset"
model = "qwen3-coder-next:cloud"
base_url = "http://localhost:11434"

# Full control via env_<NAME> — including a different Claude account:
[backends.client-x]
description = "Client X's Claude account"
env_CLAUDE_CONFIG_DIR = "/Users/you/.claude-client-x"

You don't write an account's preset by hand: cctabs account add client-x opens a tab where you sign in as that account with Claude's normal login, and writes the preset into this file. The login stays in that config dir's own Keychain entry, so the preset holds no token. cctabs account list shows the accounts.

Inheritance

A launched tab carries CCTABS_ACTIVE_BACKEND=<name>, so new / resume / fork run from inside that session default to the same preset instead of falling back to your default account. Explicit -b wins; -b anthropic forces the default back.

Multiple Claude accounts

A preset that sets env_CLAUDE_CONFIG_DIR puts its sessions in that directory rather than ~/.claude/projects. cctabs searches every config dir it knows about — the default one plus each one named by a preset — so those sessions show up in cctabs sessions, resume and restore like any other, and are relaunched under the account they belong to automatically.

This matters more than a missing-session error would: claude --resume <id> run against the wrong config dir doesn't fail, it just can't find that id and opens a fresh conversation. Carrying the account through is what prevents a restore that looks successful and isn't.

Give each account a color and which one a tab belongs to becomes visible in the tab bar instead of something to remember:

[backends.work]
env_CLAUDE_CONFIG_DIR = "/Users/you/.claude-work"
color = "blue"

A preset's color applies to every tab launched under it and overrides [defaults] color; --color still wins over both. Because the account is inferred from the config dir a session was found in, cctabs restore puts those tabs back blue after a reboot without anything having to be recorded per tab.

A common pairing is one colour per account plus a catch-all:

[defaults]
color = "orange"          # everything else

[backends.enterprise]
env_CLAUDE_CONFIG_DIR = "/Users/you/.claude-enterprise"
color = "blue"            # this account's tabs

Note [defaults] color is the right place for the catch-all, not [backends.anthropic]: a plain cctabs new foo resolves to no backend at all, so a colour on the anthropic preset only applies when you pass -b anthropic explicitly.

A [backends.<name>] section overlays the builtin preset of that name rather than replacing it, so you can add just a color to kimi or qwen-cloud without restating its base URL, token and model.

Check current config

cctabs config

Prints the config file path and current values.