Workspace settings

Each workspace has a small settings file that your team owns and keeps with the repository: .chronos/settings.toml. It is committed, PR-reviewable and never contains secrets. Chronos creates it with sensible defaults the first time you open a workspace.

.chronos/settings.toml

[workspace]
base_branch = "main"      # the branch sessions start from and are compared against
remote = "origin"         # the remote used when you open pull requests

# Named scripts your team defines (reviewed like any other code).
# Triggered by name from the dashboard or `chronos session run` — never free text.
[scripts]
setup   = "pnpm install"          # runs on session creation
run     = "pnpm dev"              # long-running dev command (reads CHRONOS_PORT)
run_mode = "server"               # how `run` behaves (e.g. `server`, `oneshot`)
archive = "pnpm clean"            # runs on session close
test    = "pnpm test"             # verification hook
verify  = "pnpm lint && pnpm test"# verification hook
qa      = "pnpm e2e"              # verification hook
pentest = "pnpm audit"            # verification hook

# Bind an issue tracker so you can seed a session straight from a ticket.
# Names a panel-registered connector by id — never a secret. Jira OR Linear.
[integrations.jira]
connector = "jira-acme"   # the connector id your admin registered in the panel
project_key = "PROJ"      # the "Execute issue" picker is scoped to this project

• base_branch — the branch new sessions branch from and are reviewed against.
• remote — the remote used when you open pull requests.
• worktrees_path (optional) — overrides the managed directory where session worktrees are created; otherwise they land in the visible ~/Chronos/workspaces/<repo-name>/, outside the repository, so anything a session produces is one file-browser hop from home.
• [scripts] — your project’s named commands (see Scripts and the secure terminal). Because they live with the repository, changes to them go through your normal review.
• [integrations] — bind a Jira board (connector, project_key, optional default_jql) or a Linear team (connector, team_key) so you can start a session from an issue. This only references a connector your administrator registered in the panel; no credential lives here. A workspace binds one tracker — if both sections are present, Jira wins.

Verification hooks and the merge gate

The test, verify, qa and pentest slots are the verification hooks. They feed the Checks view (chronos session check) and the merge gate: a red check blocks merge. See Pull requests, approvals and merge.

Local overrides — .chronos/settings.local.toml

You can keep personal, machine-specific overrides that are never shared with the team. They live at the workspace root (not inside a session worktree, so they persist across sessions) and are gitignored — they never reach the repository.

[scripts]
setup    = "npm install --prefer-offline"
run      = "npm run dev -- --port $CHRONOS_PORT"
run_mode = "server"

Only the ergonomic slots setup, run and run_mode are honored from the local file; a set value wins over the committed one, and a blank or missing value falls back to it. The merge-gate hooks (test/verify/qa/pentest) are committed-only — a local file can never weaken the gate, even if it defines them.

The per-session port — CHRONOS_PORT

When you start an app with the run script, Chronos allocates each session its own free loopback port (from the range 4100–4999) and passes it as the CHRONOS_PORT environment variable, so parallel sessions never collide. Have your run script read the port Chronos provides rather than using a fixed one:

[scripts]
run = "pnpm dev --port $CHRONOS_PORT"

See Environment variables for everything else Chronos reads from or puts into the environment.

Enterprise settings

Your organization’s governance — available agents and tools, applied standards and prompts, and who can approve and merge — is configured centrally by your administrators in the enterprise panel, not in this file.