Configuration

Configuration

Settings are camelCase JSON fields. The tables below use v2.3.24 runtime defaults, not the illustrative values in the full example. Existing explicit values survive upgrades; an older installation does not automatically adopt every new default.

Choose and edit the file

Config selection is --config <PATH> → non-empty CODEXIFY_CONFIG → existing ~/.codexify/codexify.config.json → built-in defaults. Relative explicit paths resolve from the process startup directory. A missing explicitly selected file does not fall through to another config.

codexify config path
codexify config get agentChat.defaultMessageMode
codexify config set agentChat.automation.automaticRetries false
codexify config edit

These commands inspect stored JSON, not an expanded effective config. Keep raw output private. The owner interface's global Settings editor shows inherited defaults separately and saves overrides without materializing every default.

Minimal shape (replace the path):

{
  "workDir": "/absolute/path/to/projects"
}

The full example covers every supported field and disabled sample upstreams. Its paths, IDs, URLs, and selected event values are examples, not a ready-to-run default file.

Lifecycle and migration

Current schemaVersion is 1. Unversioned config is treated as schema 0. Startup and mutating config commands validate a migration before atomic replacement, preserve permissions, and retain a byte-for-byte *.before-schema-vN.bak. Read-only config inspection/doctor does not rewrite it. Newer unsupported schemas and ambiguous migrations are rejected.

Legacy markdownChat migrates to agentChat, review to diff, and removed command-allowlist/old artifact-cache fields are discarded. multiProject and --multi-project cannot disable current workspace selection. agentChat.analyticsEnabled is ignored; collection is always active. Use experimental.* for current annotation overrides.

Settings indicates when a restart is required. The global Automatic retries policy, progress-journal controls, turn renewal, message mode, and Extras preferences apply live. Offline timeout and retry-timing changes require a restart. Annotation hints also apply live. Schema-affecting changes queue connector refresh after a ten-second debounce; restart-required changes wait for restart first. The running server, refreshed connector, and an older conversation schema remain distinct states.

General, access, and transport

Setting	Default / meaning when omitted	Purpose
schemaVersion	1 for newly written current config	Persisted config schema, migrated with backup.
workDir	Required at runtime	Absolute existing project access root, or supply --work-dir.
instanceName	null	Optional display title, at most 128 characters with no controls. Null/blank preserves existing appearance; not a connector-name setting.
debug	true	Expose bounded operational debug metadata to widgets; independent of log switches.
uiWidgets	true	Serve built-in setup/chat/diff/update apps and private helpers. Turning it off does not remove ordinary tool authority.
port	3000	MCP port, distinct from agentChat.port.
projectCloneDir	Access root	Clone destination inside the access root.
apiKey	null	Optional static bearer in external HTTP mode; cannot be combined with native tunnels.
conversationAuthToken	null	Optional exact 64-lowercase-hex credential for per-conversation setup authorization.
allowedHosts	[]	External HTTP Host allowlist; native mode enforces loopback hosts.
openaiTunnel	Unset / no native tunnel	Optional single native tunnel object.
openaiTunnels	Unset; do not configure an empty array	Alternative array of 1–8 tunnel objects; cannot combine with the single-tunnel object or tunnel CLI overrides.

Tunnel object fields

Use these fields under openaiTunnel or in each openaiTunnels[] element. Platform permissions and secret handling are in Connecting to ChatGPT.

Setting	Default / meaning when omitted	Purpose
openaiTunnel.tunnelId	Required when this object is configured	Existing tunnel identity.
openaiTunnel.apiKeyRef	"env:CONTROL_PLANE_API_KEY"	Only an env:NAME or file:/path reference, not a literal key.
openaiTunnel.clientPath	Automatic managed runtime	Explicit compatible official tunnel client instead of the pinned managed install.
openaiTunnel.organizationId	Unset	Optional Platform organization passed by the runtime.
openaiTunnels[].tunnelId	Required per element	Same identity field in multi-tunnel configuration.
openaiTunnels[].apiKeyRef	"env:CONTROL_PLANE_API_KEY"	Use separate key references for independently configured connections.
openaiTunnels[].clientPath	Automatic managed runtime	Same client override as the single-tunnel form.
openaiTunnels[].organizationId	Unset	Same organization override as the single-tunnel form.

Workspaces and catalogue

Setting	Default / meaning when omitted	Purpose
worktrees.mode	"auto"	auto, always, or never; explicit selection can override it.
worktrees.root	Codex Desktop preference, else $CODEX_HOME/worktrees	Managed worktree parent; CLI/config overrides inherited preference.
worktrees.upstreamRefreshMode	"best-effort" built-in	best-effort or never, with native preferences used when configured.
worktrees.autoCleanupEnabled	true	Clean old unreferenced managed worktrees at startup; referenced/dirty checkouts are preserved.
worktrees.keepCount	15	Newest unreferenced worktrees retained before cleanup considers older ones.
worktrees.allowSetupScript	false	Permit arbitrary repository-influenced worktree setup-script execution.
projectCatalog.codexConfig.enabled	true	Read Codex user project candidates; independent of MCP import.
projectCatalog.codexConfig.trustedOnly	true	Filter native candidates to trusted entries; does not grant outside-root access.
projectCatalog.entries	[]	Explicit paths and searchable semantic metadata.
projectCatalog.entries[].path	Required per entry	Absolute authorized path or selector relative to the access root.
projectCatalog.entries[].name	Canonical directory basename	Display name.
projectCatalog.entries[].aliases	[]	Additional search names.
projectCatalog.entries[].description	Unset	Searchable project purpose.

See Workspace selection and Worktree isolation.

Agent chat, automation, and notifications

Setting	Default / meaning when omitted	Purpose
agentChat.enabled	true	Expose chat, progress, attachment, pairing, and goal tools and the owner listener.
agentChat.port	3120	Loopback owner-chat listener. Null requests an OS-assigned port; must differ from MCP port.
agentChat.maxWaitMs	55000	Default chat_await, turn_completed, and ticket_wait wait, 1,000–300,000 ms. Long waits must also fit transport deadlines.
agentChat.offlineTimeoutMinutes	5	Whole minutes 1–1,440 for offline display, queue delivery, goal recovery, notifications and active-time eligibility; restart required.
agentChat.defaultMessageMode	"queue"	queue or steer; a requested answer is delivered directly regardless of the default.
agentChat.rolloutEnabled	true	Enable the progress journal without deleting existing reports when disabled.
agentChat.rolloutReminderInterval	25	Work-call interval, 1–10,000; app polling, chat waits/completion, goal finishing, pairing verification and ticket waits do not count.
agentChat.automation.enabled	true	Enable browser fallback; installation, sign-in, exact connector name, and pairing are still required.
agentChat.automation.connectorName	""	Exact installed ChatGPT connector/plugin name. No assumed default; required before new-chat/goal work.
agentChat.automation.descriptorPath	"~/.codexify/browser/descriptor.json"	Private companion connection descriptor; absolute or ~/ path.
agentChat.automation.maxQueuedActions	64	Shared browser queue capacity, 1–1,024.
agentChat.automation.autoApproveToolCalls	true	Handle eligible verified connector approvals, including conversation-scoped file materialization.
agentChat.automation.automaticRetries	true	Live global retry policy. Initial actions and manual retries remain available when false.
agentChat.automation.chatgptProjectUrl	Unset	Optional HTTPS ChatGPT project URL ending in /project for newly created chats.
agentChat.automation.requestBlockingEnabled	false	Enable the stored request-blocking patterns; restart required.
agentChat.automation.requestBlockList	Five registration/sidebar/list patterns; see note below	Up to 128 printable-ASCII regex patterns; inactive while blocking is off.
agentChat.turnRenewal.enabled	false	Opt into timed handoff-and-continuation; independent of journal and goals.
agentChat.turnRenewal.limits	Bundled model pairs: 55 min, except GPT-5.6 Sol Pro at 115 min	Per-model/effort limits; unlisted/disabled pairs are not renewed.
agentChat.turnRenewal.limits[].model	Required per entry	Exact supported model identifier.
agentChat.turnRenewal.limits[].effort	Required per entry	Exact effort identifier; actual selected model/effort including fallback is used.
agentChat.turnRenewal.limits[].minutes	Required per entry	Positive turn duration, 1–1,440 minutes.
agentChat.turnRenewal.limits[].enabled	true	Independent enablement; older entries without this field remain enabled.
agentChat.notifications	null	Optional Apprise delivery configuration. No notifications until a usable destination is configured.
agentChat.notifications.urls	Required 1–32 URLs when configured	Apprise service URLs; credentials in them are sensitive.
agentChat.notifications.pythonPath	python3 (Unix), python (Windows)	Python executable with Apprise installed.
agentChat.notifications.timeoutMs	15000	Provider subprocess deadline, 1,000–60,000 ms.
agentChat.notifications.events.messages	true	Ordinary agent messages/progress. Event filters matter only when notifications are configured.
agentChat.notifications.events.completed	true	Explicit completed chat/goal events. Event filters matter only when notifications are configured.
agentChat.notifications.events.inputRequired	true	Requests for user input or needed approval. Event filters matter only when notifications are configured.
agentChat.notifications.events.goalBlocked	true	Blocked goal with reason. Event filters matter only when notifications are configured.
agentChat.notifications.events.errors	true	Failures without an automatic retry pending. Event filters matter only when notifications are configured.
agentChat.notifications.events.offline	true	Inactivity transitions at agentChat.offlineTimeoutMinutes. Event filters matter only when notifications are configured.

Notification event defaults are true when the event block is omitted. The full example explicitly turns some events off; those example choices are not the runtime defaults.

Default request-block patterns (the switch is off):

^https?://(www\.)?chatgpt\.com/.*/rgstr
^https?://(www\.)?chatgpt\.com/backend-api/.*/conversations
^https?://(www\.)?chatgpt\.com/backend-api/conversations
^https?://(www\.)?chatgpt\.com/backend-api/sidebar
^https?://(www\.)?chatgpt\.com/backend-api/.*/sidebar

See Agent chat and Browser automation for timing, retries, and queue semantics.

Retry timing fields

All fields are under agentChat.automation.retryTimings; values are seconds except jitterPercent. Arrays contain 1–32 delays, each a whole number from 1–86,400. Scalar delays use the same seconds range; jitter accepts 0–100. A timing edit requires restart. These are failure/recovery budgets, separate from the offline inactivity timeout.

Setting	Default	Purpose
agentChat.automation.retryTimings.actionDelaysSeconds	[30,60,120,240,480]	Eligible confirmed-unsent action failures.
agentChat.automation.retryTimings.chatgptAccessDelaysSeconds	[180,300,600,1200,1800,3600]	Eligible sign-in, conversation-access and editor-insertion failures.
agentChat.automation.retryTimings.goalRecoveryDelaysSeconds	[60,120,240]	Guarded goal/renewal recovery after a turn was accepted or did not produce activity.
agentChat.automation.retryTimings.jitterPercent	10	Maximum positive jitter applied to deadlines.
agentChat.automation.retryTimings.approvalResumeGraceSeconds	180	Wait for an approved existing turn to resume.
agentChat.automation.retryTimings.conversationLoadIntervalSeconds	180	Shared normal conversation-load interval.
agentChat.automation.retryTimings.conversationUnavailableCooldownSeconds	300	Shared cooldown after unavailable-conversation failures.
agentChat.automation.retryTimings.rateLimitCooldownSeconds	180	Shared cooldown after rate limiting.

An existing cooldown does not count as an attempt or consume a failure retry. The waiting bar shows its countdown and queue position, with Do now and Cancel controls. See Browser automation.

Extras

Setting	Default / meaning when omitted	Purpose
agentChat.extras.achievements	true	Show achievement celebrations.
agentChat.extras.animations	true	Use celebration animations; reduced motion is also respected.
agentChat.extras.sounds	true	Allow local celebration sound after browser user interaction.
agentChat.extras.weeklyRecap	true	Show weekly recap popups.
agentChat.extras.dailyStreaks	true	Show daily streak celebrations.
agentChat.extras.personalRecords	true	Show personal-record celebrations.

These live presentation switches do not disable statistics collection or sharing. See Analytics.

Output, execution, and filesystem workers

Setting	Default / meaning when omitted	Purpose
tree.defaultDepth	3	Default tree depth.
tree.ignore	["node_modules",".git","dist",".next","__pycache__"]	Legacy ignore patterns used with the shared ignore policy.
ignore.useGitignore	true	Use .gitignore and Git exclude rules.
ignore.useDefaultPatterns	true	Skip built-in generated/cache paths.
ignore.customPatterns	[]	Additional gitignore-style patterns.
command.defaultTimeout	30000	Legacy accepted value; does not set an exec_command timeout.
command.maxTimeout	120000	Deadline for enabled worktree environment setup scripts; not a shell allowlist.
exec.maxSessions	8	Concurrent resident command sessions per task/conversation.
exec.idleTimeoutMs	300000	Idle session expiry; zero disables idle reaping.
exec.defaultShell	$SHELL, else platform fallback	Recognized installed shell used when a call names none.
filesystem.maxConcurrentWorkers	8	Shared filesystem-worker concurrency.
filesystem.maxPendingRequests	16	Shared pending request cap.
filesystem.maxScanBytes	67108864	Bytes actually scanned by one filesystem operation.
filesystem.maxScanEntries	100000	Directory enumeration budget.
filesystem.maxLineBytes	1048576	Input line-prefix cap, independent of output limits.
output.maxToolOutputTokens	10000	Approximate independent caps for model-visible text and structured content.
output.maxFileLines	1000	Maximum read_file window lines.
output.maxFileBytes	131072	Maximum bytes for a file read window.
output.maxEntries	500	Result entries for bounded listing/search tools.
output.maxTreeNodes	1000	Nodes returned by a tree walk.
diff.maxPatchBytes	4194304	Complete diff patch cap; zero disables patch bodies.
diff.commandTimeoutMs	30000	Checkpoint initialization, lock wait, and Git helper deadline, 1–120,000 ms.

Filesystem calls have their own optional timeoutMs tool argument (30 seconds by default), including queue/spawn/work. Shell commands remain unrestricted and use pipes, not a PTY. See Tools reference.

Project instructions, skills, and memory

Setting	Default / meaning when omitted	Purpose
projectDoc.maxBytes	32768	Instruction byte budget; zero disables project-doc loading.
projectDoc.fallbackFilenames	[]	Fallbacks after AGENTS.override.md and AGENTS.md.
projectDoc.rootMarkers	[".git"]	Legacy setting; current discovery stays at the selected workspace.
skills.enabled	true	Enable skill discovery and reads.
skills.dirs	Automatic .agents / .codex user roots	Replace standalone user roots; project roots remain separate.
skills.includePlugins	Normally true; dependent on explicit dirs	Explicit dirs disable plugin discovery unless this is explicitly true.
memory.enabled	true	Persist plan/notes; independent of chat and workspace-binding persistence.
memory.dir	Workspace-keyed private state directory	Project/task memory base; use private storage outside source trees.
memory.maxBytes	16384	Notes byte budget; oversized notes fail rather than evicting old ones.

See AGENTS.md and skills and Context and memory.

Diagnostics and audit

Setting	Default / meaning when omitted	Purpose
toolLogging.mode	"all"	Bounded payload previews: off, requests, responses, all.
toolLogging.level	"info"	Tool lifecycle/payload severity.
toolLogging.maxRequestBytes	2048	Request preview bytes, 64–65,536.
toolLogging.maxResponseBytes	4096	Response preview bytes, 64–65,536.
toolLogging.redactEnv	[]	Additional environment values to redact.
audit.enabled	true	Disable with false; a path is not mandatory while disabled.
audit.logFile	~/.codexify/projects/<access-root-key>/audit.jsonl	Relative explicit paths resolve from launch directory.
audit.includeCommandPreview	true	Bounded command text with best-effort redaction.
audit.commandPreviewMaxBytes	512	Preview length, 1–16,384 bytes.
audit.redactEnv	[]	Additional environment values to redact in command previews.

Logging is enabled by default on new installations. To opt out explicitly: toolLogging.mode: "off", audit.enabled: false. See Audit logging before sharing diagnostic output.

File import and materialization

Setting	Default / meaning when omitted	Purpose
artifactIngress.enabled	true	Advertise native ChatGPT attachment import.
artifactIngress.maxFileBytes	104857600	Maximum import bytes (100 MiB).
artifactIngress.requestTimeoutMs	120000	Whole import deadline.
artifactIngress.idleTimeoutMs	30000	Body-chunk idle deadline, no greater than the whole deadline.
artifactIngress.maxRedirects	3	Validated redirects, 0–10.
artifactIngress.maxConcurrentDownloads	8	Process-wide concurrent downloads, 1–16.
artifactIngress.allowedHosts	["*"]	Wildcard admits public HTTPS; named hosts/subdomains add explicit trust.
artifactEgress.enabled	false	Opt into native export, attachment resources, and bridged file-resource materialization.
artifactEgress.maxFileBytes	104857600	Maximum native/proxied resource read (100 MiB).
artifactEgress.snapshotMaxFileBytes	104857600	Native source size eligible for an immutable snapshot.
artifactEgress.maxSnapshotBytes	5368709120	Global immutable native snapshot budget (5 GiB).
artifactEgress.fallbackToSource	true	If no snapshot remains, permit a new safe read from the recorded source; bytes can be newer.
artifactEgress.maxReferences	64	Live bridged-resource cap, 1–1,024; not a native snapshot-record limit.
artifactEgress.referenceTtlMs	300000	Bridged-resource lifetime; native capabilities are durable instead.

Materialization defaults off. Uploads and inline text/image attachment content remain usable. Opting in changes the tool/resource schema and can trigger host approval prompts. See Security model.

MCP discovery and explicit upstreams

Setting	Default / meaning when omitted	Purpose
codexMcp.enabled	true	Import Codex MCP configuration; independent of the project catalogue.
codexMcp.useCli	true	Use bounded CLI/plugin enrichment in addition to config-file parsing.
codexMcp.cliPath	CODEX_CLI_PATH, else codex on PATH	CLI executable for enrichment.
mcpServers	{}	Explicit entries or same-name overlays on imported servers.
Setting	Default / meaning when omitted	Purpose
---	---	---
mcpServers.<name>.command	Required for stdio	Executable for stdio.
mcpServers.<name>.args	[]	Process arguments.
mcpServers.<name>.env	{}	Child environment map; values can be sensitive.
mcpServers.<name>.cwd	Inherited process cwd	Child working directory.
mcpServers.<name>.disabled	false	Skip without deleting this entry.
mcpServers.<name>.type	Inferred	stdio or supported HTTP alias; infer when unambiguous.
mcpServers.<name>.url	Required for HTTP	Streamable HTTP endpoint.
mcpServers.<name>.bearerTokenEnvVar	Unset	Environment name containing HTTP bearer.
mcpServers.<name>.httpHeaders	{}	Static headers; keep secrets out of version control.
mcpServers.<name>.envHttpHeaders	{}	Header names mapped to environment-variable names.
mcpServers.<name>.startupTimeoutSec	20	Initialization/list-tools timeout in seconds.
mcpServers.<name>.toolTimeoutSec	60 when not overridden	Forwarded tool deadline in seconds.
mcpServers.<name>.tools	All tools	Allowlist of original upstream tool names.
mcpServers.<name>.disabledTools	None	Denylist after the allowlist.
mcpServers.<name>.mode	Explicit entry: direct; imported server: catalog	direct, gateway, or catalog.
mcpServers.<name>.requestLimits.maxConcurrentRequests	4	Per-upstream in-flight limit, 1–64.
mcpServers.<name>.requestLimits.maxPendingRequests	16	Per-upstream pending cap, 0–4,096.
mcpServers.<name>.requestLimits.failureThreshold	3	Failure threshold, 1–32.
mcpServers.<name>.requestLimits.recoveryDelayMs	30000	Backoff, positive and at most 600,000 ms.
mcpServers.<name>.requestLimits.slowCancellationMs	60000	Slow-cancellation bound, positive and at most 3,600,000 ms.

See Bridging MCP servers for transport examples, overlays, source/tool IDs, and resource restrictions.

Experimental switches

Setting	Default / meaning when omitted	Purpose
experimental.agentTickets	false	Optional serialized duplicate-branch ticket chain; not identity, authentication, or exactly-once execution.
experimental.claudeSkills	false	Opt into Claude standalone/plugin skill discovery.
experimental.forceReadOnlyToolAnnotations	false	Force read-only declaration hints without changing real side effects.
experimental.forceDestructiveToolAnnotations	false	Force the destructive annotation hint; false is the current default override.
experimental.forceOpenWorldToolAnnotations	false	Force the open-world annotation hint; false is the current default override.
experimental.forceIdempotentToolAnnotations	null	Override idempotence only when explicitly set; null preserves tool hints.

Annotation settings do not change tool implementations or OS permissions. When forced read-only annotations are enabled, generated agent instructions also omit the obsolete instruction to stop merely because only read-only declarations are exposed; explicit user constraints still apply. Agent tickets require serialized model calls and use ticketless, read-only ticket_wait for lease recovery; read the technical reference before enabling them.

---

Reviewed against v2.3.24 on 29 October 2026. Source: src/config.rs · src/types.rs · src/markdown_chat/mod.rs.