# Configuration

Everything is configurable from a JSON file, and nothing has to be. V3Code Terminal runs with sensible defaults — configuration is for when you want a specific model, tighter permissions, or your own agents and commands.

## Where configuration lives

Two levels, and they merge. Global settings apply everywhere; project settings apply to one repository and win where they overlap.

### \~/.config/v3code/

Your personal defaults for every project. Holds `v3code.json`, plus `agent/`, `command/`, and `skill/` folders.

### .v3code/ in your project

Settings for this repository, usually committed so your team shares them. Same layout as the global folder.

A `v3code.json` or `v3code.jsonc` file at the root of your project works too. Files are searched from your current directory upward, stopping at the worktree root, so a config in a subfolder can refine the one above it.

> Note:
>
> `opencode.json`, `opencode.jsonc`, and `.opencode/` are still read as compatibility aliases, and `OPENCODE_*` environment variables are accepted alongside `V3CODE_*`. New setups should use the `v3code` names.

To see exactly what V3Code resolved — after every file and override merged:

```bash
v3code debug config
v3code debug paths
```

## A practical starting file

```jsonc
{
  "$schema": "https://v3code.dev/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5",
  "default_agent": "build",
  "instructions": ["./docs/conventions.md"],
  "permission": {
    "edit": "ask",
    "bash": {
      "*": "ask",
      "git status*": "allow",
      "rm *": "deny",
    },
  },
}
```

`.jsonc` files — and `.json` files here — accept comments and trailing commas.

## Options worth knowing

### Models and agents

| Option                                     | What it does                                                                                                            |
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| `model`                                    | The default model, as `provider/model`.                                                                                 |
| `small_model`                              | A cheaper model for small internal jobs like session titles.                                                            |
| `default_agent`                            | Which agent a new session starts in.                                                                                    |
| `agent`                                    | Override any built-in agent — `plan`, `build`, `general`, `explore`, and the internal `title`, `summary`, `compaction`. |
| `provider`                                 | Per-provider settings and custom endpoints.                                                                             |
| `disabled_providers` / `enabled_providers` | Narrow which providers appear at all.                                                                                   |

### Behavior

| Option         | What it does                                                                               |
| -------------- | ------------------------------------------------------------------------------------------ |
| `permission`   | Approval rules per tool and pattern. See [Permissions](/terminal/permissions-and-privacy). |
| `instructions` | Extra instruction files to load, by path or glob.                                          |
| `command`      | Custom slash commands defined inline.                                                      |
| `skills`       | Extra skill folders (`paths`) and skill URLs (`urls`).                                     |
| `mcp`          | MCP servers, local or remote. See [MCP servers](/terminal/mcp-and-tools).                  |
| `plugin`       | Plugins to load.                                                                           |
| `snapshot`     | Whether file snapshots are taken, enabling revert.                                         |
| `share`        | `manual`, `auto`, or `disabled` for session sharing.                                       |
| `autoupdate`   | `true`, `false`, or `"notify"`.                                                            |

### Environment and tooling

| Option                                | What it does                                       |
| ------------------------------------- | -------------------------------------------------- |
| `shell`                               | The shell used for the terminal and the bash tool. |
| `formatter`                           | Formatters to run on edited files.                 |
| `lsp`                                 | Language server configuration.                     |
| `watcher.ignore`                      | Paths the file watcher should skip.                |
| `logLevel`                            | How much detail goes into the logs.                |
| `username`                            | The name the agent calls you.                      |
| `tool_output.max_lines` / `max_bytes` | Cap how much tool output enters the context.       |

### Compaction

When a session approaches the model's context limit, V3Code condenses the earlier part instead of failing.

| Option                              | Default | What it does                                   |
| ----------------------------------- | ------- | ---------------------------------------------- |
| `compaction.auto`                   | `true`  | Compact automatically when context fills.      |
| `compaction.prune`                  | `false` | Drop old tool outputs.                         |
| `compaction.tail_turns`             | `2`     | Recent user turns kept word-for-word.          |
| `compaction.preserve_recent_tokens` | —       | Token ceiling on what's kept verbatim.         |
| `compaction.reserved`               | —       | Buffer left free so compaction itself can run. |

## Instruction files

Beyond `instructions`, V3Code picks up instruction files automatically — the same `AGENTS.md` convention the editor uses.

It reads a global `AGENTS.md` from your config directory (or `~/.claude/CLAUDE.md`), then looks for a project file: `AGENTS.md`, then `CLAUDE.md`, then the deprecated `CONTEXT.md`.

> Note:
>
> **The first project-level match wins.** V3Code does not stack an `AGENTS.md` from every folder up the tree — one project file is used, so instructions can't silently pile up.

Entries in `instructions` may be relative paths, absolute paths, globs, `~/` paths, or `https://` URLs.

## Custom slash commands

Drop a markdown file into a `command/` folder and it becomes a slash command. `.v3code/command/review.md` becomes `/review`; a file in a subfolder becomes a namespaced name.

```markdown
---
description: Review staged changes before committing
---

Run `git diff --staged`, then review the changes for defects,
missing error handling, and anything touching auth or user input.
```

Commands can also be declared inline under `command` in `v3code.json`.

## Where your data sits

V3Code follows the XDG layout, so nothing lands in surprising places:

| Location                 | Contents                                |
| ------------------------ | --------------------------------------- |
| `~/.config/v3code/`      | Configuration, agents, commands, skills |
| `~/.local/share/v3code/` | Sessions, logs, plans, repositories     |
| `~/.cache/v3code/`       | Downloaded skills, binaries             |
| `~/.v3code/semanticdb/`  | The local semantic index                |

Run `v3code debug paths` to print the resolved locations on your machine.

## Related

[Permissions & privacy](/terminal/permissions-and-privacy) covers the permission block in depth, [Agents & subagents](/terminal/agents) covers agent files, and [Skills & instructions](/terminal/skills) covers skill discovery.