Skip to content
V3CodeV3Code
Start here

POPULAR GUIDES

    FROM THE DOCUMENTATION

    Open this guide ↗
    ↑ ↓ select ↵ open esc closeV3Code Docs
    The terminalterminal

    Configuration

    ↗ View as Markdown

    Where V3Code Terminal reads its settings from, how project and global config combine, and every option worth knowing.

    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

    Section titled “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/global

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

    .v3code/ in your projectproject

    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.

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

    Terminal window
    v3code debug config
    v3code debug paths

    A practical starting file

    Section titled “A practical starting file”
    {
      "$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

    Section titled “Options worth knowing”

    Models and agents

    Section titled “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

    Section titled “Behavior”
    Option What it does
    permission Approval rules per tool and pattern. See Permissions.
    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.
    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

    Section titled “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

    Section titled “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

    Section titled “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.

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

    Custom slash commands

    Section titled “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.

    ---
    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

    Section titled “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.

    Section titled “Related”

    Permissions & privacy covers the permission block in depth, Agents & subagents covers agent files, and Skills & instructions covers skill discovery.