config

package
v0.2.2 Latest Latest
Warning

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

 Go to latest Published: Jun 14, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// SystemPromptModeDefault (or "" / unset) means the teammate inherits
	// the host's universal base block and teammate addendum;
	// cfg.SystemPrompt is wrapped as "# Custom Agent Instructions" inside
	// the role block. Recommended path for new role-specific agents.
	SystemPromptModeDefault = "default"

	// SystemPromptModeReplace skips both the universal base and the
	// teammate addendum; cfg.SystemPrompt becomes the only SystemBlock.
	// Use when the agent definition is already a complete self-contained
	// prompt.
	SystemPromptModeReplace = "replace"

	// SystemPromptModeAppend builds the default composition and then
	// appends cfg.SystemPrompt at the end of the role block — rare, only
	// when an agent needs to add tail content on top of the default.
	SystemPromptModeAppend = "append"
)

SystemPromptMode* are the host-recognized values for agentcore/subagent.Config.SystemPromptMode. The enum stays as untyped string constants because agentcore stores it as a string hint and codebot is the only consumer that interprets it.

View Source 
const ConfigDir = ".codebot"

ConfigDir is the project-level config directory name.

View Source 
const SuggestionPrompt = `` /* 1132-byte string literal not displayed */

SuggestionPrompt is the instruction appended as a user message to generate a prompt suggestion after the agent completes a turn.

Variables

This section is empty.

Functions

func ApprovalsPath added in v0.0.4 

func ApprovalsPath(cwd string) string

ApprovalsPath returns ~/.codebot/approvals/<projectID>.json.

func AuditLogPath added in v0.0.2 

func AuditLogPath() string

AuditLogPath returns ~/.codebot/audit.log.

func BuildAutoMemoryInstructions added in v0.0.4 

func BuildAutoMemoryInstructions(memoryDir string) string

BuildAutoMemoryInstructions returns the system prompt instructions that teach the LLM how to use auto memory. Returns empty string when memoryDir is empty (e.g. no user config dir).

func BuildDynamicSystemPart added in v0.1.3 

func BuildDynamicSystemPart(mcpTools []ToolInfo, overlays []string) string

BuildDynamicSystemPart assembles the runtime-mutable portion of the system prompt: late-arriving tool descriptions (MCP) and named overlays (plan_mode, mcp instructions, etc.).

Returns "" when neither input contributes content; callers should then omit the third system block entirely.

overlays must be passed in a deterministic order — the same content in a different order changes the hash and uselessly breaks any cache placed on this segment by the caller.

func BuildFrozenSystemParts added in v0.1.3 

func BuildFrozenSystemParts(cwd string, ctx ContextFiles, localTools []ToolInfo) (identity, frozenInstructions string)

BuildFrozenSystemParts returns the static portions of the system prompt that are fixed for the lifetime of the process: the universal base (agent-agnostic, returned as identity for backwards compatibility) and the leader role block (returned as frozenInstructions).

Inputs MUST be process-stable. MCP tools, plan_mode overlays, and any runtime-mutable content belong in BuildDynamicSystemPart.

When ctx.SystemOverride is set, identity is empty and frozenInstructions is the override verbatim.

Existing callers (session_prompt.go) keep the same two-block cache layout: block 0 = identity = universal base, block 1 = frozenInstructions = leader role block. Cache footprint and shape are unchanged from the pre-refactor behavior; only the content split between the two blocks moved.

func BuildLeaderRoleBlock added in v0.2.0 

func BuildLeaderRoleBlock(ctx ContextFiles, localTools []ToolInfo) string

BuildLeaderRoleBlock returns the leader-specific portion of the system prompt: leader identity, the leader's own tool inventory, the optional Task Management section (gated on task_* tools being present), the optional Team coordination section (gated on team_*+send_message+subagent), and the optional auto-memory hints.

localTools should be the leader's session-stable tool set (caller already filtered out MCP via SplitToolsByOrigin). The list is rendered verbatim so pass it in the order callers want the model to see.

Goes in the second SystemBlock with cache_control="ephemeral".

func BuildReminders added in v0.0.2 

func BuildReminders(ctx ContextFiles, skills []skill.Spec) []string

BuildReminders extracts skills and context files into <system-reminder> wrapped text fragments for injection into user messages. Returns nil when there are no reminders to inject.

Today's date is surfaced here (not in the system prompt) so that the system prefix stays identical across days and prompt cache can hit.

func BuildSystemBlockTexts added in v0.0.2 

func BuildSystemBlockTexts(cwd string, ctx ContextFiles, tools []ToolInfo) (identity, instructions string)

BuildSystemBlockTexts is a backward-compatible wrapper. It splits tools by origin internally and concatenates frozen + dynamic into a single instructions string for callers that haven't migrated to the two-block layout yet.

New code should call BuildFrozenSystemParts + BuildDynamicSystemPart directly so the static prefix can be cached independently.

func BuildTeammateRoleBlock added in v0.2.0 

func BuildTeammateRoleBlock(localTools []ToolInfo, agentRolePrompt string) string

BuildTeammateRoleBlock returns the teammate-specific portion of the system prompt: identity preamble, tool inventory, mailbox/coordination addendum, and (when set) the agent definition's custom prompt under "# Custom Agent Instructions". localTools is the effective tool set (Config.Tools + injected coordination tools); empty/nil omits the tool list. Lives in the second SystemBlock with cache_control="ephemeral".

func BuildUniversalBase added in v0.2.0 

func BuildUniversalBase(cwd string) string

BuildUniversalBase returns the agent-agnostic head of the system prompt: neutral identity preamble, environment metadata, and the five shared conventions (parallel exec / doing tasks / using your tools / system conventions / output efficiency). Tool inventory is deliberately NOT here — leader and teammate have different tool sets, so listing tools in the shared prefix would break the byte-equality precondition for cross-agent prompt cache reuse.

Inputs MUST be process-stable: cwd does not change inside a session, OS metadata is fixed at compile time. MCP tools and runtime overlays go in BuildDynamicSystemPart, never here.

This is the first SystemBlock of both leader and teammate AgentContexts, both with cache_control="ephemeral". When the leader has run a few turns, Anthropic's server-side cache holds these bytes; a fresh teammate's first request hits the same key and reads from cache instead of paying full input-token cost.

func CollectGitSnapshot added in v0.0.4 

func CollectGitSnapshot(cwd string) string

CollectGitSnapshot runs git commands in cwd and returns a formatted snapshot suitable for LLM system prompt injection. Returns empty string when cwd is not a git repository.

func CommandsDir added in v0.0.2 

func CommandsDir(cwd string) string

CommandsDir returns <cwd>/.codebot/commands/.

func DefaultModelName 

func DefaultModelName(prov string) string

DefaultModelName returns the default model name for a given provider.

func DetectEnvProvider added in v0.0.2 

func DetectEnvProvider() (providerName, envKey string)

DetectEnvProvider scans every registered litellm provider for available env credentials. Returns the first match's provider name and env var key.

func EnsureMemoryDir added in v0.0.4 

func EnsureMemoryDir(cwd string)

EnsureMemoryDir creates the memory directory if it doesn't exist.

func EnvCredentials 

func EnvCredentials(prov string) (apiKey, baseURL string)

EnvCredentials reads the API key and base URL from the standard env vars derived from the provider name.

func ExpandHome added in v0.0.4 

func ExpandHome(path string) string

func ExploreSubAgentPrompt 

func ExploreSubAgentPrompt(cwd string) string

ExploreSubAgentPrompt returns the system prompt for the explore sub-agent.

func FormatModelID 

func FormatModelID(provider, model string) string

FormatModelID combines provider and model into "provider/model". If model already contains "/", it is returned as-is.

func GeneralPurposeSubAgentPrompt added in v0.2.0 

func GeneralPurposeSubAgentPrompt(cwd string) string

GeneralPurposeSubAgentPrompt returns the system prompt for the general-purpose sub-agent.

func GlobalConfigExists added in v0.1.0 

func GlobalConfigExists() bool

GlobalConfigExists reports whether ~/.codebot/settings.json exists.

func GlobalSettingsPath added in v0.1.0 

func GlobalSettingsPath() string

GlobalSettingsPath returns ~/.codebot/settings.json.

func IsGitRepo added in v0.2.0 

func IsGitRepo(cwd string) bool

IsGitRepo reports whether cwd is inside a git working tree.

func IsKnownSystemPromptMode added in v0.2.0 

func IsKnownSystemPromptMode(s string) bool

IsKnownSystemPromptMode reports whether s is one of the modes this package understands. Empty string is treated as known (it falls back to Default).

func IsMCPTool added in v0.1.3 

func IsMCPTool(name string) bool

IsMCPTool reports whether a tool name belongs to an MCP server.

func LoadMemory added in v0.0.4 

func LoadMemory(cwd string) (content, dir string)

LoadMemory reads MEMORY.md (first 200 lines) and returns the content along with the memory directory path. Returns empty strings when no memory file exists.

func MemoryDir added in v0.0.4 

func MemoryDir(cwd string) string

MemoryDir returns ~/.codebot/projects/<projectID>/memory/.

func MemoryFilePath added in v0.0.4 

func MemoryFilePath(cwd string) string

MemoryFilePath returns the path to MEMORY.md.

func PatchGlobalSettings added in v0.0.2 

func PatchGlobalSettings(patch Settings) error

PatchGlobalSettings loads the global settings, applies the patch, and saves back. Only non-nil fields in patch are updated.

func PatchProjectSettings added in v0.0.2 

func PatchProjectSettings(cwd string, patch Settings) error

PatchProjectSettings loads project-level settings, applies the patch, and saves back.

func PlanSubAgentPrompt 

func PlanSubAgentPrompt(cwd string) string

PlanSubAgentPrompt returns the system prompt for the plan sub-agent.

func PlansDir 

func PlansDir(_ string) string

PlansDir returns ~/.codebot/plans/. A single global directory shared across projects; word-slug filenames make collisions vanishingly rare.

func ProjectConfigExists added in v0.0.2 

func ProjectConfigExists(cwd string) bool

ProjectConfigExists reports whether <cwd>/.codebot/settings.json exists.

func ProjectSettingsDefinesModel added in v0.1.1 

func ProjectSettingsDefinesModel(cwd string) bool

ProjectSettingsDefinesModel reports whether the project settings file exists and explicitly sets provider or model. Callers use this to decide whether /model persistence should target the project file (so the choice sticks across restarts) or the global file.

func ProviderEnvKey 

func ProviderEnvKey(prov string) string

ProviderEnvKey derives the standard env var name for a provider's API key (e.g. "openai" → "OPENAI_API_KEY"). All provider env conventions follow the same UPPER(name)_API_KEY / UPPER(name)_BASE_URL pattern.

func ResolveConfiguredProviderType added in v0.1.0 

func ResolveConfiguredProviderType(providers map[string]ProviderConfig, name string) (string, error)

ResolveConfiguredProviderType resolves the protocol type for a configured provider.

func ResolveProviderType added in v0.1.0 

func ResolveProviderType(name, explicitType string) (string, error)

ResolveProviderType resolves a provider's protocol type. When explicitType is set it wins (and must be registered); otherwise the provider name itself must be a registered litellm provider.

func RunSetup 

func RunSetup(settings Resolved) error

RunSetup runs an interactive first-time configuration wizard.

func SaveSettings 

func SaveSettings(s Settings) error

SaveSettings writes settings to ~/.codebot/settings.json (global).

func SessionMemoryPath added in v0.1.1 

func SessionMemoryPath(cwd string) string

SessionMemoryPath returns ~/.codebot/projects/<projectID>/session-memory.md. This file is project-scoped (shared across sessions in the same cwd) so that resuming or starting a new session can inherit accumulated context.

func SessionsDir 

func SessionsDir(cwd string) string

SessionsDir returns ~/.codebot/projects/<projectID>/. Sessions are stored globally but scoped by project.

func SettingsPath 

func SettingsPath(cwd string) string

SettingsPath returns <cwd>/.codebot/settings.json.

func SnapshotDir added in v0.2.0 

func SnapshotDir(cwd string) string

SnapshotDir returns ~/.codebot/snapshot/<projectID> — the shadow git repository backing /undo file checkpoints for this project.

func TasksDir 

func TasksDir() string

TasksDir returns ~/.codebot/tasks/.

func TeamDir added in v0.2.0 

func TeamDir(sessionID string) string

TeamDir returns ~/.codebot/tasks/<sessionID>/team/ — the per-session home for team coordination artifacts (roster, teammate transcripts, mailbox backlog) that must survive a restart alongside the durable task list. It lives under the session's task dir so a session's entire coordination state is reclaimed together.

func UndoStatePath added in v0.2.0 

func UndoStatePath(cwd, sessionID string) string

UndoStatePath returns the per-session sidecar that persists /undo's snapshot stack across restarts: ~/.codebot/projects/<projectID>/<sessionID>/undo-stack.json. It sits under the per-session dir alongside bg/ and tool-outputs/.

func UserConfigDir 

func UserConfigDir() string

UserConfigDir returns ~/.codebot/.

Types

type ContextFiles 

type ContextFiles struct {
	// Agents is the concatenated content of all AGENTS.md files found
	// from filesystem root down to cwd, separated by newlines.
	Agents string

	// SystemOverride is the content of SYSTEM.md if found in cwd.
	// When non-empty, it replaces the default system prompt entirely.
	SystemOverride string

	// SystemAppend is the content of APPEND_SYSTEM.md if found in cwd.
	// When non-empty, it is appended to the system prompt.
	SystemAppend string

	// GitSnapshot is the git status snapshot collected at session start.
	// Injected as a separate system block so the LLM knows the repo state.
	GitSnapshot string

	// Memory is the auto memory content (first 200 lines of MEMORY.md).
	Memory string

	// MemoryDir is the absolute path to the memory directory.
	// Used by auto memory instructions to tell the LLM where to write.
	MemoryDir string
}

ContextFiles holds the loaded context file contents.

func LoadContextFiles 

func LoadContextFiles(cwd string) ContextFiles

LoadContextFiles searches for context files from cwd upward to the filesystem root.

Loading order (lowest to highest specificity):

  1. ~/.codebot/AGENTS.md (global user-level, auto-created if missing)
  2. AGENTS.md in each ancestor from root down to cwd

CLAUDE.md is used as fallback when AGENTS.md is not found in a directory. SYSTEM.md and APPEND_SYSTEM.md are only looked for in cwd.

type ExtraCommandSource added in v0.1.0 

type ExtraCommandSource struct {
	Path   string
	Source string
}

type FileCommand added in v0.0.2 

type FileCommand struct {
	Name        string
	Aliases     []string
	Description string
	Usage       string
	Content     string
	Source      string // "user" or "project"
	FilePath    string
	Category    string // prompt/info/session/config/plan/exit
	NeedsIdle   bool
	Hidden      bool
}

FileCommand is a user-defined slash command loaded from a Markdown file. Its body is treated as a prompt template with optional frontmatter metadata.

func LoadCommandsFromDir added in v0.1.0 

func LoadCommandsFromDir(dir, source string) []FileCommand

func LoadFileCommands added in v0.0.2 

func LoadFileCommands(cwd string, extraPaths ...string) []FileCommand

LoadFileCommands discovers and loads Markdown-backed slash commands from user, project, and extra paths (e.g. skill-declared command files). Project commands override user commands; extra paths have lowest priority.

func LoadFileCommandsWithSources added in v0.1.0 

func LoadFileCommandsWithSources(cwd string, extraSources ...ExtraCommandSource) []FileCommand

LoadFileCommandsWithSources discovers Markdown-backed slash commands from user, project, and extra plugin/skill paths. Project commands override user commands; extra paths have lowest priority.

func ValidateCommandsDir added in v0.1.0 

func ValidateCommandsDir(dir, source string) ([]FileCommand, []error)

type HookEntry added in v0.0.2 

type HookEntry struct {
	Type     string            `json:"type"`               // "command", "prompt", or "http"
	Command  string            `json:"command,omitempty"`  // type=command: shell command
	Prompt   string            `json:"prompt,omitempty"`   // type=prompt: LLM prompt ($ARGUMENTS = payload)
	URL      string            `json:"url,omitempty"`      // type=http: POST endpoint
	Headers  map[string]string `json:"headers,omitempty"`  // type=http: request headers
	Matcher  string            `json:"matcher,omitempty"`  // tool name filter: exact or /regex/
	If       string            `json:"if,omitempty"`       // argument content filter: substring or /regex/
	Blocking *bool             `json:"blocking,omitempty"` // can block execution
	Timeout  *int              `json:"timeout,omitempty"`  // seconds (default 60)
}

HookEntry describes a single hook. Supported types: "command" (shell), "prompt" (LLM evaluation), "http" (POST).

type HooksConfig added in v0.0.2 

type HooksConfig map[string][]HookEntry

HooksConfig maps event names to their hook entries.

type PermissionsConfig added in v0.0.4 

type PermissionsConfig struct {
	Allow      []string `json:"allow,omitempty"`
	Deny       []string `json:"deny,omitempty"`
	ReadRoots  []string `json:"read_roots,omitempty"`
	WriteRoots []string `json:"write_roots,omitempty"`
}

PermissionsConfig holds user-defined permission rules.

type ProviderConfig 

type ProviderConfig struct {
	Type       string   `json:"type,omitempty"` // LiteLLM protocol type; required only when the provider name is not a known litellm provider
	APIKey     string   `json:"api_key,omitempty"`
	BaseURL    string   `json:"base_url,omitempty"`
	Models     []string `json:"models,omitempty"`      // available model list for this provider
	SmallModel string   `json:"small_model,omitempty"` // lightweight model for sub-agents
}

ProviderConfig holds credentials and model configuration for a single provider.

func (ProviderConfig) ProviderType added in v0.0.2 

func (pc ProviderConfig) ProviderType(name string) (string, error)

ProviderType resolves the protocol type for this provider. The protocol type maps to a name registered in litellm's provider registry.

type Resolved 

type Resolved struct {
	Provider   string                    // active provider name
	Model      string                    // model name sent to API as-is
	SmallModel string                    // sub-agent model; equals Model when not configured
	Providers  map[string]ProviderConfig // per-provider credentials

	ContextWindow  int     // effective window after applying CompactWindow cap
	CompactWindow  int     // user-configured cap on effective window; 0 = disabled
	CompactRatio   float64 // usage ratio that triggers compaction; 0 = engine default
	ThinkingLevel  string
	MaxTurns       int
	SearchProvider string
	SearchAPIKey   string

	Hooks HooksConfig // lifecycle hooks

	Permissions PermissionsConfig // user-defined permission rules

	Telemetry TelemetryConfig // OTLP trace export config

	Snapshot bool // workspace checkpoints for /undo; defaults on
}

Resolved holds settings resolved to concrete values (no pointers).

func LoadSettingsStrict added in v0.1.0 

func LoadSettingsStrict(cwd string) (Resolved, error)

LoadSettingsStrict loads and merges settings from global (~/.codebot/settings.json) and project (<cwd>/.codebot/settings.json). Project-level values override global. Returns an error when either settings file exists and cannot be parsed.

func ResolveAllStrict added in v0.1.0 

func ResolveAllStrict(cwd string) (Resolved, error)

ResolveAllStrict merges global and project settings, applies defaults, and returns a fully resolved configuration. Refuses to continue when an existing settings file is malformed.

func (Resolved) ProviderCredentials 

func (r Resolved) ProviderCredentials(prov string) (apiKey, baseURL string)

ProviderCredentials returns API key and base URL for the given provider. It checks the providers map first, then falls back to standard environment variables.

type Settings 

type Settings struct {
	Provider   *string                    `json:"provider,omitempty"`    // provider name (matches key in providers map)
	Model      *string                    `json:"model,omitempty"`       // model name sent to API as-is
	SmallModel *string                    `json:"small_model,omitempty"` // sub-agent model; defaults to Model if empty
	Providers  map[string]*ProviderConfig `json:"providers,omitempty"`

	ThinkingLevel *string `json:"thinking_level,omitempty"`

	MaxTurns *int `json:"max_turns,omitempty"`

	// CompactWindow caps the effective context window used for compaction.
	// Effective = min(model's detected window, CompactWindow). 0 = disabled.
	CompactWindow *int `json:"compact_window,omitempty"`
	// CompactRatio triggers compaction when usage >= effective * ratio.
	// Range (0, 1). 0 = engine default (fixed headroom buffer).
	CompactRatio *float64 `json:"compact_ratio,omitempty"`

	SearchProvider *string `json:"search_provider,omitempty"`
	SearchAPIKey   *string `json:"search_api_key,omitempty"`

	Hooks HooksConfig `json:"hooks,omitempty"` // lifecycle hooks

	Permissions *PermissionsConfig `json:"permissions,omitempty"`

	Telemetry *TelemetryConfig `json:"telemetry,omitempty"` // OpenTelemetry trace export

	// Snapshot toggles workspace file checkpoints backing /undo. Unset means on;
	// set false to disable (e.g. on a large repo where per-turn scans lag).
	Snapshot *bool `json:"snapshot,omitempty"`
}

Settings holds application-level configuration. Fields use pointer types so unset fields fall back to defaults.

func (Settings) Resolve 

func (s Settings) Resolve() Resolved

Resolve converts Settings to Resolved using defaults for unset fields.

type TelemetryConfig added in v0.2.0 

type TelemetryConfig struct {
	Enabled   bool   `json:"enabled,omitempty"`
	Endpoint  string `json:"endpoint,omitempty"`   // OTLP/HTTP endpoint URL, e.g. https://cloud.langfuse.com/api/public/otel
	PublicKey string `json:"public_key,omitempty"` // basic-auth username
	SecretKey string `json:"secret_key,omitempty"` // basic-auth password
}

TelemetryConfig configures OpenTelemetry trace export to an OTLP backend (e.g. Langfuse). Telemetry stays off unless Enabled is true.

type ToolInfo 

type ToolInfo struct {
	Name        string
	Description string
}

ToolInfo describes a tool for system prompt generation. Decoupled from agentcore.Tool to avoid package dependency.

func SplitToolsByOrigin added in v0.1.3 

func SplitToolsByOrigin(all []ToolInfo) (local, mcp []ToolInfo)

SplitToolsByOrigin partitions tools into local (session-stable) and MCP (runtime-mutable) buckets so callers can route them to the right frozen/dynamic system block.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.