Documentation
¶
Overview ¶
Package rc loads and manages runtime configuration from .ctxrc files.
Package rc provides runtime configuration loading from .ctxrc files.
Index ¶
- Constants
- func AllowOutsideCwd() bool
- func ArchiveAfterDays() int
- func AutoArchive() bool
- func BillingTokenWarn() int
- func ContextDir() string
- func ContextWindow() int
- func ConventionLineCount() int
- func EntryCountDecisions() int
- func EntryCountLearnings() int
- func EventLog() bool
- func FilePriority(name string) int
- func InjectionTokenWarn() int
- func KeyPath() string
- func KeyRotationDays() int
- func NotifyEvents() []string
- func OverrideContextDir(dir string)
- func PriorityOrder() []string
- func Reset()
- func ScratchpadEncrypt() bool
- func SessionPrefixes() []string
- func StaleAgeDays() int
- func TaskNudgeInterval() int
- func TokenBudget() int
- func Validate(data []byte) (warnings []string, err error)
- type CtxRC
- type FreshnessFile
- type NotifyConfig
Constants ¶
const ( DefaultTokenBudget = runtime.DefaultTokenBudget DefaultArchiveAfterDays = runtime.DefaultArchiveAfterDays DefaultEntryCountLearnings = runtime.DefaultEntryCountLearnings DefaultEntryCountDecisions = runtime.DefaultEntryCountDecisions DefaultConventionLineCount = runtime.DefaultConventionLineCount DefaultInjectionTokenWarn = runtime.DefaultInjectionTokenWarn DefaultContextWindow = runtime.DefaultContextWindow DefaultTaskNudgeInterval = runtime.DefaultTaskNudgeInterval DefaultKeyRotationDays = runtime.DefaultKeyRotationDays DefaultStaleAgeDays = runtime.DefaultStaleAgeDays )
Aliases re-exported from config/runtime for use within rc.
Variables ¶
This section is empty.
Functions ¶
func AllowOutsideCwd ¶ added in v0.6.0
func AllowOutsideCwd() bool
AllowOutsideCwd returns whether boundary validation should be skipped.
Returns false (default) when the field is not set in .ctxrc.
Returns:
- bool: True if context directory is allowed outside the project root
func ArchiveAfterDays ¶
func ArchiveAfterDays() int
ArchiveAfterDays returns the configured days before archiving.
Returns:
- int: Number of days after which completed tasks are archived (default 7)
func AutoArchive ¶
func AutoArchive() bool
AutoArchive returns whether auto-archiving is enabled.
Returns:
- bool: True if completed tasks should be auto-archived
func BillingTokenWarn ¶ added in v0.8.0
func BillingTokenWarn() int
BillingTokenWarn returns the absolute token threshold for billing warnings.
Returns 0 (default, disabled). When set to a positive value, the check-context-size hook emits a one-shot VERBATIM warning the first time session tokens exceed this threshold.
Returns:
- int: Token threshold, or 0 if disabled
func ContextDir ¶
func ContextDir() string
ContextDir returns the configured context directory.
Priority: CLI override > env var > .ctxrc > default.
Returns:
- string: The context directory path (e.g., ".context")
func ContextWindow ¶ added in v0.8.0
func ContextWindow() int
ContextWindow returns the configured context window size in tokens.
Returns 200000 (default). For Claude Code users this value is a no-op: the system hook auto-detects 200k vs 1M from ~/.claude/settings.json. Only useful as a manual override for non-Claude AI tools.
Returns:
- int: Context window size in tokens
func ConventionLineCount ¶ added in v0.8.0
func ConventionLineCount() int
ConventionLineCount returns the line count threshold for CONVENTIONS.md.
Returns 0 if the check is disabled. Default: 200.
Returns:
- int: Threshold above which a drift warning is emitted
func EntryCountDecisions ¶ added in v0.8.0
func EntryCountDecisions() int
EntryCountDecisions returns the entry count threshold for DECISIONS.md.
Returns 0 if the check is disabled. Default: 20.
Returns:
- int: Threshold above which a drift warning is emitted
func EntryCountLearnings ¶ added in v0.8.0
func EntryCountLearnings() int
EntryCountLearnings returns the entry count threshold for LEARNINGS.md.
Returns 0 if the check is disabled. Default: 30.
Returns:
- int: Threshold above which a drift warning is emitted
func EventLog ¶ added in v0.8.0
func EventLog() bool
EventLog returns whether local hook event logging is enabled.
Returns false (default) when the field is not set in .ctxrc.
Returns:
- bool: True if hook events should be logged to .context/state/events.jsonl
func FilePriority ¶
FilePriority returns the priority of a context file.
If a priority_order is configured in .ctxrc, that order is used. Otherwise, the default config.ReadOrder is used.
Lower numbers indicate higher priority (1 = highest). Unknown files return 100.
Parameters:
- name: Filename to look up (e.g., "TASKS.md")
Returns:
- int: Priority value (1-9 for known files, 100 for unknown)
func InjectionTokenWarn ¶ added in v0.8.0
func InjectionTokenWarn() int
InjectionTokenWarn returns the token threshold for oversize injection warning.
Returns 0 if the check is disabled. Default: 15000.
Returns:
- int: Threshold above which an oversize flag is written
func KeyPath ¶ added in v0.8.0
func KeyPath() string
KeyPath returns the resolved encryption key file path.
Priority: key_path in .ctxrc (explicit) > project-local
(.context/.ctx.key) > global (~/.ctx/.ctx.key).
Returns:
- string: Resolved path to the encryption key file
func KeyRotationDays ¶ added in v0.8.0
func KeyRotationDays() int
KeyRotationDays returns the configured key rotation threshold in days.
The encryption key is shared by both ctx pad and ctx notify, so the rotation threshold is a project-wide setting.
Priority: top-level key_rotation_days >
notify.key_rotation_days (legacy) > default (90).
Returns:
- int: Number of days before a key rotation nudge
func NotifyEvents ¶ added in v0.8.0
func NotifyEvents() []string
NotifyEvents returns the configured event filter list for notifications.
Returns nil if Notify is nil (no filtering: all events pass).
Returns:
- []string: Event names to allow, or nil for all
func OverrideContextDir ¶
func OverrideContextDir(dir string)
OverrideContextDir sets a CLI-provided override for the context directory.
This takes precedence over all other configuration sources.
Parameters:
- dir: Directory path to use as an override
func PriorityOrder ¶
func PriorityOrder() []string
PriorityOrder returns the configured file priority order.
Returns:
- []string: File names in priority order, or nil if not configured (callers should fall back to config.ReadOrder)
func Reset ¶
func Reset()
Reset clears the cached configuration, forcing reload on the next access. This is primarily useful for testing.
func ScratchpadEncrypt ¶ added in v0.6.0
func ScratchpadEncrypt() bool
ScratchpadEncrypt returns whether the scratchpad should be encrypted.
Returns true (default) when the field is not set in .ctxrc.
Returns:
- bool: True if scratchpad encryption is enabled (default true)
func SessionPrefixes ¶ added in v0.8.0
func SessionPrefixes() []string
SessionPrefixes returns the list of recognized session header prefixes for the Markdown parser. Falls back to parser.DefaultSessionPrefixes when unconfigured or empty in .ctxrc.
Returns:
- []string: Recognized prefixes (e.g., ["Session:"])
func StaleAgeDays ¶ added in v0.8.0
func StaleAgeDays() int
StaleAgeDays returns the number of days before a context file is flagged as stale by drift detection. Returns 0 if disabled.
Returns:
- int: Days threshold, or 0 to disable the check
func TaskNudgeInterval ¶ added in v0.8.0
func TaskNudgeInterval() int
TaskNudgeInterval returns the number of Edit/Write calls between task completion nudges. Returns 0 if disabled.
Returns:
- int: Interval between nudges, or 0 if disabled
func TokenBudget ¶
func TokenBudget() int
TokenBudget returns the configured default token budget.
Priority: env var > .ctxrc > default (8000).
Returns:
- int: The token budget for context assembly
func Validate ¶ added in v0.8.0
Validate performs strict YAML decoding of .ctxrc content.
Unknown fields are returned as warnings (not errors) so callers can distinguish typos from genuinely broken YAML.
Parameters:
- data: Raw YAML content from a .ctxrc file
Returns:
- warnings: Human-readable messages for each unknown field
- err: Non-nil only for genuinely malformed YAML
Types ¶
type CtxRC ¶
type CtxRC struct {
Profile string `yaml:"profile"`
ContextDir string `yaml:"context_dir"`
TokenBudget int `yaml:"token_budget"`
PriorityOrder []string `yaml:"priority_order"`
AutoArchive bool `yaml:"auto_archive"`
ArchiveAfterDays int `yaml:"archive_after_days"`
ScratchpadEncrypt *bool `yaml:"scratchpad_encrypt"`
AllowOutsideCwd bool `yaml:"allow_outside_cwd"`
EntryCountLearnings int `yaml:"entry_count_learnings"`
EntryCountDecisions int `yaml:"entry_count_decisions"`
ConventionLineCount int `yaml:"convention_line_count"`
InjectionTokenWarn int `yaml:"injection_token_warn"`
ContextWindow int `yaml:"context_window"`
BillingTokenWarn int `yaml:"billing_token_warn"`
EventLog bool `yaml:"event_log"`
KeyRotationDays int `yaml:"key_rotation_days"`
TaskNudgeInterval int `yaml:"task_nudge_interval"`
KeyPathOverride string `yaml:"key_path"`
StaleAgeDays int `yaml:"stale_age_days"`
SessionPrefixes []string `yaml:"session_prefixes"`
FreshnessFiles []FreshnessFile `yaml:"freshness_files"`
Notify *NotifyConfig `yaml:"notify"`
}
CtxRC represents the configuration from the .ctxrc file.
Fields:
- ContextDir: Name of the context directory (default ".context")
- TokenBudget: Default token budget for context assembly (default 8000)
- PriorityOrder: Custom file loading priority order
- AutoArchive: Whether to auto-archive completed tasks (default true)
- ArchiveAfterDays: Days before archiving completed tasks (default 7)
- ScratchpadEncrypt: Whether to encrypt the scratchpad (default true)
- AllowOutsideCwd: Skip boundary validation for external context dirs (default false)
- InjectionTokenWarn: Token threshold for oversize injection warning (default 15000, 0 = disabled)
- ContextWindow: Context window size in tokens for usage reporting (default 200000). No-op for Claude Code users: auto-detected from ~/.claude/settings.json. Only needed for non-Claude AI tools.
- BillingTokenWarn: Absolute token threshold for billing nudge (default 0 = disabled). When set, a one-shot VERBATIM warning fires the first time session tokens exceed this value. Useful for Claude Pro users with 1M context where tokens beyond the included allowance incur extra cost.
- EventLog: Whether to log hook events locally (default false)
- KeyRotationDays: Days before encryption key rotation nudge (default 90)
- TaskNudgeInterval: Edit/Write calls between task completion nudges (default 5, 0 = disabled)
- KeyPathOverride: Explicit encryption key file path (default: auto-resolved)
- SessionPrefixes: Recognized session header prefixes for Markdown parser (default: Session:)
- StaleAgeDays: Days before a context file is flagged as stale by drift detection (default 30, 0 = disabled)
- FreshnessFiles: Files to track for technology-dependent constant staleness (opt-in)
type FreshnessFile ¶ added in v0.8.0
type FreshnessFile struct {
Path string `yaml:"path"`
Desc string `yaml:"desc"`
ReviewURL string `yaml:"review_url"`
}
FreshnessFile describes a source file containing technology-dependent constants that should be periodically reviewed.
Fields:
- Path: File path relative to the project root
- Desc: Summary of what constants live in the file
- ReviewURL: Optional URL to check against when reviewing (e.g., vendor docs)
func FreshnessFiles ¶ added in v0.8.0
func FreshnessFiles() []FreshnessFile
FreshnessFiles returns the configured list of files to track for freshness. Returns nil if no files are configured: the hook is a no-op when the list is empty.
Returns:
- []FreshnessFile: Tracked files, or nil if unconfigured
type NotifyConfig ¶ added in v0.8.0
type NotifyConfig struct {
Events []string `yaml:"events"`
KeyRotationDays int `yaml:"key_rotation_days"`
}
NotifyConfig holds webhook notification settings.
KeyRotationDays is deprecated here; use the top-level CtxRC.KeyRotationDays instead. This field is retained for backwards compatibility with existing .ctxrc files that have key_rotation_days nested under notify.
Source Files