Skip to content

Migration guide: v0.3.0 → v0.13.x

anthrogo's config has accreted features across 80+ releases. This guide helps you upgrade settings.yaml and understand behaviour changes milestone by milestone. Read only the sections that apply to your current version.


v0.3 → v0.4 (Hooks + Compact + Skills + Plugins)

Hooks stanza (M4.1)

A new top-level hooks: key lets you run shell commands at lifecycle events.

Before (v0.3): no hooks support.

After (v0.4):

hooks:
  # Run before every user message is sent to the model.
  preMessage: []

  # Run after every assistant message is received.
  postMessage:
    - command: ./my-hook.sh
      args: []
      env: {}

  # Run once when the session starts.
  sessionStart: []

  # Run once when the session ends (/exit or Ctrl-C).
  sessionEnd: []

Each hook entry supports command, args, and env fields.

Pricing stanza (M7.4 — backfill note)

The pricing: stanza was added later (M7.4) but depends on provider: which was introduced in M4.x. If you see /cost returning $0, add:

pricing:
  inputPerMToken: 3.00    # USD per million input tokens
  outputPerMToken: 15.00  # USD per million output tokens

Or rely on built-in defaults which cover all Claude models by name.

/compact is no longer a placeholder

In v0.3 /compact printed "not implemented". From v0.4 it summarises the conversation using the current model and replaces the history with the summary. No config change required; behaviour is now active.

Skills directory (M4.3)

# New optional key. Omit to disable skills.
skillsDir: ~/.anthrogo/skills   # or a relative path

Each subdirectory containing a SKILL.md becomes a skill available via trigger phrases or the Task tool.

Plugins directory (M4.4)

# New optional key. Omit to disable plugins.
pluginsDir: ~/.anthrogo/plugins

v0.4 → v0.5 (Subagents + MCP debt)

subagent_type on the Task tool

The Task tool now accepts a subagent_type field:

Value Behaviour
local (default) Run subagent in the same process
remote:<name> Dispatch to a KAIROS worker named <name>

No config change required for local subagents. For remote subagents see v0.5 → v0.6.

/mcp reload

/mcp reload now re-registers tools with the model without restarting anthrogo. Previously only a full restart would pick up MCP config changes.

MCP server env vars

MCP server entries can now forward environment variables to the server process:

mcpServers:
  my-server:
    command: my-mcp-server
    args: []
    env:
      MY_SECRET: env:MY_SECRET_ENV_VAR   # "env:" prefix reads from shell

v0.5 → v0.6 (KAIROS + WebSocket + OAuth)

KAIROS configuration

Two new top-level stanzas for KAIROS distributed subagents:

Worker side:

kairos:
  role: worker
  listen: ":9001"
  maxConcurrent: 4
  authToken: env:KAIROS_AUTH_TOKEN

Client side:

kairos:
  role: client
  remote:
    - name: my-worker
      address: "worker-host:9001"
      authToken: env:KAIROS_AUTH_TOKEN
      maxHops: 1

WebSocket MCP servers

mcpServers.<name>.type: websocket is now supported alongside the default stdio type:

mcpServers:
  remote-tools:
    type: websocket
    url: wss://my-mcp-server.example.com/mcp
    headers:
      Authorization: "Bearer env:MCP_TOKEN"

OAuth for MCP (M6.3)

MCP servers that require OAuth 2.0 can use:

mcpServers:
  oauth-server:
    type: websocket
    url: wss://example.com/mcp
    auth:
      type: oauth2
      clientId: env:OAUTH_CLIENT_ID
      clientSecret: env:OAUTH_CLIENT_SECRET
      tokenUrl: https://example.com/oauth/token

v0.6 → v0.7 (multi-provider + /compact auto + /cost)

profiles map and provider selection (M7.1)

The config now supports multiple provider profiles. provider: selects which profile to use by name.

Before (v0.6): single apiKey: at top level, implicit Anthropic.

After (v0.7):

# Active provider — must match a key in profiles: (or "anthropic" built-in).
provider: anthropic

# Built-in shorthand still works — no profiles: block needed for Anthropic:
apiKey: env:ANTHROPIC_API_KEY

# Multi-provider example:
provider: openai-gpt4
profiles:
  openai-gpt4:
    type: openai
    model: gpt-4o
    apiKey: env:OPENAI_API_KEY
    baseUrl: https://api.openai.com/v1
  anthropic-haiku:
    type: anthropic
    model: claude-haiku-4-5
    apiKey: env:ANTHROPIC_API_KEY

--provider CLI flag

anthrogo --provider openai-gpt4

Overrides the provider: key in settings.yaml for this session only.

/compact auto-trigger (M7.2)

Auto-compact fires when context usage exceeds a threshold. Configurable:

compact:
  autoThreshold: 0.85      # Trigger at 85% context usage (0.0 to 1.0).
  autoEnabled: true        # Set false to disable auto-compact.
  summaryMaxTokens: 2048   # Max tokens for the compaction summary.

/cost command (M7.4)

/cost is now available. It uses the pricing: stanza or built-in per-model defaults. Override if you're using a custom endpoint with different pricing:

pricing:
  inputPerMToken: 3.00
  outputPerMToken: 15.00

v0.7 → v0.8 (system overlay + theme + UX)

System overlay file (M8.1)

Create ~/.anthrogo/system_overlay.md (or a project-local system_overlay.md in ANTHROGO_HOME) to inject persistent instructions into every session's system prompt:

# My overlay

Always respond in British English.
Never use bullet points — use numbered lists instead.

No config key needed — anthrogo reads the file automatically.

You can also set the path explicitly:

systemOverlay: ./my-overlay.md

Theme stanza (M8.2)

theme:
  # "default", "dark", "light", or "solarized"
  colorScheme: dark

  # Highlight colour for the prompt and tool output.
  accentColor: "#7c3aed"   # purple

  # Width of the main content column (characters).
  contentWidth: 100

Input history persistence (M8.3)

history:
  file: ~/.anthrogo/history     # Path to the readline history file.
  maxEntries: 1000

v0.8 → v0.9 (Bedrock + Vertex + KAIROS multi-hop)

AWS Bedrock provider (M9.1)

profiles:
  bedrock-sonnet:
    type: bedrock
    model: anthropic.claude-sonnet-4-6-20260101-v1:0
    region: us-west-2
    # Credentials: uses the standard AWS credential chain
    # (env vars, ~/.aws/credentials, instance role, etc.)
    # Optional explicit override:
    # accessKeyId: env:AWS_ACCESS_KEY_ID
    # secretAccessKey: env:AWS_SECRET_ACCESS_KEY

Google Vertex AI provider (M9.2)

profiles:
  vertex-sonnet:
    type: vertex
    model: claude-sonnet-4-6@20260101
    project: my-gcp-project-id
    location: us-east5
    # Credentials: uses Application Default Credentials (gcloud auth).
    # Optional service account key file:
    # credentialsFile: env:GOOGLE_APPLICATION_CREDENTIALS

KAIROS multi-hop (M9.3)

Workers can now forward tasks to other workers. Increase maxHops on the client to allow chained dispatch:

kairos:
  role: client
  remote:
    - name: tier-1-worker
      address: "worker1:9001"
      authToken: env:KAIROS_AUTH_TOKEN
      maxHops: 2   # worker1 may itself dispatch one more hop

Session search cache (M10.1)

# Number of past session summaries to keep in the in-process search index.
# Increase for better /search recall at the cost of memory.
sessionSearchCacheSize: 200

Bash tool sandbox (M10.2)

The Bash tool can now run commands in an isolated environment:

tools:
  bash:
    # Enable a sandboxed shell (uses Docker or macOS Sandbox).
    sandbox: true

    # Allowed paths inside the sandbox (bind-mounted read-write).
    allowedPaths:
      - /tmp
      - ./workspace

    # Commands blocked even inside the sandbox.
    blockedCommands:
      - curl
      - wget

Web search backends (M10.3)

webSearch.backend now accepts multiple values tried in order:

webSearch:
  # Try Brave first, fall back to DuckDuckGo if quota exceeded.
  backend:
    - brave
    - duckduckgo
  braveApiKey: env:BRAVE_API_KEY
  maxResults: 5

v0.10 → v0.11 (multi-pane TUI + plugin marketplace + speech I/O)

TUI layout cycling (M11.1)

Press F2 at runtime to cycle through TUI layouts: default → wide → split → minimal → default

Set the initial layout in config:

theme:
  layout: split    # "default", "wide", "split", "minimal"

Plugin install from URL (M11.2)

/plugin install https://github.com/owner/my-anthrogo-plugin
/plugin install https://example.com/plugins/my-plugin.tar.gz

No config change required — plugins are installed to pluginsDir.

Speech I/O (M11.3)

speech:
  # Input: transcribe spoken audio to text.
  input:
    enabled: false
    provider: whisper       # "whisper" or "system"
    language: en

  # Output: read assistant messages aloud.
  output:
    enabled: false
    provider: system        # "system" (OS TTS) or "elevenlabs"
    voice: default
    # elevenlabsApiKey: env:ELEVENLABS_API_KEY

v0.11 → v0.12 (doctor + init-config + HTTPRequest + SQLQuery + Ollama)

anthrogo doctor (M12.1)

New subcommand that checks your installation and config:

anthrogo doctor

No config change. Outputs a checklist of warnings and errors.

anthrogo init-config wizard (M12.2)

anthrogo init-config              # Interactive wizard, does not overwrite
anthrogo init-config --force      # Backs up existing config, starts fresh

The wizard creates a new settings.yaml in ANTHROGO_HOME.

HTTPRequest tool (M12.3)

tools:
  httpRequest:
    enabled: true
    # Domains the model is allowed to call. Omit for unrestricted.
    allowedDomains:
      - api.github.com
      - httpbin.org
    # Max response body size in bytes (default 1 MB).
    maxResponseBytes: 1048576

SQLQuery tool (M12.4)

tools:
  sqlQuery:
    enabled: true
    # Named database connections the model may query.
    connections:
      analytics:
        driver: postgres
        dsn: env:ANALYTICS_DB_DSN
      local:
        driver: sqlite3
        dsn: ./local.db
    # Block write statements (INSERT/UPDATE/DELETE/DROP/…).
    readOnly: true

Ollama local provider (M12.5)

profiles:
  ollama-llama3:
    type: ollama
    model: llama3
    # baseUrl defaults to http://localhost:11434
    baseUrl: http://localhost:11434

Ollama pricing defaults to $0/M (local inference). See docs/providers/ollama.md for the full model list.


v0.12 → v0.13 (docs restructure)

README slimmed (M13.1)

The README.md was reduced from ~1 000 lines to ~280 lines. All feature documentation moved to dedicated docs/*.md pages. If you had links to README sections, update them to the corresponding docs/ page.

Full reference: https://Ricardo-M-L.github.io/anthrogo/

No YAML changes

v0.13 introduces no breaking config changes. Existing settings.yaml files from v0.12 work without modification.


YAML upgrade strategy

If you have an old settings.yaml and want to get to v0.13:

  1. Run anthrogo doctor to get a checklist of missing or deprecated keys.
  2. Apply one section of this guide at a time, testing after each change.
  3. Reload with /mcp reload (for MCP changes) or restart for everything else.

Option B — fresh start

# Back up your current config.
cp "$ANTHROGO_HOME/settings.yaml" "$ANTHROGO_HOME/settings.yaml.bak"

# Run the wizard to generate a fresh config.
anthrogo init-config --force

The wizard asks which features you want and writes a complete, annotated settings.yaml. You can then merge your customisations from the backup.

Key compatibility notes

Feature Min version Notes
hooks: v0.4 New in M4.1
skillsDir: v0.4 New in M4.3
pluginsDir: v0.4 New in M4.4
profiles: / provider: v0.7 New in M7.1
compact.autoThreshold: v0.7 New in M7.2
pricing: v0.7 New in M7.4
systemOverlay: v0.8 New in M8.1
theme: v0.8 New in M8.2
kairos: v0.6 (basic) / v0.9 (multi-hop) —
Profile.Type: "bedrock" v0.9 New in M9.1
Profile.Type: "vertex" v0.9 New in M9.2
sessionSearchCacheSize: v0.10 New in M10.1
tools.bash.sandbox: v0.10 New in M10.2
webSearch.backend: (multi) v0.10 New in M10.3
speech: v0.11 New in M11.3
tools.httpRequest: v0.12 New in M12.3
tools.sqlQuery: v0.12 New in M12.4
Profile.Type: "ollama" v0.12 New in M12.5