Coven Documentation

Configuration reference for Coven Code, including settings files, environment variables, provider defaults, local state directories, and Coven daemon integration.

Coven Code stores TUI-specific state under ~/.coven-code and reads shared daemon state from COVEN_HOME when it uses the local Coven daemon.

State Directories

Path	Owner	Contains
`~/.coven-code/settings.json`	Coven Code	TUI settings, provider defaults, and feature preferences.
`~/.coven-code/projects/`	Coven Code	Project-scoped session transcripts and local session state.
`~/.coven-code/keybindings.json`	Coven Code	Custom keybindings.
`~/.coven-code/plugins/`	Coven Code	Local plugin manifests and plugin files.
`~/.coven`	Coven daemon	Daemon socket, session ledger, and shared Coven state.

Do not mix reset scopes

Removing ~/.coven-code resets Coven Code. Removing ~/.coven resets shared daemon state used by the CLI, Cave, and other clients. They solve different problems.

Settings Reference

~/.coven-code/settings.json accepts the keys below. Change them with /config in the TUI or by editing the file directly.

Display & Notifications

Key	Default	Purpose
`showCwd`	`true`	Show the current working directory in the footer.
`showGitBranch`	`true`	Show the git branch in the footer.
`notifications`	`true`	Enable desktop notifications.
`completionToast`	`true`	Show a toast when a background task or assistant turn finishes.
`bellOnComplete`	`false`	Ring the terminal bell when a background task or assistant turn finishes.
`showTurnDuration`	`false`	Show turn duration in output.
`reduceMotion`	`false`	Reduce motion in the UI.
`terminalProgressBar`	`true`	Show terminal progress bars.
`autoCopyOnHighlight`	`false`	Copy a drag selection to the system clipboard when the drag is released.

Context & File Handling

Key	Default	Purpose
`autoCompact`	`true`	Automatically compact the conversation as the context window fills.
`fileAutocompleteLimit`	`15`	Maximum number of file suggestions shown in autocomplete.
`fileAutocompleteShowHiddenFiles`	`false`	Show hidden files in file autocomplete.
`fileInjectionEnabled`	`true`	Automatically inject `@file` references into message context before sending.
`fileInjectionMaxSize`	`100`	Maximum file size to auto-inject, in KB. Set to `0` for no limit.

Structured Sections

Key	Default	Purpose
`provider`	unset	Active provider ID, such as `anthropic` or `codex`.
`providers`	empty map	Per-provider configurations.
`commands`	empty map	User-defined slash command templates.
`formatter`	empty map	Formatter configurations keyed by a user-defined name.
`agents`	empty map	Named agent definitions that override built-in defaults.
`familiar`	unset	Active familiar persona for the welcome screen and `/familiar`.
`skills`	empty	Skill-discovery configuration: extra paths and git URLs.
`managed_agents`	unset	Manager-executor (managed agent) architecture configuration.
`daemonLedger`	`false`	Register interactive sessions in the Coven daemon ledger (best-effort, opt-in).

Environment Variables

Variable	Purpose
`COVEN_CODE_PROVIDER`	Default provider, such as `anthropic` or `codex`.
`COVEN_CODE_API_BASE`	Override the provider API base URL.
`COVEN_CODE_SKIP_PROMPT_HISTORY`	Disable prompt history when set to `1`.
`COVEN_CODE_ANTHROPIC_OAUTH_CLIENT_ID`	Configure a registered Anthropic OAuth client for Coven Code auth login.
`ANTHROPIC_API_KEY`	Anthropic API key used by the Anthropic provider path.
`OPENAI_API_KEY`	OpenAI API key used by the Codex provider path when no stored credential exists.
`ANTHROPIC_BASE_URL`	Override the Anthropic API base URL.
`OPENAI_BASE_URL`	Override the OpenAI API base URL for the Codex provider.
`COVEN_HOME`	Coven daemon home. Defaults to `~/.coven`.
`COVEN_LEGACY_TUI`	Opt out of `coven` / `coven tui` exec behavior where legacy TUI support is available.

Provider Defaults

Set a default provider for new launches:

export COVEN_CODE_PROVIDER=codex
coven-code

Or choose explicitly per run:

coven-code --provider anthropic
coven-code --provider codex

Use /connect to manage accounts and /model to pick a model in the interactive UI.

Project Context

Coven Code runs from the current working directory unless a command or workflow changes it. Keep these boundaries in mind:

Project files and AGENTS.md-style instructions are read from the local project context.
Session state under ~/.coven-code/projects/ is project-scoped.
Daemon operations invoked through /coven still go through Coven's project-root and working-directory validation.

For daemon project-root rules, see Harness Project Roots and Working Directories.

Keybindings

Keybindings are stored in:

~/.coven-code/keybindings.json

Edit them through the TUI where possible. If you edit the file manually, restart Coven Code afterward so the current process reloads the new bindings.

Daemon Integration

The /coven command and welcome daemon status block use the typed daemon client over:

~/.coven/coven.sock

If you use a custom Coven home:

export COVEN_HOME=/path/to/coven-home
coven daemon status
coven-code

Make sure both the daemon command and the Coven Code process see the same COVEN_HOME. If they do not, the TUI may show no daemon sessions even though the CLI can see a different daemon.

Configuration

On this page