ANA MAX

ANA MAX is a Windows-first MCP runtime for local QA labs, private workstations, offline LLMs, and AI coding agents that need real situational awareness before they act: files, git state, terminal output, desktop vision, Windows UI automation, memory, runtime instrumentation, voice feedback, and smoke-test verification.

This repository is the clean public release. It must stay public-safe, repeatable, and boring in the best possible way.

Why It Exists

Most agents lose time because they guess from partial context. ANA MAX is built to help agents observe the real workspace first, pick the smallest useful tool, act, verify the result, and remember useful lessons.

The intended workflow is:

observe -> instrument when needed -> act -> verify -> learn

This can turn long manual debugging, QA, UI inspection, and local automation work into a focused agent workflow, especially when the agent can see the desktop, inspect Windows UI/API state, use git and tests, speak status aloud, and use Frida for authorized runtime instrumentation.

ANA MAX is privacy-first and hybrid:

• local/offline workflows are the default direction;
• online models can be used when configured by the operator;
• MCP auth is enabled by default;
• private memory, logs, screenshots, tokens, and license files do not belong in the public release.

Local QA Lab Vision

ANA MAX is designed for environments where data should stay on the machine:

• QA labs that need repeatable desktop observations, logs, and smoke checks;
• AI coding agents working with local projects and local evidence;
• offline Ollama-style model setups where tools provide the missing senses;
• security or reverse-engineering labs where Frida is used only with authorization and only when runtime instrumentation is really needed;
• private workstations where screenshots, memory, logs, and tokens must not be uploaded to a cloud service.

The important idea is simple: a local model can reason, but tools give it eyes, hands, ears, memory, and verification. See docs/LOCAL_QA_LAB_VISION.md.

What Makes It Different

• It gives agents situational awareness, not just file access.
• It combines desktop vision, Windows UI automation, code tools, git, memory, and verification in one workflow.
• It supports authorized runtime instrumentation with Frida when static inspection is not enough.
• It treats desktop_capture as free Vision AI and keeps deep desktop control premium-gated.
• It keeps public docs and shell-facing examples ASCII-only so Windows consoles and weaker agents can parse them reliably.

AI Collaboration Acknowledgement

This project was built and repaired through a human-led engineering workflow. Dragos owns the vision, direction, testing, and final decisions.

OpenAI Codex has been an important AI coding collaborator for this release:

• helped turn a noisy experimental workspace into a cleaner public release;
• helped repair MCP, voice, desktop diagnostic, and release-hygiene workflows;
• helped separate public-safe demo material from local-only tools;
• helped keep changes testable through repeatable quality checks;
• helped document the project in a way that engineers can verify instead of trusting hype.

The goal of this acknowledgement is simple: show that AI tools can be useful when they work as careful engineering collaborators, not blind code generators.

Demo

Website - Live Demo

Current public videos:

• Watch Demo 1 on YouTube
• Watch Demo 2 on YouTube

Video demos should be hosted outside git, for example on YouTube or GitHub Releases, then linked from this README and the website. Large .mp4 files do not belong in the repository.

The demo should prove the core workflow quickly: observe the workspace, choose focused tools, act, run smoke checks, and verify the result. Keep the public demo short and factual; users should understand the value before reading the full architecture notes.

For the recommended public recording plan, see docs/ANA_MAX_WOW_DEMO.md.

Quick Start

Run from the repository root:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
$env:MCP_API_KEY = "change-me"
python main.py

# Launch the voice engine
scripts\ana_voice.bat

ANA MAX starts on http://127.0.0.1:8765 by default.

MCP auth is enabled by default. Send:

Authorization: Bearer change-me

Example MCP request:

curl -X POST http://127.0.0.1:8765/mcp `
  -H "Content-Type: application/json" `
  -H "Authorization: Bearer change-me" `
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Verification

Before handing off changes, run:

python -m compileall -q main.py core tools vscode_extension
python main.py --test
python main.py --list-tools
python -m unittest discover -s tests -v

Expected baseline:

• python main.py --test: 3 PASS / 0 FAIL
• python main.py --list-tools: 64 loaded tools
• python -m unittest discover -s tests -v: all tests passing

Tool Model

Core tool behavior is owned by tools/base.py.

Tool Status Overview

Category	Status	Example Tools
Core Utilities	Stable	file_operations, code_tools, git_operations
Desktop Eyes	Stable	desktop_capture, windows_uia_bridge, ocr_tool
AI Core Modules	Experimental	context_engine, self_evolving_tool
Deep Windows API	Premium / Pro	desktop_control, windows_deep_sight

New tools must:

• inherit from tools.base.Tool;
• implement get_definition() and execute();
• be registered from main.py;
• be importable from this clean repo;
• have docs only when the code and tests exist.

Premium Gate

desktop_capture is free Vision AI.

These tools are premium-gated at runtime:

• live_desktop_viewer
• desktop_control
• desktop_control_tool
• windows_insight
• windows_insight_tool
• windows_deep_sight

Premium checks happen in ToolRegistry.execute(), so the gate applies through CLI, HTTP, and MCP.

Windows And PowerShell Text Rule

All commands, expected terminal output, log examples, and setup snippets in public docs must be ASCII-only. Do not use Romanian diacritics, smart quotes, emoji, or mojibake in shell-facing text.

Good:

3 PASS / 0 FAIL
64 loaded tools
Authorization: Bearer change-me

Bad:

mojibake text
non-ascii shell output

This is deliberate. Cheap agents and Windows consoles often stumble on encoded text. Public docs should be simple enough that weak agents cannot misread them.

Public Release Hygiene

Do not add private workspace notes, local IDE setup files, local shortcuts, private tokens, logs, databases, or screenshots.

If a feature is experimental, keep it private until code, tests, docs, and release hygiene are all present.

When behavior changes, update code, docs, .env.example, tests, and release counts together. Users should never need private notes to know how the public release works.

License

MIT. Use automated desktop control only on machines you own or are allowed to operate.