Skip to content

Configuration

letscode resolves settings from four sources in this precedence order:

CLI flag  >  env var  >  project config  >  user config  >  built-in default

Config files

~/.letscode/config.toml

model = "gpt-4o-mini"
base_url = "https://api.openai.com/v1"
frontend = "basic"
tools = "read,write,edit,bash"
verbose = false
timeout = 600.0
no_context_files = false
footer = true

.letscode/config.toml in your project root (or any ancestor of cwd).

Project values override user values key-by-key. Use this to pin a specific model or disable footers per-project without touching your global config.

API keys are not loaded from TOML

OPENAI_API_KEY and other secrets are read from the environment only — never from a config file. Don't put keys in config.toml.

Environment variables

Variable Purpose
OPENAI_API_KEY Required. The provider's API key.
OPENAI_BASE_URL The provider's endpoint. Defaults to OpenAI.
LETSCODE_MODEL Equivalent to --model.
LETSCODE_SESSIONS_DIR Override ~/.letscode/sessions/ (testing seam).
LETSCODE_E2E Enable the e2e test suite (developer-only).

CLI flags

letscode --help
Flag Effect
-m, --model NAME Model name.
--base-url URL OpenAI-compatible endpoint.
--api-key KEY API key (prefer env).
--system TEXT Override the default system prompt.
--tools LIST Comma-separated whitelist (e.g. read,bash).
--no-tools Disable all tools.
--frontend NAME Pick a registered frontend (default basic).
-c, --continue Continue the most recent session in cwd.
--no-session Don't persist this run.
--no-context-files Skip AGENTS.md / CLAUDE.md discovery.
-p, --print Print mode: prompt → final text → exit.
--timeout FLOAT LLM request timeout in seconds (default 600).
--debug Verbose logging (openai SDK wire, httpx, plugin discovery).

Resolution example

You have a user config setting model = "gpt-4o-mini", a project config overriding to model = "claude-sonnet-4-5", and you run:

LETSCODE_MODEL="gpt-4o" letscode --model "minimax-m2p5" "prompt"

The effective model is minimax-m2p5 — CLI wins over env, which wins over project, which wins over user.

Context files

letscode walks up from cwd looking for these files and prepends their contents to the system prompt:

  • AGENTS.md (the cross-tool standard)
  • CLAUDE.md (Claude Code convention)

Plus the user-global ~/.letscode/AGENTS.md if it exists.

Disabling context files

Pass --no-context-files to skip the walk. Useful for short one-off prompts where the surrounding repo's context is noise.

Sections (since v0.4)

Flat core keys remain valid and permanent. Since v0.4 the loader also passes through any [table] it doesn't model, so plugins read their own namespace without the core knowing about them — e.g. letscode-memory:

model = "..."            # flat core keys, unchanged

[memory]                 # plugin-owned, passed through verbatim
relevance = false
relevance_top_n = 5

Run letscode --init to write a commented starter config at ~/.letscode/config.toml (it never overwrites an existing file). A malformed config degrades to defaults with a one-line warning rather than crashing.