config

Documentation

Overview

Package config loads and merges odek configuration from multiple sources.

Priority (lowest to highest):

1. ~/.odek/config.json — global defaults (shared across projects)
2. ./odek.json — project-specific overrides
3. ODEK_* env vars — runtime/environment overrides
4. CLI flags — explicit invocation overrides (highest)

Both config files are optional. Missing files are silently ignored. String values in config files support ${VAR} environment variable substitution (e.g. "api_key": "${MY_API_KEY}"). Use $$ for a literal dollar sign.

Index

• Constants
• func GlobalConfigPath() string
• func ProjectConfigPath() string
• type CLIFlags
• type FileConfig
• type ResolvedConfig
  • func LoadConfig(cli CLIFlags) ResolvedConfig
• type SkillsConfig
• type TranscriptionConfig

Constants

const (
	DefaultSandboxNetwork = "none"
)

Functions

func GlobalConfigPath

func GlobalConfigPath() string

GlobalConfigPath returns the path to the global config file. Uses $HOME/.odek/config.json.

func ProjectConfigPath

func ProjectConfigPath() string

ProjectConfigPath returns the path to the project-level config file. Uses ./odek.json relative to the current working directory.

Types

type CLIFlags

type CLIFlags struct {
	Model    string
	BaseURL  string
	System   string
	Thinking string
	MaxIter  int   // 0 = not set
	Sandbox  *bool // nil = not set
	NoColor  *bool // nil = not set
	NoAgents *bool // nil = not set
	Learn    *bool // nil = not set
	Task     string

	// PromptCaching enables prompt caching markers for supported providers.
	// Config: prompt_caching, ODEK_PROMPT_CACHING, --prompt-caching.
	PromptCaching *bool // nil = not set

	// Sandbox-specific
	SandboxImage    string
	SandboxNetwork  string
	SandboxMemory   string
	SandboxCPUs     string
	SandboxUser     string
	SandboxReadonly *bool // nil = not set

	// GithubRepoDirectory is the path to the local clone of the project repo.
	GithubRepoDirectory string

	// GithubRepoUrl is the HTTPS URL of the project's GitHub repository.
	GithubRepoUrl string

	// InteractionMode controls how tool-call progress is surfaced.
	// "engaging" (default) = emoji-rich narration, progress message edited.
	// "enhance" = per-tool narrated messages appended, progress header kept.
	// "verbose" = raw tool names, args, and results.
	// "off" = no intermediate progress output, clean answer only.
	InteractionMode string
}

CLIFlags holds values parsed from the CLI. Zero/nil values mean the flag was not explicitly passed — the config loader will look at lower priority layers for these fields.

CLIFlags holds CLI-only configuration. These fields participate in the same merge chain: global file → project file → ODEK_* env → CLI. Fields typed as *bool distinguish "explicitly set to false" from "not set", which matters when the config file says "sandbox_readonly: false" (user explicitly wants writable) vs the field being absent (inherit from lower layer or default).

type FileConfig

type FileConfig struct {
	Model   string `json:"model,omitempty"`
	BaseURL string `json:"base_url,omitempty"`
	APIKey  string `json:"api_key,omitempty"`

	Thinking string `json:"thinking,omitempty"`
	MaxIter  int    `json:"max_iterations,omitempty"`

	Sandbox  *bool `json:"sandbox,omitempty"`
	NoColor  *bool `json:"no_color,omitempty"`
	NoAgents *bool `json:"no_agents,omitempty"`

	// PromptCaching enables prompt caching markers for supported providers.
	PromptCaching *bool `json:"prompt_caching,omitempty"`

	System string `json:"system,omitempty"`

	// Sandbox-specific fields.
	SandboxImage    string            `json:"sandbox_image,omitempty"`
	SandboxNetwork  string            `json:"sandbox_network,omitempty"`
	SandboxReadonly *bool             `json:"sandbox_readonly,omitempty"`
	SandboxMemory   string            `json:"sandbox_memory,omitempty"`
	SandboxCPUs     string            `json:"sandbox_cpus,omitempty"`
	SandboxUser     string            `json:"sandbox_user,omitempty"`
	SandboxEnv      map[string]string `json:"sandbox_env,omitempty"`
	SandboxVolumes  []string          `json:"sandbox_volumes,omitempty"`

	// Dangerous operation approval settings.
	Dangerous *danger.DangerousConfig `json:"dangerous,omitempty"`

	// Skills section (see internal/skills package).
	Skills *SkillsConfig `json:"skills,omitempty"`

	// Memory section controls the persistent memory system.
	Memory *memory.MemoryConfig `json:"memory,omitempty"`

	// MCPServers maps server names to MCP server configurations.
	// Each server is an external MCP server (e.g., Playwright, database,
	// web scraping) whose tools are exposed to the agent.
	// Format matches Claude Code's mcpServers config:
	//
	//	"mcp_servers": {
	//	  "playwright": {
	//	    "command": "npx",
	//	    "args": ["@playwright/mcp"]
	//\t  }
	//\t}
	MCPServers map[string]mcpclient.ServerConfig `json:"mcp_servers,omitempty"`

	// MaxConcurrency limits how many sub-agent tasks run in parallel.
	// Config: max_concurrency, ODEK_MAX_CONCURRENCY.
	// Default: 3.
	MaxConcurrency int `json:"max_concurrency,omitempty"`

	// MaxToolParallel limits how many tool calls run concurrently per
	// agent iteration. Config: max_tool_parallel.
	// Default: 0 (loop uses default of 4).
	MaxToolParallel int `json:"max_tool_parallel,omitempty"`

	// Telegram configures the Telegram bot integration.
	Telegram *telegram.TelegramConfig `json:"telegram,omitempty"`

	// Transcription configures local audio transcription (whisper.cpp).
	Transcription *TranscriptionConfig `json:"transcription,omitempty"`

	// GithubRepoDirectory is the path to the local clone of the project
	// repository. Injected into the system prompt so the agent knows
	// where source code lives and can self-correct.
	// Config: github_repo_directory, ODEK_GITHUB_REPO_DIRECTORY.
	GithubRepoDirectory string `json:"github_repo_directory,omitempty"`

	// GithubRepoUrl is the HTTPS URL of the project's GitHub repository.
	// Injected into the system prompt so the agent can reference the
	// upstream repo for PRs, issues, and documentation links.
	// Config: github_repo_url, ODEK_GITHUB_REPO_URL.
	GithubRepoUrl string `json:"github_repo_url,omitempty"`

	// InteractionMode controls how the agent communicates tool/progress updates.
	// "engaging" (default) = emoji-rich narration, progress message edited.
	// "enhance" = per-tool narrated messages, progress header kept.
	// "verbose" = raw tool names, args, and results.
	// "off" = no progress output, clean answer only.
	InteractionMode string `json:"interaction_mode,omitempty"`

	// ToolProgress controls per-tool progress messages for the Telegram bot.
	//   "all"     (default) — show every tool call
	//   "new"     — only when the tool name changes (dedup consecutive same-tool)
	//   "verbose" — full tool arguments in progress messages
	//   "off"     — no per-tool progress messages (just thinking + final answer)
	ToolProgress string `json:"tool_progress,omitempty"`

	// ToolProgressCleanup controls whether progress messages are deleted after
	// the final answer. Default: true (delete progress messages).
	ToolProgressCleanup *bool `json:"tool_progress_cleanup,omitempty"`
}

FileConfig is the JSON schema used by ~/.odek/config.json and ./odek.json. Pointer booleans distinguish "explicitly set to false" from "not set".

type ResolvedConfig

type ResolvedConfig struct {
	Model         string
	BaseURL       string
	APIKey        string
	Thinking      string
	MaxIter       int
	Sandbox       bool
	NoColor       bool
	NoAgents      bool
	PromptCaching bool
	System        string

	// SandboxImage is the Docker image for the sandbox container.
	// Default: "alpine:latest" (applied at call site, not here —
	// set to "alpine:latest" only if Dockerfile.odek doesn't exist).
	// Config: sandbox_image, ODEK_SANDBOX_IMAGE, --sandbox-image.
	SandboxImage string

	// SandboxNetwork is the Docker network mode.
	// Default: "bridge" (internet access by default).
	// Config: sandbox_network, ODEK_SANDBOX_NETWORK, --sandbox-network.
	SandboxNetwork string

	// SandboxReadonly, when true, mounts the working directory read-only
	// in the container. The agent can read /workspace but cannot write to it.
	// Config: sandbox_readonly, ODEK_SANDBOX_READONLY, --sandbox-readonly.
	SandboxReadonly bool

	// SandboxMemory is the container memory limit (e.g. "512m", "2g").
	// Empty string means no limit.
	// Config: sandbox_memory, ODEK_SANDBOX_MEMORY, --sandbox-memory.
	SandboxMemory string

	// SandboxCPUs is the container CPU limit (e.g. "0.5", "2", "4").
	// Empty string means no limit.
	// Config: sandbox_cpus, ODEK_SANDBOX_CPUS, --sandbox-cpus.
	SandboxCPUs string

	// SandboxUser sets the container user (e.g. "1000:1000" or "node").
	// Empty string means root (default Docker behavior).
	// Config: sandbox_user, ODEK_SANDBOX_USER, --sandbox-user.
	SandboxUser string

	// SandboxEnv holds extra environment variables injected into the
	// container. File-only — no env var or CLI mapping.
	// Config: sandbox_env.
	SandboxEnv map[string]string

	// SandboxVolumes holds extra volume mounts in "host:container" format.
	// File-only — no env var or CLI mapping.
	// Config: sandbox_volumes.
	SandboxVolumes []string

	// Dangerous is the resolved dangerous operations config.
	// Uses danger.DangerousConfig defaults for any unset fields.
	Dangerous danger.DangerousConfig

	// Skills is the resolved skills config with default values.
	Skills skills.SkillsConfig

	// Memory is the resolved memory config with default values.
	Memory memory.MemoryConfig

	// MCPServers maps server names to external MCP server configurations.
	// Populated from the mcp_servers section of odek.json.
	MCPServers map[string]mcpclient.ServerConfig

	// MaxConcurrency limits how many sub-agent tasks run in parallel.
	// Config: max_concurrency, ODEK_MAX_CONCURRENCY.
	// Default: 3.
	MaxConcurrency int

	// MaxToolParallel limits how many tool calls run concurrently per
	// agent iteration. Config: max_tool_parallel.
	// Default: 0 (loop uses default of 4).
	MaxToolParallel int

	// Telegram is the resolved Telegram bot configuration.
	Telegram telegram.TelegramConfig

	// Transcription is the resolved transcription config.
	// Default: auto_transcribe=true, model="tiny", language="", no binary_path.
	Transcription TranscriptionConfig

	// GithubRepoDirectory is the path to the local clone of the project
	// repository. Injected into the system prompt.
	GithubRepoDirectory string

	// GithubRepoUrl is the HTTPS URL of the project's GitHub repository.
	GithubRepoUrl string

	// InteractionMode is the resolved interaction style.
	// Values: "engaging" (default), "enhance", "verbose", or "off".
	// "engaging" (default), "enhance", or "verbose".
	InteractionMode string

	// ToolProgress is the resolved tool progress mode for Telegram.
	// Default: "all".
	ToolProgress string

	// ToolProgressCleanup controls whether progress messages are deleted
	// after the final answer. Default: true.
	ToolProgressCleanup bool
}

ResolvedConfig is the fully merged result. Every field has a concrete value — callers can read directly without checking for "not set".

func LoadConfig

func LoadConfig(cli CLIFlags) ResolvedConfig

LoadConfig merges configuration from all four layers and returns the fully resolved result.

Priority (lowest → highest):

global file → project file → ODEK_* env → CLI flags

For each field, the highest-priority layer that provides a value wins. API key has an additional fallback: if none of the four layers provides one, it falls back to DEEPSEEK_API_KEY → OPENAI_API_KEY (legacy env vars).

type SkillsConfig

type SkillsConfig struct {
	MaxAutoLoad  *int                   `json:"max_auto_load,omitempty"`
	MaxLazySlots *int                   `json:"max_lazy_slots,omitempty"`
	Learn        *bool                  `json:"learn,omitempty"`
	Dirs         []string               `json:"dirs,omitempty"`
	Import       *skills.ImportConfig   `json:"import,omitempty"`
	Curation     *skills.CurationConfig `json:"curation,omitempty"`
	AutoSave     *skills.AutoSaveConfig `json:"auto_save,omitempty"`
	LLMLearn     *bool                  `json:"llm_learn,omitempty"`
	LLMCurate    *bool                  `json:"llm_curate,omitempty"`
	Verbose      *bool                  `json:"verbose,omitempty"`
}

SkillsConfig holds the skills configuration section from JSON files.

type TranscriptionConfig

type TranscriptionConfig struct {
	Model          string `json:"model,omitempty"`
	Language       string `json:"language,omitempty"`
	AutoTranscribe bool   `json:"auto_transcribe,omitempty"`
	ModelsDir      string `json:"models_dir,omitempty"`
	BinaryPath     string `json:"binary_path,omitempty"`
}

TranscriptionConfig controls the transcribe tool (local whisper.cpp). Populated from the "transcription" section of odek.json.