config

package
v0.6.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Feb 16, 2026 License: Apache-2.0 Imports: 2 Imported by: 0

Documentation

Overview

Package config provides configuration constants, regex patterns, and entry type definitions used across the ctx codebase.

It centralizes magic strings (file names, directory names, headings), file permissions, regex patterns for parsing Markdown context files, and template strings for generating output. All repeated literals are defined here to prevent drift across packages.

Index

Constants

View Source
const (
	// DirArchive is the subdirectory for archived tasks within .context/.
	DirArchive = "archive"
	// DirClaude is the Claude Code configuration directory in the project root.
	DirClaude = ".claude"
	// DirClaudeHooks is the hooks subdirectory within .claude/.
	DirClaudeHooks = ".claude/hooks"
	// DirContext is the default context directory name.
	DirContext = ".context"
	// DirJournal is the subdirectory for journal entries within .context/.
	DirJournal = "journal"
	// DirTools is the subdirectory for tool scripts within .context/.
	DirTools = "tools"
	// DirJournalSite is the journal static site output directory within .context/.
	DirJournalSite = "journal-site"
)

Directory path constants used throughout the application.

View Source
const (
	// JournalDirDocs is the docs subdirectory in the generated site.
	JournalDirDocs = "docs"
	// JournalDirTopics is the topics subdirectory in the generated site.
	JournalDirTopics = "topics"
	// JournalDirFiles is the key files subdirectory in the generated site.
	JournalDirFiles = "files"
	// JournalDirTypes is the session types subdirectory in the generated site.
	JournalDirTypes = "types"
)

Journal site output directories.

View Source
const (
	// EntryTask represents a task entry in TASKS.md.
	EntryTask = "task"
	// EntryDecision represents an architectural decision in DECISIONS.md.
	EntryDecision = "decision"
	// EntryLearning represents a lesson learned in LEARNINGS.md.
	EntryLearning = "learning"
	// EntryConvention represents a code pattern in CONVENTIONS.md.
	EntryConvention = "convention"
	// EntryComplete represents a task completion action (marks the task as done).
	EntryComplete = "complete"
	// EntryUnknown is returned when user input doesn't match any known type.
	EntryUnknown = "unknown"
)

Entry type constants for context updates.

These are the canonical internal representations used in switch statements for routing add/update commands to the appropriate handler.

View Source
const (
	// FieldContext is the background/situation field for decisions and learnings.
	FieldContext = "context"
	// FieldRationale is the reasoning field for decisions (why this choice).
	FieldRationale = "rationale"
	// FieldConsequence is the outcomes field for decisions (what changes).
	FieldConsequence = "consequences"
	// FieldApplication is the usage field for learnings (how to apply going forward).
	FieldApplication = "application"
	// FieldLesson is the insight field for learnings (the key takeaway).
	FieldLesson = "lesson"
)

Field name constants for structured entry attributes.

These are used in validation error messages and as attribute names in context-update XML tags for decisions and learnings.

View Source
const (
	// PermFile is the standard permission for regular files (owner rw, others r).
	PermFile = 0644
	// PermExec is the standard permission for directories and executable files.
	PermExec = 0755
	// PermSecret is the permission for secret files (owner rw only).
	PermSecret = 0600
)

File permission constants.

View Source
const (
	// ExtMarkdown is the Markdown file extension.
	ExtMarkdown = ".md"
	// ExtJSONL is the JSON Lines file extension.
	ExtJSONL = ".jsonl"
)

File extension constants.

View Source
const (
	// FilenameReadme is the standard README filename.
	FilenameReadme = "README.md"
	// FilenameIndex is the standard index filename for generated sites.
	FilenameIndex = "index.md"
)

Common filenames.

View Source
const (
	// FileZensicalToml is the zensical site configuration filename.
	FileZensicalToml = "zensical.toml"
	// BinZensical is the zensical binary name.
	BinZensical = "zensical"
)

Journal site configuration.

View Source
const (
	// EnvCtxDir is the environment variable for overriding the context directory.
	EnvCtxDir = "CTX_DIR"
	// EnvCtxTokenBudget is the environment variable for overriding the token budget.
	EnvCtxTokenBudget = "CTX_TOKEN_BUDGET" //nolint:gosec // G101: env var name, not a credential
)

Environment configuration.

View Source
const (
	// ClaudeBlockText is a text content block.
	ClaudeBlockText = "text"
	// ClaudeBlockThinking is an extended thinking content block.
	ClaudeBlockThinking = "thinking"
	// ClaudeBlockToolUse is a tool invocation block.
	ClaudeBlockToolUse = "tool_use"
	// ClaudeBlockToolResult is a tool execution result block.
	ClaudeBlockToolResult = "tool_result"
)

Claude API content block types.

View Source
const (
	// ClaudeFieldType is the block type discriminator key.
	ClaudeFieldType = "type"
	// ClaudeFieldText is the text content key.
	ClaudeFieldText = "text"
	// ClaudeFieldThinking is the thinking content key.
	ClaudeFieldThinking = "thinking"
	// ClaudeFieldName is the tool name key.
	ClaudeFieldName = "name"
	// ClaudeFieldInput is the tool input parameters key.
	ClaudeFieldInput = "input"
	// ClaudeFieldContent is the tool result content key.
	ClaudeFieldContent = "content"
)

Claude API content block field keys.

View Source
const (
	// RoleUser is a user message.
	RoleUser = "user"
	// RoleAssistant is an assistant message.
	RoleAssistant = "assistant"
)

Claude API message roles.

View Source
const (
	// FileClaudeMd is the Claude Code configuration file in the project root.
	FileClaudeMd = "CLAUDE.md"
	// FilePromptMd is the session prompt file in the project root.
	FilePromptMd = "PROMPT.md"
	// FileImplementationPlan is the implementation plan file in the project root.
	FileImplementationPlan = "IMPLEMENTATION_PLAN.md"
	// FileSettings is the Claude Code local settings file.
	FileSettings = ".claude/settings.local.json"
	// FileSettingsGolden is the golden image of the Claude Code settings.
	FileSettingsGolden = ".claude/settings.golden.json"
	// FileContextWatch is the context monitoring tool script.
	FileContextWatch = "context-watch.sh"
	// FileMakefileCtx is the ctx-owned Makefile include for project root.
	FileMakefileCtx = "Makefile.ctx"
)

Claude Code integration file names.

View Source
const (
	// FileConstitution contains inviolable rules for agents.
	FileConstitution = "CONSTITUTION.md"
	// FileTask contains current work items and their status.
	FileTask = "TASKS.md"
	// FileConvention contains code patterns and standards.
	FileConvention = "CONVENTIONS.md"
	// FileArchitecture contains system structure documentation.
	FileArchitecture = "ARCHITECTURE.md"
	// FileDecision contains architectural decisions with rationale.
	FileDecision = "DECISIONS.md"
	// FileLearning contains gotchas, tips, and lessons learned.
	FileLearning = "LEARNINGS.md"
	// FileGlossary contains domain terms and definitions.
	FileGlossary = "GLOSSARY.md"
	// FileAgentPlaybook contains the meta-instructions for using the
	// context system.
	FileAgentPlaybook = "AGENT_PLAYBOOK.md"
	// FileDependency contains project dependency documentation.
	FileDependency = "DEPENDENCIES.md"
)

Context file name constants for .context/ directory.

View Source
const (
	// FileScratchpadEnc is the encrypted scratchpad file.
	FileScratchpadEnc = "scratchpad.enc"
	// FileScratchpadMd is the plaintext scratchpad file.
	FileScratchpadMd = "scratchpad.md"
	// FileScratchpadKey is the scratchpad encryption key file.
	FileScratchpadKey = ".scratchpad.key"
)

Scratchpad file constants for .context/ directory.

View Source
const (
	// FormatJSON selects JSON output.
	FormatJSON = "json"
	// FormatMarkdown selects Markdown output.
	FormatMarkdown = "md"
)

Output format constants for CLI commands.

View Source
const (
	// HeadingLearningStart is the Markdown heading for entries in LEARNINGS.md
	HeadingLearningStart = "## ["
	// HeadingLearnings is the Markdown heading for LEARNINGs.md
	HeadingLearnings = "# Learnings"
	// ColumnLearning is the singular column header for learning index tables.
	ColumnLearning = "Learning"
)

Learnings

View Source
const (
	// HeadingInProgress is the section heading for in-progress tasks.
	HeadingInProgress = "## In Progress"
	// HeadingNextUp is the section heading for upcoming tasks.
	HeadingNextUp = "## Next Up"
	// HeadingCompleted is the section heading for completed tasks.
	HeadingCompleted = "## Completed"
	// HeadingArchivedTasks is the heading for archived task files.
	HeadingArchivedTasks = "# Archived Tasks"
)

Task sections in TASKS.md

View Source
const (
	// HeadingDecisions is the Markdown heading for DECISIONS.md
	HeadingDecisions = "# Decisions"
	// ColumnDecision is the singular column header for decision index tables.
	ColumnDecision = "Decision"
)

Decisions

View Source
const (
	// JournalHeadingSessionJournal is the main journal index title.
	JournalHeadingSessionJournal = "# Session Journal"
	// JournalHeadingTopics is the topics index title.
	JournalHeadingTopics = "# Topics"
	// JournalHeadingPopularTopics is the popular topics section heading.
	JournalHeadingPopularTopics = "## Popular Topics"
	// JournalHeadingLongtailTopics is the long-tail topics section heading.
	JournalHeadingLongtailTopics = "## Long-tail Topics"
	// JournalHeadingKeyFiles is the key files index title.
	JournalHeadingKeyFiles = "# Key Files"
	// JournalHeadingFrequentlyTouched is the popular key files section heading.
	JournalHeadingFrequentlyTouched = "## Frequently Touched"
	// JournalHeadingSingleSession is the single-session key files section heading.
	JournalHeadingSingleSession = "## Single Session"
	// JournalHeadingSessionTypes is the session types index title.
	JournalHeadingSessionTypes = "# Session Types"
	// JournalHeadingSuggestions is the suggestions section heading.
	JournalHeadingSuggestions = "## Suggestions"
	// JournalHeadingRecentSessions is the nav section title for recent entries.
	JournalHeadingRecentSessions = "Recent Sessions"
)

Journal index headings

View Source
const (
	// RecallHeadingSummary is the summary section heading in journal entries.
	RecallHeadingSummary = "## Summary"
	// RecallHeadingToolUsage is the tool usage section heading.
	RecallHeadingToolUsage = "## Tool Usage"
	// RecallHeadingConversation is the conversation section heading.
	RecallHeadingConversation = "## Conversation"
)

Recall/export headings used in journal entry Markdown.

View Source
const (
	// JournalLabelHome is the nav label for the index page.
	JournalLabelHome = "Home"
	// JournalLabelTopics is the nav label for the topics index.
	JournalLabelTopics = "Topics"
	// JournalLabelFiles is the nav label for the key files index.
	JournalLabelFiles = "Files"
	// JournalLabelTypes is the nav label for the session types index.
	JournalLabelTypes = "Types"
)

Journal navigation labels used in the zensical site nav bar.

View Source
const (
	// MetadataID is the bold ID field prefix.
	MetadataID = "**ID**:"
	// MetadataDate is the bold date field prefix.
	MetadataDate = "**Date**:"
	// MetadataTime is the bold time field prefix.
	MetadataTime = "**Time**:"
	// MetadataDuration is the bold duration field prefix.
	MetadataDuration = "**Duration**:"
	// MetadataTool is the bold tool field prefix.
	MetadataTool = "**Tool**:"
	// MetadataProject is the bold project field prefix.
	MetadataProject = "**Project**:"
	// MetadataBranch is the bold branch field prefix.
	MetadataBranch = "**Branch**:"
	// MetadataModel is the bold model field prefix.
	MetadataModel = "**Model**:"
	// MetadataTurns is the bold turns field prefix.
	MetadataTurns = "**Turns**:"
	// MetadataParts is the bold parts field prefix.
	MetadataParts = "**Parts**:"
	// MetadataType is the bold type field prefix.
	MetadataType = "**Type**:"
	// MetadataStartTime is the bold start_time field prefix.
	MetadataStartTime = "**start_time**:"
	// MetadataEndTime is the bold end_time field prefix.
	MetadataEndTime = "**end_time**:"
	// MetadataSource is the bold source field prefix.
	MetadataSource = "**Source**:"
)

Bold metadata field prefixes in journal/session Markdown.

View Source
const (
	// LabelRoleUser is the display label for user turns.
	LabelRoleUser = "User"
	// LabelRoleAssistant is the display label for assistant turns.
	LabelRoleAssistant = "Assistant"
)

Conversation role display labels used in exported journal entries.

View Source
const (
	// LabelBoldReminder is the bold-style system reminder prefix.
	LabelBoldReminder = "**System Reminder**:"
	// LabelToolOutput is the turn role label for tool output turns.
	LabelToolOutput = "Tool Output"
)

Journal turn markers for content transformation.

View Source
const (
	// InsightMaxLen is the maximum character length for an extracted insight.
	InsightMaxLen = 150
	// InsightWordBoundaryMin is the minimum cut position when truncating
	// at a word boundary.
	InsightWordBoundaryMin = 100
)

Insight extraction constants.

View Source
const (
	// RecallShortIDLen is the truncation length for session IDs in filenames.
	RecallShortIDLen = 8
	// RecallDetailsThreshold is the line count above which tool output is
	// wrapped in a collapsible <details> block.
	RecallDetailsThreshold = 10
)

Recall/export constants.

View Source
const (
	// JournalPopularityThreshold is the minimum number of entries to
	// mark a topic or key file as "popular" (gets its own dedicated page).
	JournalPopularityThreshold = 2
	// JournalLineWrapWidth is the soft wrap target column for journal
	// content.
	JournalLineWrapWidth = 80
	// JournalMaxRecentSessions is the maximum number of sessions shown
	// in the zensical navigation sidebar.
	JournalMaxRecentSessions = 20
	// JournalMaxNavTitleLen is the maximum title length before
	// truncation in the zensical navigation sidebar.
	JournalMaxNavTitleLen = 40
	// JournalDatePrefixLen is the length of a YYYY-MM-DD date prefix.
	JournalDatePrefixLen = 10
	// JournalMonthPrefixLen is the length of a YYYY-MM month prefix.
	JournalMonthPrefixLen = 7
	// JournalTimePrefixLen is the length of an HH:MM time prefix.
	JournalTimePrefixLen = 5
)

Journal site generation constants.

View Source
const (
	// CommentOpen is the HTML comment opening tag.
	CommentOpen = "<!--"
	// CommentClose is the HTML comment closing tag.
	CommentClose = "-->"
)

HTML comment markers for parsing and generation.

View Source
const (
	// CtxMarkerStart marks the beginning of an embedded context block.
	CtxMarkerStart = "<!-- ctx:context -->"
	// CtxMarkerEnd marks the end of an embedded context block.
	CtxMarkerEnd = "<!-- ctx:end -->"
)

Context block markers for embedding context in files.

View Source
const (
	// PromptMarkerStart marks the beginning of the prompt block.
	PromptMarkerStart = "<!-- ctx:prompt -->"
	// PromptMarkerEnd marks the end of the prompt block.
	PromptMarkerEnd = "<!-- ctx:prompt:end -->"
)

Prompt block markers for PROMPT.md.

View Source
const (
	// PlanMarkerStart marks the beginning of the plan block.
	PlanMarkerStart = "<!-- ctx:plan -->"
	// PlanMarkerEnd marks the end of the plan block.
	PlanMarkerEnd = "<!-- ctx:plan:end -->"
)

Plan block markers for IMPLEMENTATION_PLAN.md.

View Source
const (
	// IndexStart marks the beginning of an auto-generated index.
	IndexStart = "<!-- INDEX:START -->"
	// IndexEnd marks the end of an auto-generated index.
	IndexEnd = "<!-- INDEX:END -->"
)

Index markers for auto-generated table of contents sections.

View Source
const (
	// PrefixTaskUndone is the prefix for an unchecked task item.
	PrefixTaskUndone = "- [ ]"
	// PrefixTaskDone is the prefix for a checked (completed) task item.
	PrefixTaskDone = "- [x]"
)

Task checkbox prefixes for Markdown task lists.

View Source
const (
	// TagSystemReminderOpen is the opening tag for system reminders.
	TagSystemReminderOpen = "<system-reminder>"
	// TagSystemReminderClose is the closing tag for system reminders.
	TagSystemReminderClose = "</system-reminder>"
)

System reminder tags injected by Claude Code into tool results.

View Source
const (
	// ObsidianDirName is the default output directory for the Obsidian vault
	// within .context/.
	ObsidianDirName = "journal-obsidian"
	// ObsidianDirEntries is the subdirectory for journal entry files.
	ObsidianDirEntries = "entries"
	// ObsidianConfigDir is the Obsidian configuration directory name.
	ObsidianConfigDir = ".obsidian"
)

Obsidian vault output directory constants.

View Source
const (
	// ObsidianAppConfig is the minimal app.json content that enforces
	// wikilink mode and shows frontmatter properties.
	ObsidianAppConfig = `{
  "useMarkdownLinks": false,
  "showFrontmatter": true,
  "strictLineBreaks": false
}
`
	// ObsidianAppConfigFile is the Obsidian app configuration filename.
	ObsidianAppConfigFile = "app.json"
)

Obsidian vault configuration.

View Source
const (
	// ObsidianMOCPrefix is prepended to MOC filenames so they sort first
	// in the Obsidian file explorer.
	ObsidianMOCPrefix = "_"
	// ObsidianHomeMOC is the root navigation hub filename.
	ObsidianHomeMOC = "Home.md"
	// ObsidianTopicsMOC is the topics index MOC filename.
	ObsidianTopicsMOC = "_Topics.md"
	// ObsidianFilesMOC is the key files index MOC filename.
	ObsidianFilesMOC = "_Key Files.md"
	// ObsidianTypesMOC is the session types index MOC filename.
	ObsidianTypesMOC = "_Session Types.md"
)

Obsidian MOC (Map of Content) page filenames.

View Source
const (
	// ObsidianWikilinkFmt formats a wikilink with display text.
	// Args: target, display.
	ObsidianWikilinkFmt = "[[%s|%s]]"
	// ObsidianWikilinkPlain formats a plain wikilink (no display text).
	// Args: target.
	ObsidianWikilinkPlain = "[[%s]]"
	// ObsidianRelatedHeading is the section heading for the related footer.
	ObsidianRelatedHeading = "## Related Sessions"
	// ObsidianSeeAlso is the label for the see-also section in the footer.
	ObsidianSeeAlso = "**See also**:"
)

Obsidian vault format templates.

View Source
const (
	// NewlineCRLF is the Windows new line.
	//
	// We check NewlineCRLF first, then NewlineLF to handle both formats.
	NewlineCRLF = "\r\n"
	// NewlineLF is Unix new line.
	NewlineLF = "\n"
	// Whitespace is the set of inline whitespace characters (space and tab).
	Whitespace = " \t"
	// Separator is a Markdown horizontal rule used between sections.
	Separator = "---"
	// Ellipsis is a Markdown ellipsis.
	Ellipsis = "..."
	// HeadingLevelOneStart is the Markdown heading for the first section.
	HeadingLevelOneStart = "# "
	// HeadingLevelTwoStart is the Markdown heading for subsequent sections.
	HeadingLevelTwoStart = "## "
	// CodeFence is the standard Markdown code fence delimiter.
	CodeFence = "```"
	// Backtick is a single backtick character.
	Backtick = "`"
	// PipeSeparator is the inline separator used between navigation links.
	PipeSeparator = " | "
	// LinkPrefixParent is the relative link prefix to the parent directory.
	LinkPrefixParent = "../"
	// PrefixHeading is the Markdown heading character used for prefix checks.
	PrefixHeading = "#"
	// PrefixBracket is the opening bracket used for placeholder checks.
	PrefixBracket = "["
	// LoopComplete is the banner printed when the loop finishes.
	LoopComplete = "=== Loop Complete ==="
	// TomlNavOpen is the opening bracket for the TOML nav array.
	TomlNavOpen = "nav = ["
	// TomlNavSectionClose closes a nav section group.
	TomlNavSectionClose = "  ]}"
	// TomlNavClose closes the top-level nav array.
	TomlNavClose = "]"
)
View Source
const (
	// TplTask formats a task checkbox line.
	// Args: content, priorityTag, timestamp.
	TplTask = "- [ ] %s%s #added:%s\n"

	// TplTaskPriority formats the inline priority tag.
	// Args: priority level.
	TplTaskPriority = " #priority:%s"

	// TplLearning formats a learning section with all ADR-style fields.
	// Args: timestamp, title, context, lesson, application.
	TplLearning = `## [%s] %s

**Context**: %s

**Lesson**: %s

**Application**: %s
`

	// TplConvention formats a convention list item.
	// Args: content.
	TplConvention = "- %s\n"

	// TplDecision formats a decision section with all ADR fields.
	// Args: timestamp, title, context, title (repeated), rationale, consequences.
	TplDecision = `## [%s] %s

**Status**: Accepted

**Context**: %s

**Decision**: %s

**Rationale**: %s

**Consequences**: %s
`
)

Markdown format templates for context entries.

These templates define the structure of entries written to .context/ files by the add command. Each uses fmt.Sprintf verbs for interpolation.

View Source
const (
	// TplJournalSiteReadme formats the README for the journal-site directory.
	// Args: journalDir.
	TplJournalSiteReadme = `# journal-site (generated)

This directory is generated by ` + "`ctx journal site`" + ` and is read-only.
Do not edit files here — changes will be overwritten on the next run.

## To update

1. Edit source entries in ` + "`%s/`" + `
2. Regenerate:

` + "```" + `
ctx journal site          # generate
ctx journal site --serve  # generate and preview
` + "```" + `
`

	// TplJournalIndexIntro is the introductory line on the journal index.
	TplJournalIndexIntro = "Browse your AI session history."

	// TplJournalIndexStats formats the session/suggestion count line.
	// Args: regular count, suggestion count.
	TplJournalIndexStats = "**Sessions**: %d | **Suggestions**: %d"

	// TplJournalSuggestionsNote is the description under the suggestions heading.
	TplJournalSuggestionsNote = "*Auto-generated suggestion prompts from Claude Code.*"

	// TplJournalMonthHeading formats a month section heading.
	// Args: month string (YYYY-MM).
	TplJournalMonthHeading = "## %s"

	// TplJournalIndexEntry formats a single entry in the journal index.
	// Args: timeStr, title, link, project, size.
	TplJournalIndexEntry = "- %s[%s](%s.md)%s `%s`"

	// TplJournalSourceLink formats the "View source" link injected into entries.
	// Args: absPath, relPath, relPath.
	TplJournalSourceLink = `*[View source](file://%s) · <code>%s</code>*` +
		` <button onclick="navigator.clipboard.writeText('%s')" title="Copy path"` +
		` style="cursor:pointer;border:none;background:none;font-size:0.8em;vertical-align:middle">` +
		`&#x2398;</button>`

	// TplJournalTopicStats formats the topics index summary line.
	// Args: topic count, session count, popular count, longtail count.
	TplJournalTopicStats = "**%d topics** across **%d sessions**— **%d popular**, **%d long-tail**"

	// TplJournalTopicPageStats formats an individual topic page summary.
	// Args: session count.
	TplJournalTopicPageStats = "**%d sessions** with this topic."

	// TplJournalFileStats formats the key files index summary line.
	// Args: file count, session count, popular count, longtail count.
	TplJournalFileStats = "**%d files** across **%d sessions** — **%d popular**, **%d long-tail**"

	// TplJournalFilePageStats formats an individual key file page summary.
	// Args: session count.
	TplJournalFilePageStats = "**%d sessions** touching this file."

	// TplJournalTypeStats formats the session types index summary line.
	// Args: type count, session count.
	TplJournalTypeStats = "**%d types** across **%d sessions**"

	// TplJournalTypePageStats formats an individual type page summary.
	// Args: session count, type name.
	TplJournalTypePageStats = "**%d sessions** of type *%s*."

	// TplJournalPageHeading formats a Markdown heading for an index page.
	// Args: name.
	TplJournalPageHeading = "# %s"

	// TplJournalCodePageHeading formats a Markdown heading with code styling.
	// Args: path.
	TplJournalCodePageHeading = "# `%s`"

	// TplJournalSubpageEntry formats a session link on a subpage (topic, file, type).
	// Args: timeStr, title, linkPrefix, link.
	TplJournalSubpageEntry = "- %s[%s](%s%s.md)"

	// TplJournalLongtailEntry formats an inline longtail topic entry.
	// Args: name, title, link.
	TplJournalLongtailEntry = "- **%s** — [%s](../%s.md)"

	// TplJournalLongtailCodeEntry formats an inline longtail key file entry.
	// Args: path, title, link.
	TplJournalLongtailCodeEntry = "- `%s` — [%s](../%s.md)"

	// TplJournalNavItem formats a navigation item in zensical.toml.
	// Args: label, path.
	TplJournalNavItem = `  { "%s" = "%s" },`

	// TplJournalNavSection formats a navigation section opening.
	// Args: label.
	TplJournalNavSection = `  { "%s" = [`

	// TplJournalNavSessionItem formats a session entry in navigation.
	// Args: title, filename.
	TplJournalNavSessionItem = `    { "%s" = "%s" },`

	// TplZensicalProject is the [project] section of zensical.toml.
	TplZensicalProject = `` /* 535-byte string literal not displayed */

	// TplZensicalTheme is the theme and extras section of zensical.toml.
	TplZensicalTheme = `` /* 721-byte string literal not displayed */

)

Journal site format templates.

These templates define the structure of generated journal site pages. Each uses fmt.Sprintf verbs for interpolation.

View Source
const (
	// TplLoadBudget formats the token budget summary line.
	// Args: budget, totalTokens.
	TplLoadBudget = "Token Budget: %d | Available: %d"

	// TplLoadTruncated formats the truncation notice for budget-limited output.
	// Args: fileName.
	TplLoadTruncated = "*[Truncated: %s and remaining files excluded due to token budget]*"

	// TplLoadSectionHeading formats a file section heading in assembled output.
	// Args: title.
	TplLoadSectionHeading = "## %s"

	// TplLoopScript is the bash script template for the Ralph Loop.
	// Args: promptFile, completionMsg, maxIterCheck, aiCommand, loopComplete.
	TplLoopScript = `` /* 1079-byte string literal not displayed */

	// TplLoopMaxIter is the iteration-limit check block for the loop script.
	// Args: maxIterations, maxIterations.
	TplLoopMaxIter = `` /* 131-byte string literal not displayed */

)

Agent load and loop script templates.

View Source
const (
	// TplRecallFilename formats a journal entry filename.
	// Args: date, slug, shortID.
	TplRecallFilename = "%s-%s-%s.md"

	// TplRecallTokens formats the token stats line.
	// Args: total, in, out.
	TplRecallTokens = "**Tokens**: %s (in: %s, out: %s)" //nolint:gosec // G101: display template, not a credential

	// TplRecallPartOf formats the part indicator.
	// Args: part, totalParts.
	TplRecallPartOf = "**Part %d of %d**"

	// TplRecallConversationContinued formats the continued conversation heading.
	// Args: previous part number.
	TplRecallConversationContinued = "## Conversation (continued from part %d)"

	// TplRecallTurnHeader formats a conversation turn heading.
	// Args: msgNum, role, time.
	TplRecallTurnHeader = "### %d. %s (%s)"

	// TplRecallToolUse formats a tool use line.
	// Args: formatted tool name and args.
	TplRecallToolUse = "🔧 **%s**"

	// TplRecallToolCount formats a tool usage count line.
	// Args: name, count.
	TplRecallToolCount = "- %s: %d"

	// TplRecallSummaryPlaceholder is the placeholder text in the summary section.
	TplRecallSummaryPlaceholder = "[Add your summary of this session]"

	// TplRecallErrorMarker is the error indicator for tool results.
	TplRecallErrorMarker = "❌ Error"

	// TplRecallDetailsSummary formats the summary text for collapsible content.
	// Args: line count.
	TplRecallDetailsSummary = "%d lines"

	// TplRecallDetailsOpen formats the opening HTML for collapsible content.
	// Args: summary text.
	TplRecallDetailsOpen = "<details>\n<summary>%s</summary>"

	// TplRecallDetailsClose is the closing HTML for collapsible content.
	TplRecallDetailsClose = "</details>"

	// TplRecallFencedBlock formats content inside code fences.
	// Args: fence, content, fence.
	TplRecallFencedBlock = "%s\n%s\n%s"

	// TplRecallNavPrev formats the previous part navigation link.
	// Args: filename.
	TplRecallNavPrev = "[← Previous](%s)"

	// TplRecallNavNext formats the next part navigation link.
	// Args: filename.
	TplRecallNavNext = "[Next →](%s)"

	// TplRecallPartFilename formats a multi-part filename.
	// Args: baseName, part.
	TplRecallPartFilename = "%s-p%d.md"
)

Recall export format templates.

These templates define the structure of exported session transcripts. Each uses fmt.Sprintf verbs for interpolation.

View Source
const (
	// DefaultSessionFilename is the fallback filename component when
	// sanitization produces an empty string.
	DefaultSessionFilename = "session"
)

Session defaults.

View Source
const (
	// FileContextRC is the optional runtime configuration file.
	FileContextRC = ".contextrc"
)

Runtime configuration constants.

View Source
const (
	// LabelSuggestionMode identifies suggestion mode sessions in journal content.
	LabelSuggestionMode = "SUGGESTION MODE:"
)

Journal content markers for detecting session modes.

View Source
const (
	// LoadHeadingContext is the top-level heading for assembled context output.
	LoadHeadingContext = "# Context"
)

Load command headings

View Source
const (
	// LoopHeadingStart is the heading shown after loop script generation.
	LoopHeadingStart = "To start the loop:"
)

Loop command headings

View Source
const (
	// MarkTaskComplete is the unchecked task marker.
	MarkTaskComplete = "x"
)
View Source
const MaxDecisionsToSummarize = 3

MaxDecisionsToSummarize is the number of recent decisions to include in summaries.

View Source
const MaxLearningsToSummarize = 5

MaxLearningsToSummarize is the number of recent learnings to include in summaries.

View Source
const MaxPreviewLen = 60

MaxPreviewLen is the maximum length for preview lines before truncation.

View Source
const (
	// MinContentLen is the minimum byte length for a file to be considered
	// non-empty by the effectively-empty heuristic.
	MinContentLen = 20
)

Content detection constants.

View Source
const ObsidianReadme = `# journal-obsidian (generated)

This directory is generated by ` + "`ctx journal obsidian`" + ` and is read-only.
Do not edit files here — changes will be overwritten on the next run.

## To update

1. Edit source entries in ` + "`%s/`" + `
2. Regenerate:

` + "```" + `
ctx journal obsidian
` + "```" + `

## Usage

Open this directory as an Obsidian vault:

1. Open Obsidian
2. Choose "Open folder as vault"
3. Select this directory
`

Obsidian vault README template.

View Source
const (
	// ParserPeekLines is the number of lines to scan when detecting file format.
	ParserPeekLines = 50
)

Parser configuration.

Variables

View Source
var DefaultClaudePermissions = []string{
	"Bash(ctx:*)",
	"Skill(ctx-add-convention)",
	"Skill(ctx-add-decision)",
	"Skill(ctx-add-learning)",
	"Skill(ctx-add-task)",
	"Skill(ctx-agent)",
	"Skill(ctx-alignment-audit)",
	"Skill(ctx-archive)",
	"Skill(ctx-blog)",
	"Skill(ctx-blog-changelog)",
	"Skill(ctx-borrow)",
	"Skill(ctx-commit)",
	"Skill(ctx-context-monitor)",
	"Skill(ctx-drift)",
	"Skill(ctx-implement)",
	"Skill(ctx-journal-enrich)",
	"Skill(ctx-journal-enrich-all)",
	"Skill(ctx-journal-normalize)",
	"Skill(ctx-loop)",
	"Skill(ctx-next)",
	"Skill(ctx-pad)",
	"Skill(ctx-prompt-audit)",
	"Skill(ctx-recall)",
	"Skill(ctx-reflect)",
	"Skill(ctx-remember)",
	"Skill(ctx-status)",
	"Skill(ctx-worktree)",
}

DefaultClaudePermissions lists the default permissions for ctx commands and skills.

These permissions allow Claude Code to run ctx CLI commands and skills without prompting for approval. The Bash wildcard covers all ctx subcommands; the Skill entries cover all ctx-shipped skills.

View Source
var EntryPlural = map[string]string{
	EntryTask:       "tasks",
	EntryDecision:   "decisions",
	EntryLearning:   "learnings",
	EntryConvention: "conventions",
}

EntryPlural maps entry type constants to their plural forms.

Used for user-facing messages (e.g., "no decisions found").

FileReadOrder defines the priority order for reading context files.

The order follows a logical progression for AI agents:

  1. CONSTITUTION — Inviolable rules. Must be loaded first so the agent knows what it cannot do before attempting anything.

  2. TASKS — Current work items. What the agent should focus on.

  3. CONVENTIONS — How to write code. Patterns and standards to follow.

  4. ARCHITECTURE — System structure. Understanding of components and boundaries before making changes.

  5. DECISIONS — Historical context. Why things are the way they are, to avoid re-debating settled decisions.

  6. LEARNINGS — Gotchas and tips. Lessons from past work that inform current implementation.

  7. GLOSSARY — Reference material. Domain terms and abbreviations for lookup as needed.

  8. AGENT_PLAYBOOK — Meta instructions. How to use this context system. Loaded last because it's about the system itself, not the work. The agent should understand the content before the operating manual.

View Source
var FileType = map[string]string{
	EntryDecision:   FileDecision,
	EntryTask:       FileTask,
	EntryLearning:   FileLearning,
	EntryConvention: FileConvention,
}

FileType maps short names to actual file names.

FilesRequired lists the essential context files that must be present.

These are the files created with `ctx init --minimal` and checked by drift detection for missing files.

View Source
var GitignoreEntries = []string{
	".context/sessions/",
	".context/journal/",
	".context/journal-site/",
	".context/journal-obsidian/",
	".context/logs/",
	".context/.scratchpad.key",
	".claude/settings.local.json",
}

GitignoreEntries lists the recommended .gitignore entries added by ctx init.

View Source
var Packages = map[string]string{
	"package.json":     "Node.js dependencies",
	"go.mod":           "Go module dependencies",
	"Cargo.toml":       "Rust dependencies",
	"requirements.txt": "Python dependencies",
	"Gemfile":          "Ruby dependencies",
}

Packages maps dependency manifest files to their descriptions.

Used by sync to detect projects and suggest dependency documentation.

View Source
var Patterns = []Pattern{
	{".eslintrc*", "linting conventions"},
	{".prettierrc*", "formatting conventions"},
	{"tsconfig.json", "TypeScript configuration"},
	{".editorconfig", "editor configuration"},
	{"Makefile", "build commands"},
	{"Dockerfile", "containerization"},
}

Patterns lists config files that should be documented in CONVENTIONS.md.

Used by sync to suggest documenting project configuration.

View Source
var RegExBulletItem = regexp.MustCompile(`(?m)^-\s*(.+)$`)

RegExBulletItem matches any Markdown bullet item (not just tasks).

Groups:

  • 1: item content
View Source
var RegExCodeFenceClose = regexp.MustCompile("(```+) *(\\S)")

RegExCodeFenceClose matches code fences immediately followed by text. E.g., "```text" where text should be on its own line after the fence. Groups:

  • 1: the code fence (3+ backticks)
  • 2: following non-whitespace character
View Source
var RegExCodeFenceInline = regexp.MustCompile("(\\S) *(```+)")

RegExCodeFenceInline matches code fences that appear inline after text. E.g., "some text: ```code" where fence should be on its own line. Groups:

  • 1: preceding non-whitespace character
  • 2: the code fence (3+ backticks)
View Source
var RegExContextUpdate = regexp.MustCompile(`<context-update(\s+[^>]+)>([^<]+)</context-update>`)

RegExContextUpdate matches context-update XML tags.

Groups:

  • 1: opening tag attributes (e.g., ` type="task" context="..."`)
  • 2: content between tags
View Source
var RegExDecision = regexp.MustCompile(`(?m)^## \[\d{4}-\d{2}-\d{2}-\d{6}].*$`)

RegExDecision matches decision entry headers in multiline content. Use for finding decision positions without capturing groups.

View Source
var RegExDecisionPatterns = []*regexp.Regexp{
	regexp.MustCompile(`(?i)decided to\s+(.{20,100})`),
	regexp.MustCompile(`(?i)decision:\s*(.{20,100})`),
	regexp.MustCompile(`(?i)we('ll| will) use\s+(.{10,80})`),
	regexp.MustCompile(`(?i)going with\s+(.{10,80})`),
	regexp.MustCompile(`(?i)chose\s+(.{10,80})\s+(over|instead)`),
}

RegExDecisionPatterns detects decision-like phrases in text.

View Source
var RegExEntryHeader = regexp.MustCompile(
	`## \[(\d{4}-\d{2}-\d{2})-(\d{6})] (.+)`,
)

RegExEntryHeader matches entry headers like "## [2026-01-28-051426] Title here".

Groups:

  • 1: date (YYYY-MM-DD)
  • 2: time (HHMMSS)
  • 3: title
View Source
var RegExEntryHeading = regexp.MustCompile(`(?m)^## \[`)

RegExEntryHeading matches any entry heading (## [timestamp]). Use for counting entries without capturing groups.

View Source
var RegExFenceLine = regexp.MustCompile("^\\s*(`{3,}|~{3,})(.*)$")

RegExFenceLine matches lines that are code fence markers (3+ backticks or tildes, optionally followed by a language tag).

View Source
var RegExFencesVerified = regexp.MustCompile(`<!-- fences-verified: \d{4}-\d{2}-\d{2} -->`)

RegExFencesVerified matches the marker left after AI fence reconstruction. Only files with this marker skip fence stripping in the site pipeline.

View Source
var RegExGlobStar = regexp.MustCompile(`\*(\.\w+|[/)])`)

RegExGlobStar matches glob-like wildcards: *.ext, */, *) etc.

View Source
var RegExGlossary = regexp.MustCompile(`(?m)(?:^|\n)\s*(?:-\s*)?\*\*[^*]+\*\*`)

RegExGlossary matches glossary definition entries (lines with **term**).

View Source
var RegExLearning = regexp.MustCompile(`(?m)^- \*\*\[\d{4}-\d{2}-\d{2}]\*\*.*$`)

RegExLearning matches learning entry headers in multiline content. Use for finding learning positions without capturing groups.

View Source
var RegExLearningPatterns = []*regexp.Regexp{
	regexp.MustCompile(`(?i)learned that\s+(.{20,100})`),
	regexp.MustCompile(`(?i)gotcha:\s*(.{20,100})`),
	regexp.MustCompile(`(?i)lesson:\s*(.{20,100})`),
	regexp.MustCompile(`(?i)TIL:?\s*(.{20,100})`),
	regexp.MustCompile(`(?i)turns out\s+(.{20,100})`),
	regexp.MustCompile(`(?i)important to (note|remember):\s*(.{20,100})`),
}

RegExLearningPatterns detects learning-like phrases in text.

View Source
var RegExLineNumber = regexp.MustCompile(`(?m)^\s*\d+→`)

RegExLineNumber matches Claude Code's line number prefixes like " 1→".

View Source
var RegExMultiPart = regexp.MustCompile(`-p\d+\.md$`)

RegExMultiPart matches session part files like "...-p2.md", "...-p3.md", etc.

View Source
var RegExNonFileNameChar = regexp.MustCompile(`[^a-zA-Z0-9-]+`)

RegExNonFileNameChar matches characters not allowed in file names.

View Source
var RegExNormalizedMarker = regexp.MustCompile(`<!-- normalized: \d{4}-\d{2}-\d{2} -->`)

RegExNormalizedMarker matches the metadata normalization marker (normalize.py).

View Source
var RegExPath = regexp.MustCompile("`([^`]+\\.[a-zA-Z]{1,5})`")

RegExPath matches file paths in Markdown backticks.

Groups:

  • 1: file path
View Source
var RegExPhase = regexp.MustCompile(`^#{1,6}\s+Phase`)

RegExPhase matches phase headers at any heading level (e.g., "## Phase 1", "### Phase").

View Source
var RegExSystemReminder = regexp.MustCompile(`(?s)<system-reminder>\s*(.*?)\s*</system-reminder>`)

RegExSystemReminder matches <system-reminder>...</system-reminder> blocks. These are injected by Claude Code into tool results. Groups:

  • 1: content between tags
View Source
var RegExTask = regexp.MustCompile(regExTaskPattern)

RegExTask matches a task item on a single line.

Use with MatchString or FindStringSubmatch on individual lines. For multiline content, use RegExTaskMultiline.

View Source
var RegExTaskDoneTimestamp = regexp.MustCompile(`#done:(\d{4}-\d{2}-\d{2}-\d{6})`)

RegExTaskDoneTimestamp extracts the #done: timestamp from a task line.

Groups:

  • 1: timestamp (YYYY-MM-DD-HHMMSS)
View Source
var RegExTaskMultiline = regexp.MustCompile(`(?m)` + regExTaskPattern)

RegExTaskMultiline matches task items across multiple lines.

Use with FindAllStringSubmatch on multiline content.

View Source
var RegExToolBold = regexp.MustCompile(`🔧\s*\*\*(.+?)\*\*`)

RegExToolBold matches tool-use lines like "🔧 **Glob: .context/journal/*.md**".

View Source
var RegExTurnHeader = regexp.MustCompile(`^### (\d+)\. (.+?) \((\d{2}:\d{2}:\d{2})\)$`)

RegExTurnHeader matches conversation turn headers.

Groups:

  • 1: turn number
  • 2: role (e.g. "Assistant", "Tool Output")
  • 3: timestamp (HH:MM:SS)

Functions

func RegExFromAttrName added in v0.2.0

func RegExFromAttrName(name string) *regexp.Regexp

RegExFromAttrName creates a regex to extract an XML attribute value by name.

Parameters:

  • name: The attribute name to match

Returns:

  • *regexp.Regexp: Pattern matching name="value" with value in group 1

func UserInputToEntry added in v0.2.0

func UserInputToEntry(s string) string

UserInputToEntry normalizes user input to a canonical entry type.

Accepts both singular and plural forms (e.g., "task" or "tasks") and returns the canonical singular form. Matching is case-insensitive. Unknown inputs return EntryUnknown.

Parameters:

  • s: User-provided entry type string

Returns:

  • string: Canonical entry type constant (EntryTask, EntryDecision, etc.)

Types

type Pattern

type Pattern struct {
	Pattern string
	Topic   string
}

Pattern represents a config file pattern and its documentation topic.

Fields:

  • Pattern: Glob pattern to match (e.g., ".eslintrc*")
  • Topic: Documentation topic (e.g., "linting conventions")

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL