devduck

DevDuck is a self-modifying AI agent written in Python that can hot-reload its own code and expand its capabilities at runtime. It exposes a rich set of features including dynamic runtime tools, multi-protocol communication (TCP/WebSocket/MCP/IPC), a Web UI, and a unified mesh that lets CLI, browser, and cloud agents coordinate. You can add new tools by placing Python files in the ./tools directory or manage tools at runtime with actions like add or install_and_load. For external integrations, DevDuck can connect to MCP servers via the MCP_SERVERS environment variable and can participate in a Zenoh P2P mesh for auto-discovery and coordination with other DevDucks. The project also supports session recording, ambient/macro modes, and a full browser-based or terminal-based interaction flow.

Prerequisites:

• Python 3.10–3.13 (recommended)
• Optional: a virtual environment tool (venv) or Python virtualenv

Install (preferred via pipx, then run):

# Install via pipx (recommended)
pipx install devduck

# Run the tool
devduck

Install directly into a virtual environment (alternative):

python3 -m venv .venv
source .venv/bin/activate  # on Unix/macOS
# Windows: .venv\Scripts\activate

pip install --upgrade pip
pip install devduck

# Run the tool
devduck

One-liner to run as a module (alternative entry):

python -m devduck

Optional extras (if you want speech features):

pip install devduck[speech]
# then run
devduck

If you prefer Docker or other runtimes, consult the project docs for containerized options (not required for basic usage).

Tips and common issues:

• Environment variables to know:
  • MCP_SERVERS: comma-separated list of external MCP server endpoints to connect to as a client
  • DEVDUCK_KNOWLEDGE_BASE_ID: ID for the Knowledge Base used by Auto-RAG
  • DEVDUCK_AMBIENT_MODE=true: enable ambient thinking in the background
  • DEVDUCK_ASCIINEMA=true: enable terminal cast recording via asciinema
• DevDuck supports hot-reload by monitoring the ./tools directory and init.py; changes trigger immediate reloads.
• If you add new tools by placing .py files in ./tools, ensure they expose a compatible interface so that the runtime can load and execute them.
• For recording sessions, use --record or the session_recorder utilities; recordings are saved to /tmp/devduck/recordings.
• When deploying to AgentCore or cloud environments, use devduck deploy --launch for a one-command deployment workflow.
• If you encounter environment-specific issues (e.g., networking, firewall), ensure ports 10001/10002/10003 (as referenced) are accessible and that MCP or Zenoh peers can discover each other.
• Documentation and examples are available in the README and docs folder; refer to those for advanced tooling like the RL/ML toolkit, browser peers, and multi-protocol support.