mini_agent CLAUDE.md

Mini_agent

File structure and development

Files:

• mini_agent.py -- main entrypoint for agentic loop
• core_tools.py -- MCP server with tools, hooks and system prompts
• typedefs.py -- type definitions
• utils.py -- common helpers used by agentic loop
• test/*.py -- various unit tests
• test/sample_data -- directory with immutable sample data

Codebase:

• uses litellm library, to make calls to different LLMs in a uniform way
• uses watchdog, to be able to notify about file changes
• uses mcp, for some common tool definitions
• uses pyright, for typechecking in strict mode
• uses pytest, for testing

Running and testing:

• Set up venv and install dependencies:

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

• On subsequent use, just source venv/bin/activate.
• Run the agentic loop:

OPENAI_API_KEY=redacted    ./mini_agent.py --model gpt-4.1
GEMINI_API_KEY=redacted    ./mini_agent.py --model gemini/gemini-2.5-pro
ANTHROPIC_API_KEY=redacted ./mini_agent.py --model anthropic/claude-sonnet-4-20250514

• Test the mcp server:
  • npx @modelcontextprotocol/inspector --cli ./core_tools.py --method tools/list
  • npx @modelcontextprotocol/inspector --cli ./core_tools.py --method resources/templates/list
• Unit tests: for example python -m pytest test/test_edit.py

Codebase style and guidelines

All code MUST be written with a high degree of rigor:

• All functions are documented to say what they do, what side effects they have in any
• All state variables MUST be documented with INVARIANTS. Every function's comments MUST explain which invariants the function is assuming, and which ones it establishes/upholds, and how,
• When we do code review, we always review by checking it against invariants.
• When we write code, we add comments to explain whenever code relies upon a documented assumption, or ensures a documented guarantee.

IMPORTANT: The AI agent MUST ALWAYS evaluate code with skepticism and rigor.

• IMPORTANT: The AI agent MUST ALWAYS look for flaws, bugs, loopholes, in what the user writes and what the AI agent writes.
• IMPORTANT: instead of saying "that's right" to a user prompt, the AI agent must instead think to find flaws, loopholes, problems, and question what assumptions went into a question or solution.
• A good way to find flaws is to think through the code line by line with a worked example.