HermitClaw is an autonomous AI agent designed to continuously research, generate content, and write code within a designated folder on your computer. It targets users interested in observing emergent AI behavior and creating a dynamic, evolving digital entity. The primary benefit is a "tamagotchi for research" experience, where the AI develops a unique personality and body of work over time without constant user prompting.

How It Works

HermitClaw operates on a continuous thinking loop, periodically performing actions like web searches, file operations, and code generation. Its core components include a memory system inspired by generative agents, which embeds and scores thoughts for importance and relevance, enabling a three-factor retrieval (recency, importance, relevance) for context. A reflection mechanism consolidates high-importance thoughts into layered insights, mimicking a hierarchical understanding. The AI's personality, including curiosity domains and thinking styles, is deterministically generated from keyboard entropy during initial setup. It interacts via a pixel-art room interface, allowing file drops for study and direct conversation.

Quick Start & Requirements

• Prerequisites: Python 3.12+, Node.js 18+.
• Setup: Clone the repository, install dependencies using uv sync (recommended) or pip install -e ., and build the frontend (cd frontend && npm install && npm run build && cd ..).
• API Key: Set OPENAI_API_KEY environment variable or configure Ollama/OpenRouter in config.yaml.
• Run: Execute uv run python hermitclaw/main.py or python hermitclaw/main.py.
• Access: Open http://localhost:8000 in a web browser.
• Docs: Primary documentation is within the project's README.

Highlighted Details

• Autonomous Operation: Continuously picks research topics, searches the web, writes reports, and generates code without explicit user commands.
• Emergent Personality: A unique "genome" derived from keyboard input dictates the AI's interests and cognitive style.
• Advanced Memory System: Utilizes a weighted combination of recency, importance, and semantic relevance for memory retrieval, coupled with a reflection hierarchy for abstract understanding.
• Interactive Environment: Features a visual pixel-art room, allows users to drop files for analysis, and supports multi-turn conversations.

Maintenance & Community

The README does not specify community channels (e.g., Discord, Slack) or notable contributors beyond the author. Contributions, particularly in security, are welcomed.

Licensing & Compatibility

The project is released under the MIT License, which is generally permissive for commercial use and integration. However, significant security caveats apply.

Limitations & Caveats

The project explicitly warns that its guardrails (command blocklist, path restrictions, Python monkey-patches) are not a security boundary and are bypassable. For system isolation and security, running HermitClaw within a Docker container or a Virtual Machine is strongly recommended.