Skip to main content

​
Configure .trellis/config.yaml

.trellis/config.yaml is the project-level configuration file for Trellis runtime behavior. It controls session journal commits, task lifecycle hooks, package mapping, and Codex dispatch mode. Track this file with the repo. Treat it as shared team configuration, not as a place for per-machine identity or secrets. Per-machine identity belongs in .trellis/.developer; credentials should stay in environment variables or your normal secret manager.

​
Edit safely

Most sections are optional. Leave commented examples commented until you need them, and edit only the keys your project actually uses. Use normal YAML values:
When a key is absent, Trellis uses its built-in default. Keep indentation consistent for nested blocks such as hooks, packages, and codex.
Hook commands live in tracked project configuration. Do not put tokens, API keys, or machine-specific absolute paths in .trellis/config.yaml.

​
Current keys

​
Session recording

session_commit_message and max_journal_lines apply to session journal recording:
Use session_commit_message if your repo has a conventional commit style for Trellis journal commits. Use max_journal_lines to keep .trellis/workspace/<developer>/journal-N.md files at a reviewable size.

​
Session auto-commit

session_auto_commit controls whether Trellis scripts touch git for journal and task archive bookkeeping:
Default true preserves the normal behavior: add_session.py and task.py archive write files, stage the Trellis changes, and create bookkeeping commits. Set it to false when .trellis/ is intentionally gitignored or when your team wants to review and commit Trellis bookkeeping manually. Accepted values are true, false, yes, no, 1, 0, on, and off (case-insensitive). Invalid values fall back to true and print a warning.

​
Task lifecycle hooks

hooks runs shell commands after task lifecycle events. Each command receives TASK_JSON_PATH, pointing at the task’s task.json.
Supported events are after_create, after_start, after_finish, and after_archive. Hook failures print a warning but do not block the main task operation.

​
Packages and default package

packages declares project structure for monorepos and repos with multiple working directories:
Use type: submodule for git submodules. Use git: true when a subdirectory is its own independent git repository, as in polyrepo or meta-repo layouts. default_package must match a key under packages. Trellis uses it when a task or command does not specify a package.

​
Update skip compatibility

update.skip is still supported for projects that already use it, even though the current template no longer includes a commented example:
During normal trellis update runs, skipped paths are excluded from template writes and safe-file-delete cleanup. During breaking migrations that you run with --migrate, Trellis can bypass update.skip for migration-required cleanup so the project does not stay half-updated; the update command prints a warning before doing this.

​
Codex dispatch mode

codex.dispatch_mode is only read by Codex workflows. Other platforms ignore it.
inline keeps implementation and checking in the main Codex agent. sub-agent opts into the older dispatch model where the main agent launches trellis-implement, trellis-check, or trellis-research sub-agents. The default is inline because Codex sub-agents run in isolated turns and cannot inherit the parent session’s full task context. Use sub-agent only when you explicitly want that legacy split.

​
Update behavior

trellis init writes the current template for new projects. For existing projects, trellis update preserves local edits to .trellis/config.yaml instead of replacing the file wholesale. When a release adds a new config section, the migration manifest can declare it through configSectionsAdded. During trellis update, Trellis checks whether the configured sentinel text already appears in the target file. If the sentinel is missing, Trellis appends the matching section from the bundled template to the end of .trellis/config.yaml. This append-only path is idempotent and preserves your existing values. The session_auto_commit section was delivered this way for existing projects: if session_auto_commit: was missing, trellis update appended the commented section; if it was already present, update skipped it. After an update, review any appended commented section and uncomment only the keys you want to activate.