Config reference

The schema is generated from src/core/schema.ts into config.schema.json — do not edit that file by hand. Point $schema at it for editor autocomplete:

{ "$schema": "./node_modules/titah-code/config.schema.json" }

Global config is ~/.config/titah/titah.json, merged with the project’s ./titah.json. The project file wins.

Top level

provider

"provider": {
  "<name>": {
    "npm": "@ai-sdk/openai-compatible",
    "options": { "baseURL": "https://…/v1", "apiKey": "${env:VAR}" },
    "models": {
      "<model-id>": { "name": "Human label", "contextWindow": 131072 }
    }
  }
}

permission

"permission": {
  "edit": "ask", "write": "ask", "bash": "ask",
  "network": "ask", "delete": "ask", "mcp": "ask",
  "external_directory": "deny",
  "doom_loop": "ask",
  "allowlist": ["git *", "npm test"],
  "rules": { "bash(git *)": "allow", "bash(git push *)": "deny" }
}

A rule-level deny is absolute; among ask and allow the most specific pattern wins, measured in non-wildcard characters rather than file order. Full rules in Permissions & undo.

agent

"agent": {
  "<id>": {
    "description": "Shown in /agents and to the coordinator",
    "prompt": "Extra system prompt for this agent",
    "model": "provider/model",
    "mode": "primary | subagent | all",
    "delegate": "<externalAgent name>",
    "tools": { "write": false },
    "permission": { "bash": "allow" },
    "skills": ["namespace:name"],
    "effort": "low | medium | high",
    "steps": 40
  }
}

externalAgent

"externalAgent": {
  "<name>": {
    "command": "aider",
    "args": ["--message", "{prompt}", "--no-stream"],
    "resumeArgs": [],
    "format": "stream-json | json | text",
    "sessionMode": "generate | discover",
    "specialist": "deep architectural reasoning, cross-module refactors",
    "timeout": 600000,
    "enabled": true
  }
}

skills

"skills": {
  "discover": ["claude", "opencode"],
  "paths": ["~/.config/opencode/skills", { "path": "./.titah/skills", "as": "team" }],
  "always": ["superpowers:using-superpowers"],
  "learn": { "enabled": false, "minTools": 8, "max": 30 }
}

Set discover to [] in tests or anywhere that must not read ~/.claude and ~/.config/opencode.

Full behaviour in Skills → Learned skills.

compaction

"compaction": { "auto": true, "reserved": 8192, "tailTurns": 2, "prune": true }

Full behaviour in Context & compaction.

search

"search": { "backend": "ddg | brave | tavily", "apiKey": "${env:BRAVE_API_KEY}" }

ddg needs no key and scrapes HTML, so it can break without warning — titah doctor says so.

diagnostics

"diagnostics": { "command": "npm run typecheck" }

Never guessed. A non-zero exit is a finding, not a tool failure.

mcp and lsp

"mcp": { "github": { "command": "mcp-server-github", "args": [] } },
"lsp": {
  "ts": { "command": "typescript-language-server", "args": ["--stdio"], "extensions": [".ts", ".tsx"] }
}

MCP is stdio only, tools only, namespaced <server>_<tool>. See MCP & language servers.

keybinds

"keybinds": { "session_interrupt": "ctrl+g", "tool_details": "none" }

Defaults follow opencode. "none" disables an action. See The TUI.

command

"command": {
  "review": {
    "template": "Review the code in {{.Input}} and suggest improvements",
    "description": "Quick code review",
    "agent": "explore"
  }
}

{{.Input}} follows opencode; $ARGUMENTS is accepted too. Built-in commands cannot be overridden.

account

"account": { "server": "https://titah.dev" }

Only the server address belongs here. The token does not — it lives in ~/.local/share/titah/account.json at mode 0600, for the same reason as provider keys: the config is the file people paste into GitHub issues.

Resolution order is $TITAH_ACCOUNT_SERVER, then this key, then the built-in default https://titah.dev. See Account & sign-in.

limits

"limits": {
  "turnTokens": 400000,
  "sessionTokens": 2000000,
  "continueTurns": 5
}

Full behaviour in Cost & limits.

delegation

"delegation": "ask"

"ask" (default), "auto", "always", or "never". "never" does not even send the roster to the model, so no tokens go on a list nobody uses. See Modes & custom agents.

hooks

"hooks": {
  "tool.before": [{ "match": "^bash$", "run": "scripts/guard.sh", "timeout": 30000 }],
  "tool.after":  [{ "match": "edit|write", "run": "npm run format" }]
}

match is a regex over the tool name; omit it to match every tool. timeout defaults to 30000 ms. tool.before refuses the call on a non-zero exit; tool.after cancels nothing but appends its stderr to the tool output. See Hooks.

sandbox

"sandbox": { "bash": false, "network": true }

See Sandbox.

plugin

"plugin": {
  "@acme/titah-audit": { "options": { "file": "audit.log" } },
  "./plugin/lock-migrations.mjs": {},
  "market:prettier": {}
}

Named one by one, never auto-discovered from node_modules — plugins run unsandboxed inside Titah’s process, and “installed” is not “trusted”. "enabled": false means the module is not imported at all. See Plugins.

panel and extension

"panel": {
  "floor": 40,
  "boxFloor": 2,
  "left":  { "width": 20 },
  "right": { "width": 20 }
},
"extension": {
  "@titah/extension-git":   { "side": "right" },
  "@titah/extension-tests": { "side": "right", "rows": 6 },
  "./panel/notes.mjs":      { "side": "left", "collapsed": true, "key": "n" }
}

A side is a stack: extensions listed for the same side are drawn as separate boxes, top to bottom in config order — the only order you can see and change. Extensions run unsandboxed in the TUI process, so like plugin they are named one by one and never auto-discovered. See Extensions.

instructions and scaffold

"instructions": "titah-instruction.md"
"instructions": { "path": "titah-instruction.md" }
"instructions": ["a.md", { "path": "b.md" }]

All three forms mean the same thing. The single form is accepted because it is what people write first, and the object form follows skills.paths, which already takes string | { path } — two axes pointing at files should be written the same way.

Declared files that do not exist are created on the first turn of a session, and a project with no instruction file at all gets a starter AGENTS.md.

"scaffold": false

turns all of that off — nothing is written that you did not ask for. See Project instructions.

tracking

"tracking": {
  "enabled": true,
  "exclude": ["~/clients/*"],
  "git": true,
  "sync": false
}

Per-project opt-out needs nothing here — put {"tracking": {"enabled": false}} in that project’s ./titah.json. Full behaviour in Project tracking.

artifacts

"artifacts": {
  "enabled": true
}

On by default, unlike tracking.sync, and the difference is not an inconsistency. sync uploads automatically, with nobody in the loop, so it has to be switched on deliberately. Publishing a page happens only when the model asks and the network permission dialog — naming the host, the title and the byte count — is approved. You are in the loop every single time, so a switch that started off would add a step without protecting anything.

Set it to false to remove the tool from the roster entirely. Full behaviour in Artifacts.

Checking your config

titah config path    # where the files are
titah config show    # the merged result, credentials redacted
titah doctor         # plus what resolved, what did not, and what is missing