Animus

Appearance

Migration: v0.4.11 → v0.4.12 ​

Status (2026-05-24): v0.4.12 closes the v0.4 arc. The web stack, the in-tree subject backends, the five in-tree provider mirrors, and the llm-cli-wrapper crate are all deleted from this repo. The replacements live as standalone plugins under launchapp-dev and must be installed before the daemon will start.

If you are upgrading from v0.4.11 (or any earlier v0.4.x) this is the patch where the daemon stops shipping with bundled providers, subjects, and a web server. You will need to run one post-upgrade command (animus plugin install-defaults) before the daemon will boot. After that, day-to-day operation is unchanged.

TL;DR: stop the daemon → upgrade the binary → animus plugin install-defaults --include-subjects --include-transports → animus daemon preflight → animus daemon start --autonomous.

What changed ​

ChangeImpact
In-tree web stack deleted (~9K LOC)animus web serve now spawns installed transport_backend + web_ui plugins and errors out if none are present
In-tree subject backends deleted (~1000 LOC)Daemon will refuse to start without at least one subject_backend plugin installed; install animus-subject-default for kind=task and animus-subject-requirements for kind=requirement
In-tree provider mirrors deleted (5 providers)Daemon will refuse to start without at least one provider plugin installed
llm-cli-wrapper crate deleted (~5,882 LOC)Internal refactor; user-visible only if you path-depended on the crate
Daemon preflight on startupanimus daemon start runs a plugin-presence check before booting. Default posture: refuse to start, with the exact animus plugin install ... fix command in the error
Phase-level idempotency fieldCrash recovery for phases without an explicit idempotency: idempotent annotation now lands as Blocked with an actionable hint rather than silently re-running
ANIMUS_DAEMON_DISABLE_BUILTIN_TASK_ADAPTER + _REQUIREMENTS_ADAPTER env varsNow no-ops. Use ANIMUS_DAEMON_DISABLE_SUBJECT_PLUGINS=1 if you need to disable subject discovery entirely
animus web serve no longer boots an in-process axum serverRequires animus-transport-http, animus-transport-graphql, and animus-web-ui plugins installed

This is the largest single-release surface change since the v0.3 → v0.4 rename. It is intentional: every backend is now a plugin, and the daemon treats them uniformly.

Migration steps ​

1. Stop the running daemon ​

bash
animus daemon stop

Stop the daemon in every project where you have it running before upgrading the binary. The v0.4.11 daemon and the v0.4.12 daemon do not share state about plugin requirements; running a stale daemon against a new CLI will surface confusing errors.

2. Upgrade the animus binary ​

Pick whichever path matches how you installed v0.4.11:

bash
# Upstream installer (macOS)
curl -fsSL https://raw.githubusercontent.com/launchapp-dev/animus-cli/main/scripts/install.sh | bash

# Or pin to v0.4.12 explicitly
ANIMUS_VERSION=v0.4.12 curl -fsSL https://raw.githubusercontent.com/launchapp-dev/animus-cli/main/scripts/install.sh | bash

If you built from source:

bash
cd path/to/animus-cli
git fetch origin
git checkout v0.4.12
cargo install --path crates/orchestrator-cli --locked

No Homebrew formula or crates.io publish yet — cargo install animus from crates.io is not wired up. Track the animus-cli releases page for whichever distribution channel ends up canonical.

Verify:

bash
animus --version    # should print v0.4.12

3. Install the default plugin set ​

This is the one new step that v0.4.12 introduces. Without it, the daemon will refuse to start.

bash
animus plugin install-defaults --include-subjects --include-transports

What this installs:

GroupPluginsRequired for
Providers (always)animus-provider-{claude,codex,gemini,opencode,oai} v0.2.1Any daemon start — at least one provider must be installed
--include-subjectsanimus-subject-{default,requirements,linear,sqlite,markdown} v0.1.0animus subject --kind <kind> for task, requirement, and the three plug-in backends
--include-transportsanimus-transport-{http,graphql} + animus-web-uianimus web serve and animus web open

The command is idempotent: it skips plugins that are already installed. It uses the same install pipeline as animus plugin install, so cosign signature verification and integrity checks apply uniformly.

If you only use a subset of providers (e.g. Claude only) and want a leaner install, install them one at a time instead:

bash
animus plugin install launchapp-dev/animus-provider-claude
animus plugin install launchapp-dev/animus-subject-default
animus plugin install launchapp-dev/animus-subject-requirements

4. (Optional) Install the OAI Responses API agent provider ​

If you use the OpenAI Responses API agent loop (not the plain chat completions endpoint), pull in the agent-shaped provider as well:

bash
animus plugin install launchapp-dev/animus-provider-oai-agent@v0.1.1

Or include it in the bulk install:

bash
animus plugin install-defaults --include-oai-agent --include-subjects --include-transports

5. Verify with daemon preflight ​

bash
animus daemon preflight

This prints the installed-vs-required matrix and exits non-zero if any required role is unsatisfied. The error message includes the exact animus plugin install ... command to fix each gap. JSON envelope is animus.daemon.preflight.v1 if you want to script around it (animus daemon preflight --json).

Expected output when everything is satisfied:

Daemon preflight OK
  provider:      5 installed (claude, codex, gemini, opencode, oai)
  subject:       5 installed (default, requirements, linear, sqlite, markdown)
  transport+ui:  3 installed (transport-http, transport-graphql, web-ui)

6. Start the daemon ​

bash
animus daemon start --autonomous

animus daemon start runs the same preflight check before booting. If preflight already passed in step 5, no plugins will be downloaded here.

If you want the daemon to install missing plugins on its own (less deterministic, but useful for one-shot dev boxes):

bash
animus daemon start --autonomous --auto-install

Escape hatch for dev iteration when you're knowingly running without the required plugins:

bash
animus daemon start --autonomous --skip-preflight

--skip-preflight is not recommended for production — you will get runtime errors from the first request that needs a missing backend.

What auto-resume does for in-flight workflows ​

If you upgrade while a workflow is mid-execution (rare but real for long-running phases), v0.4.12 will try to resume it on the new daemon:

  • The daemon writes <phase>.session.json for every in-flight phase ({ provider, session_id, status }).
  • On restart, the scheduler attempts provider.resume_agent through the plugin that originally ran the phase.
  • If the provider plugin supports session resume (Claude, Codex, OpenCode), the phase picks up where it left off.
  • If the provider does not support session resume, or the plugin is not installed on the new daemon, the workflow is marked Blocked with an explicit reason. You can then inspect, re-run, or cancel it manually.

The default posture is "block and ask the operator" rather than "silently re-run and burn API credits". To force-resume a blocked workflow after you've decided it's safe:

bash
animus workflow resume <workflow-id> --force

Idempotency annotations on workflow YAML ​

v0.4.12 adds a new phase-level field:

yaml
phases:
  implementation:
    mode: agent
    agent: default
    directive: "Implement production code."
    idempotency: idempotent      # or: sideeffecting, unknown
ValueMeaningCrash-recovery behavior
idempotentSafe to retry; re-running produces the same observable effectAuto-retried on daemon restart
sideeffectingMutates external state (push, merge, deploy, webhook fire)Blocked on crash; operator must decide
unknown (default)Not yet classifiedBlocked on crash; operator must decide

Existing workflow YAML without an idempotency: field defaults to unknown and will be Blocked on the first crash-recovery cycle. This is deliberate: the v0.4.11 behavior was to silently re-run any phase on restart, which burned API credits and occasionally double-pushed branches.

Options:

  1. Annotate. Walk each phase in your custom workflows and mark idempotent (most agent phases, most read-only command phases) or sideeffecting (anything that pushes, merges, opens a PR, fires a webhook). One-time edit per workflow.
  2. Leave unannotated. Phases default to unknown → blocked on crash. Use animus workflow resume <id> --force when you decide it's safe.
  3. Mix. Annotate the safe phases, leave the risky ones as unknown. Recommended for production pipelines.

Bundled workflow templates (task-queue, conductor, direct-workflow) ship with sensible defaults already in place. No action needed if you only use the bundled templates.

Env var deprecations ​

Env varv0.4.11 behaviorv0.4.12 behavior
ANIMUS_DAEMON_DISABLE_BUILTIN_TASK_ADAPTERSkipped the in-tree task subject adapterNo-op. The in-tree adapter no longer exists. Install or remove animus-subject-default instead
ANIMUS_DAEMON_DISABLE_BUILTIN_REQUIREMENTS_ADAPTERSkipped the in-tree requirements subject adapterNo-op. Install or remove animus-subject-requirements instead
ANIMUS_DAEMON_DISABLE_SUBJECT_PLUGINS(did not exist)New. Set to 1 to skip subject discovery entirely (escape hatch for debugging plugin issues; daemon will refuse most subject operations)
ANIMUS_DAEMON_DISABLE_TRIGGERSSameUnchanged
ANIMUS_PROVIDER_DISABLE_PLUGINForced fallback to in-tree provider backendsRemoved (silently ignored). The in-tree provider backends are gone and the env var no longer affects dispatch in any way. Install missing provider plugins, remove a bad plugin with animus plugin uninstall --name <name>, or move its binary out of discovery

If you have any of the deprecated env vars set in your shell config, CI, systemd unit, or Docker compose file, remove them. They will not cause errors — they are silently ignored — but they will mislead the next operator who reads the file.

animus web behavior ​

v0.4.11: animus web serve booted an embedded axum HTTP server with the React UI compiled in.

v0.4.12: animus web serve discovers installed transport_backend and web_ui plugins, spawns them, and opens the browser. If the required plugins are not installed, you get:

error: web serve requires transport + UI plugins
  run: animus plugin install-defaults --include-transports

To install:

bash
animus plugin install-defaults --include-transports

This installs animus-transport-http, animus-transport-graphql, and animus-web-ui from their respective releases. After install:

bash
animus web serve
animus web open       # also opens the browser

The user-facing UX is unchanged once the plugins are installed.

Rollback procedure ​

If v0.4.12 surfaces a blocker you need to work around, you can roll back to v0.4.11. The plugin-extraction work is not reversible at the data layer in the sense that installed plugins keep working under v0.4.11 too — v0.4.11 simply prefers the in-tree backends when both are available.

bash
# Stop the v0.4.12 daemon
animus daemon stop

# Reinstall v0.4.11
ANIMUS_VERSION=v0.4.11 curl -fsSL https://raw.githubusercontent.com/launchapp-dev/animus-cli/main/scripts/install.sh | bash

# Verify
animus --version    # should print v0.4.11

# Start the v0.4.11 daemon — no preflight on this version
animus daemon start --autonomous

The installed plugins under ~/.animus/plugins/ remain in place and will be re-used when you upgrade back to v0.4.12. The v0.4.11 daemon ignores the new idempotency field on workflow YAML (forward-compatible).

If rollback is needed because of a workflow that the v0.4.12 daemon Blocked on crash recovery, the recommended path is:

  1. animus workflow resume <id> --force under v0.4.12 (the explicit override exists for exactly this).
  2. Only roll back if --force resume itself surfaces a bug.

Quick smoke test after migration ​

bash
animus --version                                         # v0.4.12
animus plugin list                                       # at least 1 provider + 2 subjects + (optional) transports
animus daemon preflight                                  # all required roles satisfied
animus daemon start --autonomous
animus daemon health                                     # responds Healthy
animus subject list --kind task                          # routes through animus-subject-default plugin
animus web serve                                         # spawns transport + ui plugins, opens browser

If any step fails, animus doctor runs a broader environment check and prints actionable remediation.

Where to ask for help ​

Released under the Elastic License 2.0 (ELv2).

Copyright 2024-present LaunchApp / Sami Shukri