Migrating from v0.4 to v0.5

Migrating from v0.4 to v0.5

Executive summary

Chimera v0.5 ships the full mink / otter / ferret / weasel / shrew / stoat / badger coding-agent family on a single substrate, plus three new top-level commands (chimera doctor, chimera config, chimera resume, chimera agents). For users staying on chimera mink there are no breaking API changes — every flag and slash command from v0.4 still works. The release does, however, surface two DeprecationWarnings you should fix now to be ready for v0.7.0: the chimera cc subcommand alias and AgentPreset.build(). v0.5 also flips one important default: chimera code now boots into the assembled CodingAgent stack instead of the legacy ReAct loop. Pass --legacy-react to opt out.

What’s new

• Six new CLIs alongside chimera mink: otter, ferret, weasel, shrew, stoat, badger. Each is a posture on the same Agent / AgentLoop / EventSourcedSession substrate — not a fork.
• Purpose aliases so you don’t have to memorise codenames: tui → mink, multi → otter, sandbox → ferret, mini → weasel, tiny → shrew, shell → stoat, strict → badger.
• Top-level dispatchers: chimera resume <id> auto-detects which CLI minted the session; chimera agents lists every CLI + alias + inspiration; chimera doctor checks API keys, daemons and extras; chimera config manages persistent CLI defaults in ~/.chimera/config.toml (stdlib-only, no extras required).
• Event sourcing (chimera/events/sourcing/): append-only log with file locking, crash recovery, and SQLite-backed snapshot fast-resume. Existing Session consumers keep working unchanged; EventSourcedSession is opt-in.
• TLS + cooperative cancellation + SSE resume on chimera otter serve.
• SSH / remote execution via the new [ssh] extra: chimera mink --remote ssh://user@host:port/path, AsyncSSHEnvironment, SFTP transfer, ProxyJump bastion-host support.
• SWE-bench Verified scaffolding with IPythonTool and LLM condensation hooks; 11 benchmark adapters under chimera/eval/benchmarks/.

Breaking changes

None for chimera mink users. The v0.4-era surface is preserved bit-for-bit.

Two surfaces now emit DeprecationWarning and will be removed in v0.7.0. Fix them today:

1. chimera cc — this CLI subcommand was renamed to chimera mink in wave 1. The cc alias still dispatches to mink and prints a deprecation note to stderr. (Source: chimera/cli/main.py registers cc as a deprecated parser; the dispatcher prints [deprecated] the legacy 'cc' subcommand has been renamed to 'mink'.)
2. AgentPreset.build() — calling AgentPreset.SWE_AGENT.build(provider) (or any sibling) raises DeprecationWarning. Migrate to CodingAgent.from_preset(...). (Source: chimera/agents/presets/agent_styles.py:86-95 — warnings.warn(... DeprecationWarning, stacklevel=2). See the agent-presets module reference for the full rewrite recipe.)

Additionally, the claude_code preset key is a deprecated alias for coding_agent and emits a DeprecationWarning when passed to CodingAgent. (Source: chimera/assembly/presets.py:DEPRECATED_PRESET_ALIASES, chimera/assembly/coding_agent.py:_warn_if_deprecated_preset.)

Behavior changes

chimera code REPL default flipped

Bare chimera code (no --preset, no --legacy-react) now boots the CodingAgent stack with the coding_agent preset. The legacy ReAct + Session REPL — with the rich slash-command palette (/checkpoint, /tree, /branch, /switch, mid-turn steering) — is reachable via --legacy-react.

The dispatch logic (in chimera/cli/code.py):

1. --preset NAME → CodingAgent(preset=NAME)
2. --legacy-react → legacy ReAct + Session REPL
3. existing per-CLI shim that sets legacy_react=True on its namespace → legacy stack
4. otherwise → CodingAgent(preset="coding_agent")

Purpose aliases

Every codename CLI has a registered alias. chimera tui is exactly chimera mink; chimera sandbox is exactly chimera ferret. Neither path emits a deprecation warning — both are supported indefinitely. The alias makes muscle memory possible without forcing users to memorise codenames.

chimera tui          # = chimera mink
chimera multi serve  # = chimera otter serve
chimera sandbox -p "audit the repo"  # = chimera ferret -p "audit the repo"
chimera mini         # = chimera weasel
chimera tiny         # = chimera shrew
chimera shell        # = chimera stoat
chimera strict       # = chimera badger

chimera cc prints a deprecation line

Existing scripts still work. The first line on stderr is now:

[deprecated] the legacy 'cc' subcommand has been renamed to 'mink'. Please update your scripts to use 'chimera mink'.

CI pipelines that pipe stderr should either grep this out or migrate to chimera mink.

Recommended upgrade path

1. Upgrade the package. pip install --upgrade chimera-run (or uv pip install --upgrade chimera-run). The PyPI distribution name is chimera-run; the Python import is still import chimera.
2. Run chimera doctor. This is new in wave 11. It validates API keys, optional daemons (Ollama, llama.cpp), and extras ([ssh], [anthropic], [openai]). Fix anything red before continuing.
3. Replace chimera cc invocations with chimera mink. A simple grep -r "chimera cc" . over your scripts is enough. Same flags, same slash commands.
4. Audit AgentPreset.build() call sites. grep -r "AgentPreset" . in your project. Replace per the recipe in the agent-presets module reference.
5. Decide on the chimera code default. If you depend on the rich slash-command REPL (/checkpoint, /tree, /branch, /switch, mid-turn steering), pin --legacy-react in your invocation. Otherwise let the new CodingAgent default ride and adopt /help, /cost, /context, /clear from the assembled stack.
6. Optionally adopt the new top-level dispatchers. chimera resume <id> is strictly more useful than per-CLI --resume; chimera agents is the friendliest way to remember which codename does what.
7. Optionally migrate to EventSourcedSession. Existing Session consumers keep working. Switch when you want crash-recovery + snapshot fast-resume.

Code-level migrations

AgentPreset.build() → CodingAgent.from_preset(...)

The legacy primitive returns a bare Agent with no permission checking, hooks, transcripts, content replacement, compaction, or snapshot manager. The canonical replacement is the assembled CodingAgent from chimera.assembly:

# Before (v0.4) — emits DeprecationWarning in v0.5
from chimera.agents.presets.agent_styles import AgentPreset
from chimera.providers.factory import create_provider

provider = create_provider(model="glm-5")
agent = AgentPreset.SWE_AGENT.build(provider)

# After (v0.5+)
from chimera.assembly.coding_agent import CodingAgent

agent = CodingAgent.from_preset("swebench", model="glm-5")
# or, if you've already built a provider:
agent = CodingAgent.from_preset("swebench", provider=provider)

CodingAgent.from_preset(name, **kwargs) accepts the same keyword arguments as the constructor — model=, provider=, project_dir=, permission_callback=, tools_override=. Source: chimera/assembly/coding_agent.py:241-243.

Preset name map

The preset names changed because the assembly layer thinks about configuration profiles, not upstream-agent recreations:

Legacy AgentPreset	Canonical CodingAgent.from_preset(...)
AgentPreset.SWE_AGENT.build	CodingAgent.from_preset("swebench")
AgentPreset.CODEX.build	CodingAgent.from_preset("codex")
AgentPreset.AIDER.build	CodingAgent.from_preset("coding_agent")
AgentPreset.CLINE.build	CodingAgent.from_preset("coding_agent")

The four assembly presets that ship in v0.5 (source: chimera/assembly/presets.py:PRESETS):

• coding_agent — full canonical agent: permissions on, hooks on, transcripts on, content replacement on, compaction on, streaming on, max_turns=100. The default for bare chimera code.
• codex — code generation profile: permissions on, hooks off, transcripts on, max_turns=50.
• minimal — minimal tools, permissions/hooks/transcripts off, max_turns=20.
• explore — read-only exploration agent, max_turns=30.
• kimi — action-first profile (KISS, iterate on failures), permissions on, hooks off, max_turns=50.
• swebench — benchmark-tuned: permissions/hooks/transcripts/content-replacement/compaction/streaming all off, max_turns=30. Replaces the legacy SWE_AGENT lean profile.

The legacy aider and cline presets used loop variants (lint_feedback, plan_act) that the assembly layer doesn’t expose yet. Map them to coding_agent and re-run with the canonical ReAct loop, or pin to v0.6.x if you depend on those exact loops. (See the agent-presets module reference for the full discussion.)

File-based agent definitions

The AgentLoader / AgentRegistry / AgentFactory triad in chimera/agents/loader.py is the modern path for file-based agent definitions. It loads .md files with YAML frontmatter from three sources, with priority resolution:

from chimera.agents.loader import AgentLoader, AgentFactory
from chimera.providers.factory import create_provider
from chimera.tools.read import ReadTool
from chimera.tools.bash import BashTool

# Discover agent .md files from built-in / ~/.chimera/agents / .chimera/agents/
loader = AgentLoader(project_root="/path/to/project")
agent_def = loader.get("code-reviewer")

# Build an Agent from the file definition
provider = create_provider(model="glm-5")
factory = AgentFactory(
    provider=provider,
    tool_registry={"read_file": ReadTool(), "bash": BashTool()},
)
agent = factory.create(agent_def)

AgentLoader priority: built-in (lowest) → ~/.chimera/agents/ (user) → .chimera/agents/ (project, highest). Source: chimera/agents/loader.py:181-197.

Suppressing the warning during migration

If you genuinely need to keep the legacy AgentPreset.build() call for one more release:

import warnings

with warnings.catch_warnings():
    warnings.simplefilter("ignore", DeprecationWarning)
    agent = AgentPreset.SWE_AGENT.build(provider)

This pattern keeps test output quiet while you work through the migration. After v0.7.0 the import itself will be removed.

chimera code invocation

# Before (v0.4 — legacy ReAct + Session was the only stack)
chimera code

# After (v0.5+ — bare invocation now boots CodingAgent)
chimera code                       # CodingAgent(preset="coding_agent")
chimera code --preset codex        # CodingAgent(preset="codex")
chimera code --preset swebench     # benchmark-tuned profile
chimera code --legacy-react        # opt out: legacy ReAct + Session REPL

The claude_code preset key still works but emits a DeprecationWarning. Use coding_agent instead.

New top-level commands

chimera doctor

Wave-11 addition. Validates API keys, optional daemons, and extras. Run once after upgrading to confirm the install.

chimera doctor                 # human-readable text output
chimera doctor --format json   # machine-readable

chimera config

Persistent CLI defaults in ~/.chimera/config.toml. Stdlib-only — no extras required. Five verbs: get, set, unset, list, edit. Keys are dot-namespaced by CLI codename.

chimera config set otter.model glm-5
chimera config set mink.max_steps 75
chimera config get otter.model       # -> glm-5
chimera config list --cli otter      # all otter.* keys
chimera config unset mink.max_steps
chimera config edit                  # open config.toml in $EDITOR

chimera resume

Top-level dispatcher that auto-detects which CLI minted a session, based on the run-id prefix. Omit the id to resume the newest run across all CLIs.

chimera resume                       # newest run, any CLI
chimera resume mink-20260430-a1b2    # explicit id, dispatched to mink
chimera resume otter-20260430-c3d4   # dispatched to otter

Each CLI still exposes its own --resume <id> flag (wave-9 C1); the top-level command simply removes the “which CLI?” guesswork.

chimera agents

Lists all seven coding-agent CLIs with aliases and inspirations. Use this when you can’t remember which codename does what.

chimera agents

This is distinct from each CLI’s own agents subcommand (which lists agent presets within that CLI).

FAQ

Q: Does my v0.4 chimera mink config still work? Yes. No flags or slash commands were renamed or removed. The mink surface is preserved bit-for-bit.

Q: What if I have a chimera cc ... invocation in CI? It still works. You’ll see one extra line on stderr: [deprecated] the legacy 'cc' subcommand has been renamed to 'mink'. Either grep it out or migrate the invocation. The alias is removed in v0.7.0.

Q: What if I don’t want the new CodingAgent REPL default? Pass --legacy-react to chimera code. The legacy ReAct + Session REPL with /checkpoint, /tree, /branch, /switch, and mid-turn steering is preserved.

Q: Are the codename CLIs separate packages? No. They all live under the single chimera-run PyPI distribution. The Python import is still import chimera. Each CLI is a thin posture on the shared substrate (Agent, AgentLoop, EventSourcedSession, the 26-event EventBus, the unified tool registry).

Q: Is EventSourcedSession required? No. Existing Session consumers keep working unchanged. Switch when you want crash-recovery + snapshot fast-resume.

Deprecation timeline

Symbol	Status in v0.5	Removed in
chimera cc subcommand alias	DeprecationWarning (stderr line)	v0.7.0
AgentPreset.build()	DeprecationWarning (Python warning)	v0.7.0
chimera.agents.presets.agent_styles module	DeprecationWarning via AgentPreset.build()	v0.7.0
claude_code preset key	DeprecationWarning (use coding_agent)	v0.7.0

See also

• Chimera 0.5.0 release notes — the full ship list, live-verification matrix, and quality bar.
• AgentPreset → CodingAgent migration recipe — focused recipe for the AgentPreset.build() rewrite.
• Per-CLI quickstarts: mink · otter · ferret · weasel · shrew.