Animus

Local-first agentic coding tool powered by local LLMs.

---

What is Animus

Animus is a local-first agentic coding assistant that runs entirely on your machine. It uses local GGUF models via llama-cpp-python — no API keys, no data leaving your machine. Inspired by claw-code but designed from the ground up for local models, Animus adapts its behavior to the capability of the model you load: a 7-tier system scales planner complexity, grammar enforcement, tool availability, and turn budget to match what the model can reliably handle. Small models get tight GBNF grammar constraints and a decomposing planner; large models get full tool access and free-form generation. The result is a tool that works well across the full spectrum of local hardware.

---

Quick Start

Install

# Clone the repository
git clone https://github.com/crussella0129/Animus.git
cd Animus

# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

# Install Animus and its dependencies
pip install -e ".[dev]"

# Install llama-cpp-python (choose one):
pip install llama-cpp-python                          # CPU only
pip install llama-cpp-python --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cu124  # CUDA 12.4

Download a Model

Animus works with any GGUF model. A few recommended starting points:

# ~4GB, good for most machines (Small tier)
huggingface-cli download Qwen/Qwen2.5-Coder-7B-Instruct-GGUF \
    qwen2.5-coder-7b-instruct-q4_k_m.gguf --local-dir ~/models

# ~8GB, better quality (Medium tier)
huggingface-cli download Qwen/Qwen2.5-Coder-14B-Instruct-GGUF \
    qwen2.5-coder-14b-instruct-q4_k_m.gguf --local-dir ~/models

Run One-Shot (Single Prompt)

animus "Explain the structure of this project" --model ~/models/qwen2.5-coder-7b-instruct-q4_k_m.gguf

Run the REPL

animus --model ~/models/qwen2.5-coder-7b-instruct-q4_k_m.gguf

Once in the REPL, type your prompt and press Enter. Use /help to see all commands.

---

CLI Reference

animus [PROMPT] [OPTIONS]

Arguments:
  PROMPT    One-shot prompt. Omit to enter the interactive REPL.

Options:
  -m, --model TEXT         Path to a GGUF model file, or model name.
  -p, --permission TEXT    Permission mode: read-only, standard, full, prompt.
                           Default: standard.
  -w, --workspace TEXT     Workspace root directory. Default: current directory.
  -c, --config TEXT        Path to an additional config YAML file (local tier).
  --help                   Show this message and exit.

---

Model Tiers

Animus detects the tier automatically from the model's parameter count embedded in its metadata. Tier controls planner behavior, grammar enforcement, max turns, and which tools are available.

| Tier | Params | Planner | Grammar Mode | Max Turns | Tools Available | Example Models | |--------|-----------|------------------|---------------|-----------|-----------------|---------------------------------------------| | Nano | < 4B | Yes (2 steps) | full | 6 | 4 | Qwen2.5-Coder-1.5B, Phi-3-mini | | Small | 4 – 13B | Yes (3 steps) | first_turn | 15 | 6 | Qwen2.5-Coder-7B, Mistral-7B | | Medium | 13 – 30B | No | off | 20 | 8 | Qwen2.5-Coder-14B, DeepSeek-Coder-V2-Lite | | Large | 30 – 70B | No | off | 15 | 10 | Qwen2.5-Coder-32B, CodeLlama-34B | | XL | 70 – 200B | No | off | 25 | 10 | Qwen2.5-Coder-72B, Llama-3.1-70B | | Ultra | > 200B | No | off | 30 | 11 | Llama-3.1-405B, DeepSeek-V3 |

Planner — For Nano and Small tiers, tasks are decomposed into sub-steps before execution. Each step has its own scoped tool list and turn budget.

Grammar Mode — GBNF grammar constraints are applied to force structured JSON output from the model. full = every turn; first_turn = only the first generation; off = free-form.

---

Tools

All tools are confined to the workspace boundary. Attempting to access paths outside the workspace is blocked at the security layer.

| Tool | Permission | Min Tier | Description | |--------------|------------|----------|----------------------------------------------------------------------------| | read_file | READ | Nano | Read a file with optional line offset and limit. Returns numbered lines. | | write_file | WRITE | Nano | Write (overwrite) a file. Creates parent directories as needed. | | edit_file | WRITE | Small | Replace an exact string in a file. Fails on ambiguous matches. | | list_dir | READ | Nano | List directory contents with type indicators (trailing / for dirs). | | glob_search | READ | Nano | Find files matching a glob pattern. Returns up to 100 results. | | grep_search | READ | Small | Search file contents with a regex. Returns up to 50 file:line: matches. | | bash | EXECUTE | Medium | Run a shell command in the workspace. Injection patterns are blocked. | | git | WRITE | Medium | Run git subcommands (status, diff, add, commit, etc.). Network ops blocked. |

---

Slash Commands

Slash commands are intercepted in the REPL before input reaches the model.

| Command | Description | |--------------------------|--------------------------------------------------------------------------| | /help | List all available slash commands. | | /status | Show session stats: message count, token estimate, tier, context, mode. | | /compact | Manually compact session history to free context window space. | | /clear | Clear session history and start a fresh conversation. | | /cost | Show token usage for the current session (input, output, total). | | /model [name] | Show current model info, or request a model switch. | | /permissions [mode] | Show or change the permission mode (read-only, standard, full, prompt). | | /session | Show the current session ID and creation timestamp. | | /diff | Run git diff in the workspace root and display the result. | | /config [key] [value] | Show or set a config value (e.g. /config model.context_length 32768). | | /plan | Show whether the planner is active for the current model tier. | | /tier | Show the detected model tier and parameter count. |

---

Permission Modes

| Mode | Allows | Use When | |------------|-----------------------------------------|-------------------------------------------------------| | read-only | READ tools only | You only want the model to read and analyze code. | | standard | READ + WRITE tools | Normal coding sessions. Default mode. | | full | READ + WRITE + EXECUTE (bash, git) | You trust the model to run shell commands. | | prompt | READ always; prompts before WRITE/EXEC | Reserved for future interactive approval workflow. |

Set the mode at launch:

animus --model ~/models/model.gguf --permission full

Or change it mid-session:

> /permissions read-only
Permission mode set to: read-only

---

Configuration

Animus uses a three-tier YAML config system. Each tier overrides the previous via deep merge:

| Tier | Location | Purpose | |---------|------------------------------|----------------------------------------------| | User | ~/.animus/config.yaml | Your personal defaults across all projects. | | Project | .animus/config.yaml | Project-specific settings. Commit this. | | Local | .animus/config.local.yaml | Machine-local overrides. Git-ignored. |

Example Config

# ~/.animus/config.yaml

model:
  provider: native            # Only "native" (llama-cpp-python) is supported today.
  model_path: ""              # Absolute path to your .gguf file.
  temperature: 0.7            # Sampling temperature (0.0 – 2.0).
  max_tokens: 2048            # Maximum tokens per generation.
  context_length: 4096        # Model context window size (tokens).
  gpu_layers: -1              # GPU layers to offload. -1 = all, 0 = CPU only.
  size_tier: auto             # Override tier detection: auto/nano/small/medium/large/xl/ultra.

agent:
  permission_mode: standard   # read-only | standard | full | prompt
  max_turns: 20               # Hard cap on agentic loop iterations per turn.
  system_prompt: "You are Animus, a local AI coding assistant with tool use."

session:
  auto_save: true             # Save session to .animus/sessions/ on exit.
  auto_compact: true          # Automatically compact when nearing context limit.
  compact_threshold: 0.7      # Compact when session fills this fraction of context.
  preserve_recent: 4          # Messages kept verbatim after compa