| name | animus-chat |
| description | Hold and manage multi-turn Animus chat conversations — interactive provider sessions, conversation history, resume semantics, transcript search and export, and per-conversation cost. |
| user_invocable | false |
| auto_invoke | true |
| animus_version | 0.7.0-rc.18 |
Animus Chat
Use animus chat (v0.5.10+) for multi-turn conversations with a provider tool
(claude / codex / gemini / opencode / any installed provider_backend
plugin). It is the conversational sibling of animus agent run: same
SessionBackendResolver, same provider plugins, but with a durable,
queryable conversation store and turn-by-turn continuity.
Command Surface
animus chat new [--id <id>] [--title <title>]
animus chat send "your message" [flags]
animus chat get <id>
animus chat list
animus chat rename <id> --title <title>
animus chat delete <id>
animus chat export <id> [--format markdown|json] [--output <path>]
animus chat search <query> [--limit 20] [--case-sensitive]
Sending Turns
animus chat send "Explain the queue dispatch loop" --stream
animus chat send "Now compare it to the scheduler" --conversation conv-abc123 --stream
animus chat send "Summarize open tasks" --tool codex --model gpt-5.5
animus chat send "Audit auth flows" --agent auditor --reasoning-effort high
Key flags on chat send:
- positional
MESSAGE — the user message for this turn.
--conversation <ID> — target conversation; omit to create a fresh one
(its id is reported on the terminal frame).--tool <TOOL> (default claude) and --model <MODEL> — provider and
model selection, same values as animus agent run.--title <TITLE> — names a fresh conversation or renames the target;
empty string clears the title.--cwd <PATH> — provider working directory; defaults to the project root
and must stay inside it.--reasoning-effort low|medium|high — provider thinking budget
(codex model_reasoning_effort, claude --effort).--permission-mode <MODE> — mapped by each provider plugin onto its
driver (claude default|acceptEdits|bypassPermissions|plan natively;
codex untrusted|on-failure|on-request|never via MCP; gemini
default|auto_edit|yolo via ACP — transports since v0.6.9); overrides any
agent-profile value. Unknown values warn but pass through.--approvals — kernel-mediated approvals via the
animus.agent.request_approval MCP tool; implied when the --agent
profile declares an approval_policy.--agent / --skill / --mcp-server / --no-animus-mcp — see below.
Output modes: --json (global flag) emits one JSON event per line
(turn_started, text_delta, thinking, tool_call, tool_result,
metadata, warning, turn_completed) — turn_started carries
resumed: true|false, turn_completed carries the captured session_id.
--stream without --json prints plain text deltas; neither prints the
final assistant turn once complete.
Continuity: resume XOR replay
Providers own continuity. With a live session_id from a prior turn on the
same tool, Animus sends only the new message and the provider plugin resumes
its native session (how it does so is driver-internal — claude natively,
codex over MCP, gemini/opencode over ACP since v0.6.9). With no live session
(new conversation, missing/stale session id, or a mid-conversation tool
change), Animus replays its stored transcript into the prompt — never both,
so context is never double-counted. A stale-session error triggers exactly
one full-history replay retry.
MCP servers, agent profiles, and skills
animus chat send "Check ticket backlog" --agent support --mcp-server linear
animus chat send "Draft release notes" --skill release-notes --no-animus-mcp
--agent <AGENT_ID> — the chat agent receives that profile's declared
mcp_servers, resolved by name against the project's mcp_servers map.--skill <SKILL> — adds the skill's declared MCP servers (unioned with
the profile's). Unknown skill names are an error.--mcp-server <NAME> — wire an extra server by name (repeatable;
animus selects the built-in stdio surface).--no-animus-mcp — drop the built-in animus server. Without any
profile/skill servers, the baseline set is just animus, so the model
can call animus.* tools mid-conversation.
The resolved set rides the provider contract to any provider plugin
declaring supports_mcp (manifest field; undeclared defaults true).
OAuth/secret-bearing servers are rewritten to animus-mcp-proxy stdio
entries — tokens never reach CLI configs or argv.
Full skill application (v0.5.14)
--skill applies the skill's FULL definition per send invocation, not just
MCP servers + tool policy: prompt prefix/directives/suffix wrap the
outgoing message, prompt.system rides the session system_prompt,
extra_args/codex_config_overrides graft onto the runtime contract's
cli.launch block, skill env rides the request env, and the skill's
model/timeout_secs apply when not explicitly set. Precedence per field:
explicit flags > skill > defaults.
A launch-affecting skill (extra_args/codex_config_overrides/env)
forces full-history replay instead of native session resume, so launch
flags reach every turn's provider process. Practical implication: slower
turns and more tokens (history re-sent each turn), but launch behavior
stays correct on every turn.
Inspecting, searching, exporting
Conversations live under ~/.animus/<repo-scope>/chat/<conversation-id>/:
meta.json (continuity pointer: session_id + tool + model) and
messages.jsonl (append-only message log with ordered assistant blocks[]
timelines). Treat as tool-managed — use the animus chat surface, not
hand-edits.
animus chat list
animus chat search "merge conflict" --limit 10
animus chat export conv-abc123 --format json --output transcript.json
Search is case-insensitive by default (--case-sensitive to invert);
export defaults to Markdown, with --format json emitting the full
{ meta, messages } shape (same as chat get); both list and search
skip stray non-conversation directories (v0.5.13).
Cost
animus cost conversation conv-abc123
Per-turn usage/cost_usd from the provider's metadata frames fold into a
per-conversation total. See animus-cost-operations for the wider animus cost surface (summary, workflow, top, trends, decisions).
Reliability notes (v0.5.13)
- Chat sends are cross-process locked per conversation — concurrent sends
to the same conversation cannot interleave turns.
- A chat stream ending without a terminal event is an error, not a
silently-successful empty turn.
- OAuth
invalid_grant on an authed MCP server evicts the cached refresh
chain and retries the env seed in the same call — chat agents using
OAuth-protected servers self-recover.
Human-in-the-loop
The blocking animus.agent.ask / animus.agent.request_approval MCP tools
work on ad-hoc chat: in block mode (the default), the tool call parks until
a human answers via animus agent interactions answer, and on timeout a
question returns a best-judgment error while an approval denies fail-closed.
See animus-agent-interactions for the inbox workflow.
Related
- animus-agent-operations — single-shot
animus agent run, control/status, memory, messages.
- animus-agent-interactions — answering pending questions and approvals.
- animus-cost-operations — spend rollups beyond per-conversation totals.
