Settings

What the terminal itself acts on. Eight keys, and that is all of them.

// profile.config.ts
export default defineProfile({
    settings: {
        theme: "gruvbox",
        icons: "auto",
        paths: ["~/git/work/agents"],
        verbosity: { session: "normal" },
        padding: 0,
        telemetry: false,
    },
})

The set is closed on purpose. Each key has a meaning the platform enforces — theme names a registered theme, paths are scanned for agents — so an unknown key is a typo rather than a preference nobody reads. An open bag would make "is this setting doing anything?" unanswerable, which is the question a settings file exists to answer.

Extension settings live outside this, as their own top-level key on the profile config ("@cody/vim": { leader: "," }). An extension's settings are its own contract, and keeping them separate means a new platform key can never collide with one an extension already chose.

theme

export default defineProfile({
    settings: {
        // A built-in, or one an extension registered.
        theme: "gruvbox",
    },
})

The active theme, by the name it was registered under — a built-in, or one an extension registered with theme.create().

This is the one setting with a command behind it: picking a theme with " writes this line. Editing it by hand and picking it in the TUI are the same act.

icons

export default defineProfile({
    settings: {
        // "auto" | "nerd" | "unicode" | "none"
        icons: "auto",
    },
})

Which glyph set line components draw from.

A setting rather than code because it answers "what does this machine's font support" — a property of the terminal, not of the config. A line you share should look right on a laptop with a patched font and on a server without one, which cannot be true if the answer is compiled into the line.

auto is a heuristic, not a fact. A font cannot be detected from inside a terminal, so it reads the same environment the ecosystem does (TERM_PROGRAM, and whether a font name mentions "Nerd") and falls back to unicode when nothing says yes. The default is auto rather than off because Nerd Fonts are the de facto standard — lualine, starship, powerlevel10k and oh-my-posh all assume one — so defaulting them off would give most people a plainer bar than they installed a patched font for.

Seeing boxes? Set unicode. Seeing plain text where you expected glyphs? Set nerd.

paths

export default defineProfile({
    settings: {
        paths: ["~/git/work/agents", "~/experiments"],
    },
})

Extra directories scanned for agent projects, beyond profiles/<your-email>/agents/. ~ expands to your home directory.

Additive — the profile's own agents/ is always scanned. See agents/.

verbosity

export default defineProfile({
    settings: {
        verbosity: {
            // "quiet" | "normal" | "verbose"
            session: "normal",
            kernel: false,
            cognet: false,
        },
    },
})

What the timeline shows. The debugging dial: every default is the everyday view, and turning a channel on interleaves the machinery's own records into the conversation.

key	default	effect
`session`	`"normal"`	`quiet`: errors only. `normal`: + info, like reloads. `verbose`: + plumbing.
`kernel`	`false`	Interleave `kernel:*` telemetry — runs, engine calls.
`cognet`	`false`	Interleave `cognet:*` telemetry — ticks, phases, systems.

padding

export default defineProfile({
    settings: {
        padding: 1,
        // Each overrides `padding` on its own axis.
        "padding-inline": 4,
        "padding-block": 0,
    },
})

Blank space around the whole terminal UI, in cells. padding is shorthand for both axes; the per-axis keys override it where present, so { padding: 1, "padding-inline": 4 } reads as one row top and bottom, four columns each side.

The CSS names are spelled exactly. This config layer speaks CSS — VTerm mimics browser CSS, and you write scoped CSS in your own extensions — so where CSS already has a name for a thing, these settings use it verbatim rather than a near-synonym. There is nothing to translate between what you write here and what you write in a stylesheet.

padding-block is added to the layout's own one-row top offset rather than replacing it, so 0 is the shipped look. The status line is the bottom edge and sits flush by design; this is what lifts it off.

telemetry

export default defineProfile({
    settings: {
        telemetry: false,
    },
})

Not wired to anything yet. The key is accepted and stored, and nothing reads it. It is listed here because a settings page that quietly omitted a key you can see in your own config would be answering the wrong question — and because setting it today does nothing, which is worth knowing before you set it.

Edited by hand, or by command

Both work, and both take effect on save — the terminal watches the file. " writes theme; everything else is yours to edit.