projects schema (151-300)

Canonical generated docsThis section is generated from caco config schema --json. The table below preserves the runtime field path, type, required/default markers, and canonical description for every value in this slice.

Project definitions — repositories managed by Cacophony. Accepts both a list of projects (with 'name' field) and a map keyed by project name.

Previous Next

Field path	Type	Required	Default	Canonical description
└ `projects.agents.flow.default.override_pi_agent_dir`	`string`	optional		Read-only operator-owned Pi agent directory passed directly to managed Pi launches instead of materializing .pi-agent config.
└ `projects.agents.flow.default.warmup_cache_injection`	`map`	optional		Disabled-by-default advisory warmup-cache prompt injection settings for spawned agents.
└ `projects.agents.flow.default.warmup_cache_injection.enabled`	`bool`	optional	false	Enable advisory warmup-cache prompt injection.
└ `projects.agents.flow.default.warmup_cache_injection.max_age_seconds`	`i64`	optional	86400	Maximum accepted warmup summary age before skipping injection.
└ `projects.agents.flow.default.warmup_cache_injection.max_chars`	`usize`	optional	2048	Maximum characters injected from the warmup summary.
└ `projects.agents.flow.default.pane_error_detection`	`bool`	optional	false	Enable tmux pane content scanning for Pi agent fatal error detection.
└ `projects.agents.flow.default.eligible_nodes`	`list[string]`	optional		Allowlist of node names for round_robin/least_overloaded placement. Manual --node overrides bypass this.
└ `projects.agents.flow.default.friend_projects`	`list[friend_project]`	optional		Agent-default friend project overlays inherited by agents in this project.
└ `projects.agents.flow.default.friend_projects.project`	`string`	required		Target project name.
└ `projects.agents.flow.default.friend_projects.branch`	`string`	optional		Target branch; omitted means the friend project's default_branch. Mutually exclusive with revision.
└ `projects.agents.flow.default.friend_projects.revision`	`string`	optional		Pinned git revision. Mutually exclusive with branch.
└ `projects.agents.flow.default.friend_projects.permissions`	`list[string]`	optional	[checkout_read]	Granted operations: checkout_read, checkout_write, beads_read, beads_create, beads_update, beads_claim, beads_close, beads_dispatch.
└ `projects.agents.flow.default.friend_projects.materialize`	`bool`	optional	false	Materialize a real friend checkout cloned from the friend project's remote; omitted means a virtual friend with no checkout.
└ `projects.agents.flow.default.friend_projects.enabled`	`bool`	optional	true	Set false in a narrower layer to disable an inherited friend.
└ `projects.agents.heartbeat`	`map`	optional		Project-scoped managed-agent heartbeat defaults and per-agent overrides, overlaying the cluster default.
└ `projects.agents.heartbeat.enabled`	`bool`	optional	false	Enable local daemon-owned managed-agent heartbeat delivery for this scope. Defaults to false for safe rollout.
└ `projects.agents.heartbeat.selector`	`string`	optional	persistent	Agent selector for this scope: all, persistent, workers, or none.
└ `projects.agents.heartbeat.interval_secs`	`u64`	optional	300	Base heartbeat cadence in seconds.
└ `projects.agents.heartbeat.jitter_secs`	`u64`	optional	0	Optional jitter in seconds; must not exceed interval_secs.
└ `projects.agents.heartbeat.max_backoff_secs`	`u64`	optional	300	Optional delivery-failure backoff ceiling in seconds; must be at least interval_secs.
└ `projects.agents.heartbeat.allow_runtime_opt_out`	`bool`	optional	true	Allow runtime/profile code to decline heartbeats even when config enables them.
└ `projects.agents.heartbeat.conditions`	`list[string]`	optional		Optional OR timer gates: claimed_beads (owned unfinished claims), unmerged_prs (linked open PRs), pending_inbox (visible unread messages). Inherits when omitted; [] is unconditional. Runtime on never bypasses conditions.
└ `projects.agents.heartbeat.overrides`	`map[string, map]`	optional		Per-agent overrides keyed by persistent declaration name, composed profile, or concrete agent id.
└ `projects.agents.heartbeat.overrides.<agent>`	`map`	optional		One per-agent heartbeat override; inherits unspecified fields from the surrounding scope.
└ `projects.agents.heartbeat.overrides.<agent>.enabled`	`bool`	optional		Enable or disable heartbeat for this agent.
└ `projects.agents.heartbeat.overrides.<agent>.selector`	`string`	optional		Optional selector override: all, persistent, workers, or none.
└ `projects.agents.heartbeat.overrides.<agent>.interval_secs`	`u64`	optional		Override base heartbeat cadence in seconds.
└ `projects.agents.heartbeat.overrides.<agent>.jitter_secs`	`u64`	optional		Override jitter in seconds; must not exceed interval_secs when both are set.
└ `projects.agents.heartbeat.overrides.<agent>.max_backoff_secs`	`u64`	optional		Override delivery-failure backoff ceiling in seconds.
└ `projects.agents.heartbeat.overrides.<agent>.allow_runtime_opt_out`	`bool`	optional		Override runtime opt-out permission for this agent.
└ `projects.agents.heartbeat.overrides.<agent>.conditions`	`list[string]`	optional		Replace inherited OR timer gates (claimed_beads, unmerged_prs, pending_inbox); [] restores unconditional delivery.
└ `projects.agents.message_delivery`	`map`	optional		Project-scoped message-delivery cadence defaults and per-agent overrides, overlaying the cluster default before node defaults.
└ `projects.agents.message_delivery.enabled`	`bool`	optional	false	Enable local daemon-owned managed-agent message-delivery batching for this scope. Defaults to false (immediate wake) for safe rollout.
└ `projects.agents.message_delivery.selector`	`string`	optional	all	Agent selector for this scope: all, persistent, workers, or none.
└ `projects.agents.message_delivery.default_mode`	`string`	optional	immediate	Wake mode for a message with no explicit wake flag: immediate (wake now) or batch (defer to next heartbeat).
└ `projects.agents.message_delivery.always_wake_kinds`	`list[string]`	optional		Message kinds that always wake regardless of mode (e.g. lifecycle, system).
└ `projects.agents.message_delivery.allow_runtime_opt_out`	`bool`	optional	true	Allow runtime/profile code to decline batching even when config enables it.
└ `projects.agents.message_delivery.batch_flush_interval_secs`	`u64`	optional		Optional shorter dedicated cadence in seconds for surfacing deferred (batched) messages via a coalesced summary wake, instead of waiting for the full heartbeat. A flush with no pending messages costs zero model turns.
└ `projects.agents.message_delivery.direct_message_wake`	`bool`	optional	true	Operator- or agent-authored direct messages the batch policy would defer instead force one coalesced wake carrying them inline, including for idle, dormant and queue-parked recipients; paused or starting recipients are held until live. Automated notices, broadcast batching and heartbeat intervals are unchanged. false restores pure batching of direct messages.
└ `projects.agents.message_delivery.overrides`	`map[string, map]`	optional		Per-agent overrides keyed by persistent declaration name or concrete agent id.
└ `projects.agents.message_delivery.overrides.<agent>`	`map`	optional		One per-agent message-delivery override; inherits unspecified fields from the surrounding scope.
└ `projects.agents.message_delivery.overrides.<agent>.enabled`	`bool`	optional		Enable or disable message-delivery batching for this agent.
└ `projects.agents.message_delivery.overrides.<agent>.selector`	`string`	optional		Optional selector override: all, persistent, workers, or none.
└ `projects.agents.message_delivery.overrides.<agent>.default_mode`	`string`	optional		Override wake mode: immediate or batch.
└ `projects.agents.message_delivery.overrides.<agent>.always_wake_kinds`	`list[string]`	optional		Override always-wake message kinds.
└ `projects.agents.message_delivery.overrides.<agent>.allow_runtime_opt_out`	`bool`	optional		Override runtime opt-out permission for this agent.
└ `projects.agents.message_delivery.overrides.<agent>.batch_flush_interval_secs`	`u64`	optional		Override the dedicated batch-flush cadence in seconds.
└ `projects.agents.message_delivery.overrides.<agent>.direct_message_wake`	`bool`	optional		Override the direct-message wake for this agent.
└ `projects.agents.persistent.<name>`	`map`	optional		Persistent agent declaration keyed by stable name.
└ `projects.agents.persistent.<name>.name`	`string`	optional		Stable human-readable agent name (alphanumeric + hyphens, max 32 chars).
└ `projects.agents.persistent.<name>.profile`	`string \| list[string]`	required		Profile name or ordered list for composite composition.
└ `projects.agents.persistent.<name>.preset`	`string`	optional		Preset ID to launch with.
└ `projects.agents.persistent.<name>.ahp_host`	`string`	optional		For `ahp` agents: the AHP host (agents.ahp_hosts) the session lives on; optional when the node has exactly one.
└ `projects.agents.persistent.<name>.type`	`string`	optional		Explicit agent type when not implied by preset.
└ `projects.agents.persistent.<name>.environment`	`map[string, string]`	optional		Non-secret declaration overrides applied after project, preset, and profile env.
└ `projects.agents.persistent.<name>.auto_start`	`bool`	optional	true	Whether daemon auto-converges toward a live instance.
└ `projects.agents.persistent.<name>.restart`	`string`	optional	failure	Restart policy: 'failure' (default), 'always', or 'never'.
└ `projects.agents.persistent.<name>.restart_backoff_secs`	`u32`	optional	30	Minimum backoff between failed restart attempts.
└ `projects.agents.persistent.<name>.nodes`	`list[string]`	optional		Node allowlist (project-scoped only). Omit for all nodes.
└ `projects.agents.persistent.<name>.cadence`	`map`	optional		Controller idle polling timers.
└ `projects.agents.persistent.<name>.cadence.reconcile_interval_secs`	`u64`	optional	120	Idle reconciliation cadence.
└ `projects.agents.persistent.<name>.cadence.inbox_poll_interval_secs`	`u64`	optional	120	Inbox poll cadence.
└ `projects.agents.persistent.<name>.cadence.jitter_secs`	`u64`	optional	30	Max random jitter to prevent thundering herd.
└ `projects.agents.persistent.<name>.cadence.claimed_heartbeat_interval_secs`	`u64`	optional	1800	Claimed-bead heartbeat cadence (PostToolUse hook reminds agents of active claims + goal; 0 disables)..
└ `projects.agents.persistent.<name>.wait`	`map`	optional		Controller wait mode configuration.
└ `projects.agents.persistent.<name>.wait.inbox_delay_secs`	`u64`	optional	60	Minimum delay before inbox wait reads state.
└ `projects.agents.persistent.<name>.wait.choice_timeout_secs`	`u64`	optional		Timeout for choice wait mode (null = indefinite).
└ `projects.agents.persistent.<name>.model`	`string`	optional		Model to use for this persistent agent (e.g. 'opus', 'sonnet'). Passed as --model.
└ `projects.agents.persistent.<name>.provider`	`string`	optional		Provider to use for this persistent agent (e.g. 'openai', 'anthropic', 'google').
└ `projects.agents.persistent.<name>.mcp_policy`	`string`	optional	profile	Final declaration-scoped MCP policy: profile (default) or disabled.
└ `projects.agents.persistent.<name>.short_name_strategy`	`map`	optional		Strategy for generating a short human-friendly display name at agent creation time.
└ `projects.agents.persistent.<name>.short_name_strategy.strategy`	`string`	required		Short-name strategy: adj_noun, template or llm.
└ `projects.agents.persistent.<name>.short_name_strategy.template`	`string`	optional		Bounded display template for strategy = template. Placeholders: {adj}, {noun}, {profile}, {bead}, {node}, {n}. Names remain aliases, not identities.
└ `projects.agents.persistent.<name>.short_name_strategy.llm`	`string`	optional		Top-level llm alias used when strategy = llm.
└ `projects.agents.persistent.<name>.checkout_type`	`string`	optional	worktree	How the agent's working checkout is materialized: worktree (default; a git worktree sharing the canonical.git, fastest startup), clone (a shared clone), full (a 1st-party clone of the real remote), read_only_symlink (observers), or pr_branch (a full-clone whose working branch is an existing GitHub PR head; requires github_integration.enabled,). made worktree the default.
└ `projects.agents.persistent.<name>.confirm_before_spawn`	`bool`	optional	false	Require operator approval through caco choices before spawning this persistent agent.
└ `projects.agents.persistent.<name>.confirm_before_spawn_timeout_secs`	`u64`	optional	300	Timeout in seconds for the operator confirmation prompt.
└ `projects.agents.persistent.<name>.confirm_before_spawn_auto_approve`	`bool`	optional	false	Auto-approve the spawn when the confirmation timeout expires.
└ `projects.agents.persistent.<name>.all_projects`	`bool`	optional	false	Allow this persistent agent to access all configured projects instead of only its bound project.
└ `projects.agents.persistent.<name>.goal`	`string`	optional		Default goal/task description for managed launches via this declaration; used when --goal is not passed.
└ `projects.agents.persistent.<name>.schedule`	`map`	optional		Schedule configuration for periodic persistent agent launches.
└ `projects.agents.persistent.<name>.schedule.cron`	`string`	required		Standard 5-field cron expression.
└ `projects.agents.persistent.<name>.schedule.launch_mode`	`string`	optional	restart-or-recreate	Launch mode: recreate, restart, or restart-or-recreate.
└ `projects.agents.persistent.<name>.pane_error_detection`	`bool`	optional	false	Enable tmux pane content scanning for fatal error detection. Overrides agent_defaults. Default false.
└ `projects.agents.persistent.<name>.project`	`string`	optional		Explicit project binding for node-scoped persistent agents. When set, this project is used for checkout, bead visibility, and profile resolution instead of the first configured project.
└ `projects.agents.persistent.<name>.depends_on_node`	`string`	optional		Cross-node reachability dependency: defer launch until the named remote node is reachable per PeerReachabilityMap. When omitted, no gate is applied.
└ `projects.agents.persistent.<name>.friend_projects`	`list[friend_project]`	optional		Per-declaration friend project overlay; entries can narrow or disable inherited friends.
└ `projects.agents.persistent.<name>.friend_projects.project`	`string`	required		Target project name.
└ `projects.agents.persistent.<name>.friend_projects.branch`	`string`	optional		Target branch; omitted means the friend project's default_branch. Mutually exclusive with revision.
└ `projects.agents.persistent.<name>.friend_projects.revision`	`string`	optional		Pinned git revision. Mutually exclusive with branch.
└ `projects.agents.persistent.<name>.friend_projects.permissions`	`list[string]`	optional	[checkout_read]	Granted operations: checkout_read, checkout_write, beads_read, beads_create, beads_update, beads_claim, beads_close, beads_dispatch.
└ `projects.agents.persistent.<name>.friend_projects.materialize`	`bool`	optional	false	Materialize a real friend checkout cloned from the friend project's remote; omitted means a virtual friend with no checkout.
└ `projects.agents.persistent.<name>.friend_projects.enabled`	`bool`	optional	true	Set false in a narrower layer to disable an inherited friend.
└ `projects.agents.groups.<name>`	`list[string]`	optional		Project-scoped agent group mapping from group name to agent IDs.
└ `projects.submodules`	`map`	optional		Submodule handling settings.
└ `projects.submodules.enabled`	`bool`	optional	false	Whether submodule handling is active.
└ `projects.submodules.recursive`	`bool`	optional	false	Whether nested submodules are initialized recursively.
└ `projects.submodules.enabled_paths`	`list[string]`	optional		Restrict submodule init/update to these paths only.
└ `projects.sparse`	`map`	optional		Sparse-checkout spec.
└ `projects.sparse.mode`	`string`	optional	cone	Sparse-checkout mode: cone (default) or no-cone.
└ `projects.sparse.include`	`list[string]`	optional		Paths to materialize in the checkout.
└ `projects.sparse.exclude`	`list[string]`	optional		Negated patterns (no-cone mode only; ignored in cone mode).
└ `projects.actions`	`map[string, map]`	optional		Project-scoped actions keyed by action name.
└ `projects.actions.<action-name>`	`map`	optional		Project action entry.
└ `projects.actions.<action-name>.type`	`string`	required		Action type (currently only 'command').
└ `projects.actions.<action-name>.command`	`string`	required		Shell command to execute.
└ `projects.actions.<action-name>.description`	`string`	optional		Human-readable description.
└ `projects.actions.<action-name>.roles_permitted`	`list[string]`	optional		Roles/profiles allowed to invoke (e.g. 'operator', 'profile:<name>').
└ `projects.actions.<action-name>.cwd`	`string`	optional		Working directory for command execution.
└ `projects.actions.<action-name>.timeout_secs`	`u64`	optional	300	Timeout in seconds for command execution.
└ `projects.actions.<action-name>.idempotent`	`bool`	optional	false	Whether exact replay is safe after restart.
└ `projects.actions.<action-name>.check`	`string`	optional		Side-effect-free shell command that exercises the action's prerequisites; run by 'caco action check'.
└ `projects.hooks`	`map`	optional		Project-level lifecycle hooks.
└ `projects.hooks.checkout_updated`	`list[action]`	optional		Actions to fire when the canonical checkout moves to a new commit.
└ `projects.hooks.checkout_updated.action`	`string`	required		Action type: notify_agent, shell, broadcast, speak.
└ `projects.hooks.checkout_updated.agent`	`string`	optional		Target persistent agent name (for notify_agent).
└ `projects.hooks.checkout_updated.message`	`string`	optional		Message to deliver (for notify_agent). Supports $var templates.
└ `projects.hooks.checkout_updated.command`	`string`	optional		Shell command (for shell action). Hook variables injected as $CACO_HOOK_VAR env vars.
└ `projects.hooks.checkout_updated.body`	`string`	optional		Body text (for broadcast/speak). Supports $var templates.
└ `projects.hooks.checkout_updated.voice`	`string`	optional		TTS voice override (for speak action).
└ `projects.hooks.tag_pushed`	`list[action]`	optional		Actions to fire when a new git tag is detected.
└ `projects.hooks.tag_pushed.action`	`string`	required		Action type: notify_agent, shell, broadcast, speak.
└ `projects.hooks.tag_pushed.agent`	`string`	optional		Target persistent agent name (for notify_agent).
└ `projects.hooks.tag_pushed.message`	`string`	optional		Message to deliver (for notify_agent). Supports $var templates.
└ `projects.hooks.tag_pushed.command`	`string`	optional		Shell command (for shell action). Hook variables injected as $CACO_HOOK_VAR env vars.
└ `projects.hooks.tag_pushed.body`	`string`	optional		Body text (for broadcast/speak). Supports $var templates.
└ `projects.hooks.tag_pushed.voice`	`string`	optional		TTS voice override (for speak action).
└ `projects.hooks.daemon_upgraded`	`list[action]`	optional		Actions to fire after a daemon upgrade.
└ `projects.hooks.daemon_upgraded.action`	`string`	required		Action type: notify_agent, shell, broadcast, speak.
└ `projects.hooks.daemon_upgraded.agent`	`string`	optional		Target persistent agent name (for notify_agent).
└ `projects.hooks.daemon_upgraded.message`	`string`	optional		Message to deliver (for notify_agent). Supports $var templates.
└ `projects.hooks.daemon_upgraded.command`	`string`	optional		Shell command (for shell action). Hook variables injected as $CACO_HOOK_VAR env vars.
└ `projects.hooks.daemon_upgraded.body`	`string`	optional		Body text (for broadcast/speak). Supports $var templates.
└ `projects.hooks.daemon_upgraded.voice`	`string`	optional		TTS voice override (for speak action).
└ `projects.webhooks`	`map`	optional		Webhook ingress: POST /hooks/<project>/<hook-id> -> bead/bash/action/agent handler.
└ `projects.webhooks.enabled`	`bool`	optional		Whether hook ingress is enabled (default true when entries present).
└ `projects.webhooks.token`	`string`	optional		Global bearer token (inline) accepted for any hook in this section. Mutually exclusive with token_env/token_file.
└ `projects.webhooks.token_env`	`string`	optional		Section bearer token read from this env var at auth time (rotation-robust). Mutually exclusive with token/token_file.
└ `projects.webhooks.token_file`	`string`	optional		Section bearer token read from this file at auth time, tilde-expanded (rotation-robust). Mutually exclusive with token/token_env.
└ `projects.webhooks.nodes`	`list[string]`	optional		Default node filter: which daemons serve/funnel this section's hooks.
└ `projects.webhooks.bind_host`	`string`	optional		Webhook listener bind host (default 127.0.0.1).
└ `projects.webhooks.bind_port`	`int`	optional		Dedicated webhook listener port (the Tailscale Funnel target).
└ `projects.webhooks.funnel`	`bool`	optional		Opt-in Tailscale Funnel exposure on the filtered nodes (default false).
└ `projects.webhooks.max_body_bytes`	`int`	optional		Maximum request body size in bytes (default 1 MiB).
└ `projects.webhooks.entries`	`map[string, map]`	optional		Hooks keyed by <hook-id> (the URL path segment).
└ `projects.webhooks.entries.<hook-id>`	`map`	optional		A single webhook served at /hooks/<scope>/<hook-id>.
└ `projects.webhooks.entries.<hook-id>.type`	`string`	required		Handler type: bead \| bash \| action \| agent.
└ `projects.webhooks.entries.<hook-id>.token`	`string`	optional		Per-hook bearer token (inline; accepted in addition to the section token). Mutually exclusive with token_env/token_file.
└ `projects.webhooks.entries.<hook-id>.token_env`	`string`	optional		Per-hook bearer token read from this env var at auth time (rotation-robust). Mutually exclusive with token/token_file.
└ `projects.webhooks.entries.<hook-id>.token_file`	`string`	optional		Per-hook bearer token read from this file at auth time, tilde-expanded (rotation-robust). Mutually exclusive with token/token_env.

Previous Next