config.example.toml

# fastpick config
#
# Written to your config directory on first run and yours to edit. Keys belong in a file of
# their own, named here by `auth_token_file`, never pasted into this one. The `env` tables
# further down are the one place where a key would fit, and they are the one place not to
# put it: their values are printed in full by `--dry-run`, which is the output people paste
# into bug reports.
#
#   fastpick --edit           open this file
#   fastpick --paths          every path fastpick uses, and the state of each key file
#   fastpick --set-key <id>   write a key, read from stdin, owner-only. <id> is a provider,
#                             or <provider>.<key> when it holds several
#   fastpick --list           what this file declares, and what is installed
#
# Paths take ~, $VAR and %VAR%, so the same file works on Windows, macOS and Linux. Only
# the harnesses whose `bin` is installed are offered by the menu.
#
# Two kinds of block, and the menu asks for them in this order.
#
#   [[harness]]   a coding agent binary. `kind` picks the built-in adapter that knows how
#                 to hand it an endpoint, a model and extra instructions.
#   [[provider]]  an endpoint. It lists the harnesses it can serve under
#                 [provider.harness.<harness id>], and only shows up for those. Its
#                 optional `group` is a heading in the menu: entries sharing one are drawn
#                 as a block, which is how two keys on the same site stop looking like two
#                 unrelated choices. Keep them next to each other here, the menu follows
#                 this file's order.
#
# Models are not listed here. Each provider is asked what it serves through
# [provider.catalog], the answer is cached, and [[provider.model]] below only layers on
# what no API reports: a nicer name, a context window, effort levels, or an id that works
# but is not advertised.
#
# A site that issues one key per upstream group needs several credentials behind one menu
# entry, so a provider may declare [[provider.key]] blocks instead. Each key then owns its
# own `auth_token_file`, catalogue, bindings, models, proxy and host check, and the provider
# keeps only `id`, `name`, `group` and a shared `env`. See the last example at the bottom.
# The two shapes cannot be mixed: a provider declaring keys is refused if it also leaves a
# route field on itself, naming the field to move.

# Where the .md files offered as system prompts live. Every file in here is offered for every
# model; a model picks its own with `prompt` below. Left commented on purpose: unset, it
# is `system-prompts` next to this file, which is the folder the first run just created,
# and that path is right on every platform. Writing `~/.config/fastpick/system-prompts`
# here would be wrong on Windows, where this file lives under %APPDATA%.
# system_prompts_dir = "~/my-prompts"

# How long a fetched catalogue stays fresh. `tab` in the menu refetches on demand.
catalog_ttl_secs = 21600


# ============================================================================ harnesses

[[harness]]
id = "claude-code"
name = "Claude Code"
kind = "claude-code"
bin = "claude"
# Takes an endpoint through environment variables, a model through --model, an effort
# level through --effort, and appends instructions with --append-system-prompt-file.

[[harness]]
id = "opencode"
name = "OpenCode"
kind = "opencode"
bin = "opencode"
# Takes everything as one inline JSON config in OPENCODE_CONFIG_CONTENT, which is merged
# over your own opencode.json rather than replacing it, so your MCP servers, plugins and
# agents are untouched. Extra instructions go in its `instructions` array, which appends.

[[harness]]
id = "codex"
name = "Codex"
kind = "codex"
bin = "codex"
# Takes dotted TOML overrides with -c, so ~/.codex/config.toml is never written to.
# No system prompt row: Codex has no append-only surface for one, and its instructions
# override would replace the base prompt, tool rules included.

[[harness]]
id = "pi"
name = "Pi"
kind = "pi"
bin = "pi"
# Has no lever for an endpoint at launch: its built-in providers carry their own base url
# and its models.json lives inside its config directory, which fastpick never writes to. So
# a provider with a base_url is generated as an extension under fastpick's own config
# directory and loaded with --extension. That needs the endpoint's dialect, which is `api`
# on the binding. Extra instructions go through --append-system-prompt, which reads a file
# when the value is a path and appends rather than replacing.

# Every harness also takes these two, left out above because most setups need neither:
#
#   extra_args = ["--verbose"]   appended to every launch of this harness, whatever the
#                                provider. A per-provider equivalent lives on the binding.
#
# `bin` may be a bare name resolved through PATH, or a path. On Windows the npm shim is
# found and run correctly either way, including the .cmd one that CreateProcess refuses.


# ============================================================================= providers

# --------------------------------------------------------------------------- native
# The agent's own endpoint and login. Declaring a binding with no base_url is what says
# "change nothing", and it is not the same as leaving the binding out, which would hide
# this provider from that harness entirely.
[[provider]]
id = "builtin"
name = "Built in (the agent's own login)"
group = "native"

  [provider.harness.claude-code]
  [provider.harness.codex]

  # No [provider.catalog]: there is no key here to authenticate a listing with, so the
  # models below are the whole list.
  [[provider.model]]
  id = "claude-opus-5[1m]"
  label = "Opus 5"
  effort = ["low", "medium", "high", "xhigh", "max"]
  effort_default = "high"
  # No context_window, here or on any claude-* model: Claude Code ignores
  # CLAUDE_CODE_MAX_CONTEXT_TOKENS for those names and reads its own table, so the id is
  # the only lever on the window and declaring the variable would be a lie.

  [[provider.model]]
  id = "claude-sonnet-5"
  label = "Sonnet 5"
  effort = ["low", "medium", "high", "xhigh"]
  effort_default = "high"


# --------------------------------------------------------------------------- direct
# A reseller that speaks the Anthropic wire format on /v1/messages and the OpenAI one on
# /v1/chat/completions. Reachable from all three agents, each through its own dialect.
[[provider]]
id = "example"
name = "Example provider"
group = "example.invalid"
auth_token_file = "~/.example/client.key"
# Claude Code draws its background model (agent inspection, resumes, titles, subagents
# with no `model:`) from ANTHROPIC_SMALL_FAST_MODEL and defaults it to claude-sonnet-5.
# Any endpoint that does not serve that name rejects those calls, and a resume then dies
# with "Content block not found". OpenCode reads the same setting from `small_model`.
small_fast_model = "example-small"

  [provider.catalog]
  url = "https://example.invalid/v1/models"
  auth = "bearer"                      # bearer | x-api-key | none
  only_prefixes = []                   # keep only ids starting with one of these
  exclude_contains = ["embed", "image"] # drop what an agent cannot drive

  [provider.harness.claude-code]
  base_url = "https://example.invalid"

  [provider.harness.opencode]
  base_url = "https://example.invalid/v1"
  # Which AI SDK package speaks this endpoint: @ai-sdk/anthropic, @ai-sdk/openai-compatible
  # for /v1/chat/completions, or @ai-sdk/openai for /v1/responses.
  npm = "@ai-sdk/openai-compatible"

  # Codex only speaks the OpenAI Responses API: it refuses a provider config saying
  # `wire_api = "chat"` outright, so an endpoint that offers only /v1/chat/completions
  # cannot be bound here at all. Leave the binding out rather than writing one that fails
  # at launch.
  [provider.harness.codex]
  base_url = "https://example.invalid/v1"
  wire_api = "responses"

  [provider.harness.pi]
  base_url = "https://example.invalid"
  # Which of pi's streaming implementations speaks this endpoint: anthropic-messages,
  # openai-completions, openai-responses or google-generative-ai.
  api = "anthropic-messages"

  # Layered on the fetched catalogue. Everything is optional.
  [[provider.model]]
  id = "example-large"
  label = "Example Large"
  context_window = 1000000
  compact_ratio = 0.9
  # small_fast_model = "example-tiny"   overrides the provider's, for this model only
  # The system prompt this model launches with, named as the file sits in the prompts folder
  # and with the `.md` optional. Nothing is guessed from the id: any model can take any file,
  # several models can name the same one, and a file nobody names is still one keypress away
  # in the options panel. Unset, the model launches with no system prompt.
  # prompt = "house-style"

  # Anything the adapters do not cover, per provider or per binding. Values are passed to
  # the agent as written.
  #
  #   [provider.env]                          on every harness this provider serves
  #   MY_VARIABLE = "value"
  #
  #   [provider.harness.opencode.env]         on this harness only, and wins over the above
  #   MY_VARIABLE = "other value"
  #
  #   [provider.harness.opencode]
  #   extra_args = ["--print-logs"]           appended for this pair only
  #
  # Not a place for a key. `--dry-run` prints these verbatim.


# --------------------------------------------------------------------------- proxied
# For an endpoint that refuses the dialect your agent speaks: a local translator listens,
# and fastpick starts it if the port is free. Nothing runs when this provider is not used.
#
# Same `group` as the entry above because it is the same site, reached the long way round.
[[provider]]
id = "example-proxied"
name = "Example through a local proxy"
group = "example.invalid"
auth_token_file = "~/.some-proxy/client.key"

  [provider.proxy]
  port = 4000
  # Add the platform's extension if it has one, this is spawned as written.
  exe = "~/.some-proxy/proxy"
  args = ["-config", "~/.some-proxy/config.yaml"]
  workdir = "~/.some-proxy"
  timeout_secs = 15
  logs_hint = "~/.some-proxy/logs/"

  # Loopback, so http is fine here and the key never reaches a network. Any other host
  # with an `auth` other than "none" has to be https, and is refused otherwise.
  [provider.catalog]
  url = "http://127.0.0.1:4000/v1/models"

  [provider.harness.claude-code]
  base_url = "http://127.0.0.1:4000"

  # A declared model matters more here than anywhere else: the proxy only starts at launch,
  # so the catalogue above cannot answer while the menu is open and the model list would
  # otherwise be empty with no way forward.
  [[provider.model]]
  id = "example-large"
  label = "Example Large (proxied)"


# ----------------------------------------------------------------------------- local
# A model served by a host that is not always reachable. `on_down` decides what an
# unreachable host means: "warn" prints the message and launches anyway, "abort" refuses.
# Pick "warn" only when something between you and the host can bring it back on its own.
[[provider]]
id = "example-local"
name = "Local model"
group = "local"
auth_token_file = "~/.example-local/client.key"
small_fast_model = "local-model"

  [provider.host_check]
  host = "127.0.0.1"
  on_down = "abort"
  message = "The host does not answer. Start it, then retry."

  [provider.harness.claude-code]
  base_url = "http://127.0.0.1:8080"

  [[provider.model]]
  id = "local-model"
  context_window = 262144
  # A self-hosted server may divide its configured window across concurrent slots. Declare
  # what one session actually gets, not the number in the server's command line.


# ------------------------------------------------------------------------- several keys
# One site, one menu entry, one credential per upstream group. Write it this way when a
# provider issues a key per group and the groups differ in what they serve or in which API
# surfaces they allow, which is what makes one shared block impossible.
#
# The keys are disjoint here, so the model picked is enough to know which credential, which
# endpoint, and whether a proxy has to come up first. The menu writes each key's `label`
# dim beside its models, and the filter matches that label too.
[[provider]]
id = "example-groups"
name = "Example with one key per group"

  # The site's own, shared by every key below. A key's `env` is layered on top and wins.
  [provider.env]
  SOME_VENDOR_TELEMETRY = "0"

  [[provider.key]]
  # Unique inside this provider and free of `.`, since `<provider>.<key>` is how
  # --set-key and --paths name it: `fastpick --set-key example-groups.first`.
  id = "first"
  label = "first"
  auth_token_file = "~/.example/first.key"
  small_fast_model = "first-mini"

    [provider.key.catalog]
    url = "https://example.invalid/v1/models"

    [provider.key.harness.claude-code]
    base_url = "https://example.invalid"

    [[provider.key.model]]
    id = "first-mini"

  [[provider.key]]
  id = "second"
  label = "second"
  auth_token_file = "~/.example/second.key"

    [provider.key.catalog]
    url = "https://example.invalid/v1/models"

    # Bound here and not on the key above, because only this group answers the surface
    # Codex needs. Picking Codex therefore narrows the menu to this key's models on its own.
    [provider.key.harness.codex]
    base_url = "https://example.invalid/v1"
    wire_api = "responses"

    [[provider.key.model]]
    id = "second-large"
    context_window = 400000