how andromity works

Andromity operates as a stateful agent loop. Understanding this architecture helps you get the most out of the system and customize its behavior.

When you ask Andromity to perform a task, it follows a structured sequence:

graph TD
  Prompt[User Instruction] --> Explore[Read & Explore Code]
  Explore --> Plan[Create Plan]
  Plan --> Review[User Approval]
  Review -->|Approve| Build[Execute Edits]
  Review -->|Reject| Explore
  Build --> Test[Run Tests]
  Test -->|Pass| ReviewCode[Final Code Review]
  Test -->|Fail| Fix[Auto-debug & Fix]
  Fix --> Test

Andromity performs a fast, semantic search across your codebase using file lists and ripgrep searches. It matches symbols and scans relevant modules to form a context map.

Once the context is loaded, the agent produces a step-by-step implementation plan (stored as a temporary workspace markdown file). It details files to be created, modified, or deleted.

The plan is presented to you in the TUI or CLI. In SAFE or TRUST mode, Andromity pauses and waits for you to review and click [Approve] or run /approve.

The agent uses granular file tools (like edit_file or write_file) to apply code changes. It modifies only the exact ranges required, minimizing diffs.

After applying changes, Andromity executes your project's test suite (such as pytest, npm test, or go test) via the shell to verify correctness.

If tests pass, Andromity summarizes the modifications and shows a clean git diff. If tests fail, it reads the error stack trace, loops back to fix the bug, and re-runs the tests automatically.