Configuration

hycode is provider-agnostic. It supports any OpenAI-compatible APIs (OpenAI, Anthropic, Ollama, OpenRouter), etc. Connect to custom providers, corporate proxies, or self-hosted models without modifying hycode's source code.

Config file location

Your config file lives at:

~/.config/hycode/config.yaml

You can override settings with environment variables or CLI flags. Priority order: CLI flags > env vars > config file.

Quick start

Config file

provider:
  type: openai
  base_url: https://your-proxy.example.com/v1
  api_key: your-api-key
  model_id: your-model-name

Environment variables

export HYCODE_PROVIDER=openai
export HYCODE_BASE_URL=https://your-proxy.example.com/v1
export HYCODE_API_KEY=your-api-key
export HYCODE_MODEL=your-model-name
hycode

CLI flags

hycode -p openai --base-url https://your-proxy.example.com/v1 --api-key your-key -m your-model

Provider configuration reference

All fields go under provider: in config.yaml.

Built-in provider presets

Config includes

The includes field merges additional config files that use the same YAML schema. Non-empty fields from included files override the main config. This is the recommended approach for extensions — write a separate file and include it, so extensions can add provider settings without touching the user's existing config.

includes:
  - corp_proxy.yaml    # Adds corporate proxy settings
  - team_palette.yaml  # Team branding

Distributing a custom provider

The recommended pattern for distributing a custom provider is a setup.sh that:

1. Writes a separate config file (e.g. my_proxy.yaml) to ~/.config/hycode/
2. Adds it to the includes: list in the main config.yaml

#!/usr/bin/env bash
set -euo pipefail

CONFIG_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/hycode"
CONFIG_FILE="$CONFIG_DIR/config.yaml"
EXTENSION_FILE="$CONFIG_DIR/my_proxy.yaml"

API_KEY="$(your-credential-tool get-token)"

mkdir -p "$CONFIG_DIR"

# Write the extension config
cat > "$EXTENSION_FILE" <<EOF
provider:
  type: openai
  base_url: https://your-proxy.example.com/v1
  api_key: $API_KEY
  model_id: your-model-name
  display_name: your-provider
EOF

# Add to includes (if not already there)
if [[ ! -f "$CONFIG_FILE" ]]; then
  echo 'includes: ["my_proxy.yaml"]' > "$CONFIG_FILE"
elif ! grep -q "my_proxy.yaml" "$CONFIG_FILE" 2>/dev/null; then
  { echo 'includes: ["my_proxy.yaml"]'; cat "$CONFIG_FILE"; } > "$CONFIG_FILE.tmp"
  mv "$CONFIG_FILE.tmp" "$CONFIG_FILE"
fi

echo "hycode configured for your-provider"

Palettes

Palettes let you customize hycode's TUI colors, accent hues, and status verbs. Here's the default palette shipped with the binary:

palette:
  # Optional: load a named preset (see "Presets" below)
  # preset: default

  colors:
    primary:   "#B0B0B0"   # Main brand color (neutral warm grey)
    secondary: "#909090"   # Secondary accent (darker grey)
    accent1:   "#707070"   # Tertiary accent (optional)
    accent2:   "#585858"   # Quaternary accent (optional)

  # Progressive + past-tense verbs shown during/after agent turns
  action_verb: Cooking
  done_verb:   Cooked

  # Inline markdown code color. Empty = glamour default.
  # Valid values: "", primary, secondary, accent1, accent2
  markdown_code: ""

  # Syntax highlighting theme for code blocks
  syntax_theme: monokai

Supported fields

Only primary, secondary, accent1, and accent2 exist — there is no background, border, or muted. The background is whatever your terminal theme provides.

Syntax themes

Custom presets

Named presets are loaded from (in priority order):

1. $HYCODE_PALETTES_FILE (env var)
2. ~/.config/hycode/palettes.json (user global)
3. ./.hycode/palettes.json (workspace)
4. Built-in default fallback

Register a team/brand palette in your own palettes.json:

{
  "my-team": {
    "colors": {
      "primary":   "#FF6B35",
      "secondary": "#F7C948",
      "accent1":   "#2EC4B6",
      "accent2":   "#011627"
    },
    "action_verb": "Forging",
    "done_verb":   "Forged"
  }
}

Then reference it from config.yaml:

palette:
  preset: my-team

Per-user fields in config.yaml override the preset — e.g. you can load a preset and change only syntax_theme.

Extensibility

Beyond providers and palettes, hycode supports additional extension mechanisms (docs coming as the APIs stabilize):

• Skills — reusable workflows and recipes for common tasks.
• MCP servers — Model Context Protocol integrations for structured context sharing.

HyCode can explore its own features and do a walk-through by invoking the /hycode-guide internal skill.