anima-cli

Deterministic psychodynamic profiles for LLM agents. Give an agent a behavioral structure — not a paragraph of adjectives you have to maintain by hand — run it forward, and prove the result is reproducible byte-for-byte.

Built on @af199/anima-core (7-dimensional state engine, seeded RNG) and @af199/anima-trace (SHA-256 integrity hashing for run trajectories).

Install

npm install -g anima-cli

Requires Node.js 16+.

Quickstart

anima init                              # wizard: name, archetype, turns, signal preset
anima run <name>                        # step the engine forward, record + hash the trajectory
anima verify <name>                     # re-run and confirm the hash matches, byte for byte
anima export <name> --format prompt     # emit a system-prompt fragment

Commands

anima init

Interactive wizard. Prompts for:

| Field | Description | |---|---| | Agent name | Identifier used by every other command | | Archetype | One of: histeria, obsesion, fobia, melancolia, paranoia, esquizofrenia, perversion | | Turns per run | How many steps anima run will execute (default 10) | | Signal preset | calm, clinical-crisis, or chaotic — fixed signal vectors, no free text |

The seed is derived automatically from the agent name + creation date, so it's stable across re-runs without you having to track it manually. Profiles are saved to ./anima-profiles/<name>.json in the current directory.

Signal presets are fixed on purpose — there is no free-text signal input. This keeps every profile comparable and closes off prompt-injection style abuse of the signal channel.

anima run <name>

anima run <name> [--turns N] [--preset calm|clinical-crisis|chaotic]

Runs the engine for the profile's configured turns (or the override flags), records the full state trajectory, and writes it to ./anima-runs/<name>-<seed>.json along with a SHA-256 integrity hash.

anima verify <name>

Re-runs the stored signals against the engine and checks that the resulting trajectory hash matches the one on file — byte for byte. This is the whole trust model in one command: anyone with the run file can confirm it wasn't tampered with and that the archetype+seed+signals genuinely produce that trajectory.

$ anima verify test1
PASS — trajectory is byte-reproducible

anima export <name>

anima export <name> [--format prompt|json] [--out file]

• --format prompt (default): a system-prompt fragment with one behavioral directive per dimension, derived from the final state. Paste it into Claude, GPT, Grok, or any other model's system prompt.
• --format json: the raw final state vector plus integrity hash, for your own pipeline.
• --out file: write to a file instead of stdout.

The 7 dimensions

Every archetype is a point in a 7-dimensional state space, stepped forward by @af199/anima-core's update equations on each turn:

| Symbol | Meaning | |---|---| | E | Expressive energy | | T | Defensive tension | | A | Anxiety | | C | Symbolic closure | | G | Jouissance / excess | | P | Pressure | | ρ (rho) | Fantasy rigidity |

Known behavior: dimension saturation under high-intensity presets

Under sustained clinical-crisis or chaotic signal presets over several turns, some dimensions (commonly A anxiety and rho fantasy rigidity) can drive to their floor (0) or ceiling (1) rather than settling mid-range. This is the archetype's update equations behaving as designed, not a bug — anima verify will confirm the trajectory is reproducible either way. anima export flags saturated dimensions explicitly in its output. If you want more gradual, mid-range trajectories, use the calm preset or fewer turns.

Known behavior: seed only matters once irruption is reachable

The engine's random component is consumed only when internal pressure (P) crosses the archetype's irruption threshold (θ_irr). If it never crosses — for example under the calm preset, or with few turns — the trajectory up to that point is fully deterministic from the signals alone, and different seeds will produce identical output. This is correct, documented behavior in @af199/anima-core, not a bug: it means the same signals always produce the same trajectory regardless of seed, and only diverge once the stochastic irruption check actually fires.

If you're testing whether the seed "does anything," use a preset that reaches the threshold (clinical-crisis or chaotic, with enough turns) — under calm, seed independence is expected.

Troubleshooting

profile not found: <name> — you ran run/verify/export from a different directory than the one you ran init in. Profiles and runs are scoped to ./anima-profiles and ./anima-runs in the current working directory; cd back to where you initialized, or re-run anima init here.

no run found for <name> — you called verify or export before anima run <name>. Run it first.

anima: command not found after install — your global npm bin directory isn't on PATH. Run npm config get prefix and add <prefix>/bin (or <prefix> on Windows) to your PATH, then restart the terminal.

License

MIT