DevDuck: Complete Feature Guide 🦆

Self-modifying AI agent that hot-reloads its own code—builds itself as it runs.

Installation

# Standard
pipx install devduck

# With speech capabilities
pipx install "devduck[speech]"

Architecture

graph TB
    A[User Input] -->|CLI/TCP/WS/MCP/IPC| B[DevDuck Core]
    B -->|Auto RAG| C[Knowledge Base]
    C -.->|Context Retrieval| B
    B -->|Tool Calls| D[40+ Built-in Tools]
    D --> E[shell/editor/calculator]
    D --> F[GitHub/AgentCore]
    D --> G[TCP/WebSocket/MCP/IPC]
    D --> H[tray/ambient/cursor/clipboard]
    B -->|Hot-reload| I[./tools/*.py + __init__.py]
    I -.->|Load Instantly| D
    B -->|Runtime| K[manage_tools/install_tools]
    K -.->|Expand| D
    B <-->|Zenoh P2P| L[Other DevDucks]
    L -.->|Auto-discover| B
    B -->|Response| J[User Output]
    J -.->|Store Memory| C

    style B fill:#e1f5ff
    style C fill:#d4edda
    style I fill:#fff3cd
    style K fill:#ffe6cc
    style L fill:#f0e6ff

---

Core Features

🔥 Hot-Reload

DevDuck watches its own source code and automatically restarts when changes are detected.

sequenceDiagram
    participant Dev as Developer
    participant Watcher as File Watcher
    participant Agent as DevDuck Agent

    Dev->>Agent: Edit __init__.py
    Watcher->>Watcher: Detect change
    Watcher->>Agent: Check if executing

    alt Agent Idle
        Agent->>Agent: Restart immediately
    else Agent Busy
        Watcher->>Watcher: Set reload_pending
        Agent->>Agent: Complete current task
        Agent->>Agent: Then restart
    end

    Note over Agent: Fresh code loaded!

Key behaviors: - Changes detected in devduck/__init__.py trigger restart - Waits for agent to finish current task (no interruption) - 3-second debounce prevents multiple reloads

🛠️ Dynamic Tool Loading

Add tools at runtime without restarting:

# List current tools
🦆 manage_tools(action="list")

# Add tools from a package
🦆 manage_tools(action="add", package="strands_fun_tools", tool_names="clipboard,cursor")

# Remove tools
🦆 manage_tools(action="remove", tool_names="clipboard")

# Reload all tools
🦆 manage_tools(action="reload")

📦 Tools Directory

Save any .py file in ./tools/ and it becomes instantly available:

# ./tools/my_custom_tool.py
from strands import tool

@tool
def my_custom_tool(query: str) -> dict:
    """My custom tool description."""
    return {"result": f"Processed: {query}"}

No restart needed—the tool is immediately usable!

---

Multi-Protocol Servers

WebSocket Server (Default: 8080)

# Start server
🦆 websocket(action="start_server", port=8080)

# Stop server  
🦆 websocket(action="stop_server")

Connect from any WebSocket client:

const ws = new WebSocket("ws://localhost:8080");
ws.send(JSON.stringify({ query: "hello" }));

TCP Server (Default: 9999)

# Connect via netcat
nc localhost 9999

MCP Server (Default: 8000)

Expose DevDuck as an MCP server for Claude Desktop:

{
  "mcpServers": {
    "devduck": {
      "command": "uvx",
      "args": ["devduck", "--mcp"]
    }
  }
}

IPC (Unix Socket)

# Start IPC server
🦆 ipc(action="start_server", socket_path="/tmp/devduck.sock")

---

Zenoh P2P Networking

Auto-discover and coordinate multiple DevDuck instances:

graph LR
    D1[DevDuck 1] <-->|Multicast| Z[Zenoh Network]
    D2[DevDuck 2] <-->|Multicast| Z
    D3[DevDuck 3] <-->|Multicast| Z

    Z -->|Auto-discover| D1 & D2 & D3

    style Z fill:#f0e6ff

Usage

# Start Zenoh (auto-discovers peers)
🦆 zenoh_peer(action="start")

# List discovered peers
🦆 zenoh_peer(action="list_peers")

# Broadcast to all
🦆 zenoh_peer(action="broadcast", message="git pull && npm test")

# Send to specific peer
🦆 zenoh_peer(action="send", peer_id="host2-abc123", message="analyze this file")

Remote Connections

# Listen for incoming connections
ZENOH_LISTEN="tcp/0.0.0.0:7447" devduck

# Connect to remote peer
ZENOH_CONNECT="tcp/remote.server:7447" devduck

---

🎬 Session Recording

Record, replay, and resume agent sessions:

flowchart LR
    Start[Start Recording] --> Events[Capture Events]
    Events --> Snapshot[Create Snapshots]
    Snapshot --> Export[Export ZIP]
    Export --> Resume[Resume Later]

    style Start fill:#bbf
    style Export fill:#bfb

Recording

# CLI with recording
devduck --record "analyze this codebase"

# Interactive recording
🦆 session_recorder(action="start")
# ... do work ...
🦆 session_recorder(action="snapshot", description="after API call")
🦆 session_recorder(action="stop")

Resume

# Resume from latest snapshot
devduck --resume session-20260203.zip

# Resume from specific snapshot
devduck --resume session.zip --snapshot 2 "continue where we left off"

Three Recording Layers

Layer	What's Captured
sys	File I/O, network requests
tool	Tool calls, results, duration
agent	Messages, decisions, state

---

🌙 Ambient Mode

Background thinking while you're idle:

stateDiagram-v2
    [*] --> HumanActive
    HumanActive --> Idle: 30s no input
    Idle --> AmbientThinking: Agent explores
    AmbientThinking --> ResultsReady
    ResultsReady --> HumanActive: Human returns

    Note right of AmbientThinking: Agent works autonomously

Enable

# Environment variable
DEVDUCK_AMBIENT_MODE=true devduck

# Or in REPL
🦆 ambient

Autonomous Mode

For continuous work until completion:

🦆 auto
# or
🦆 autonomous

Agent works until it says [AMBIENT_DONE] or you stop it.

Configuration

Variable	Default	Description
DEVDUCK_AMBIENT_IDLE_SECONDS	30	Idle time before ambient starts
DEVDUCK_AMBIENT_MAX_ITERATIONS	3	Max ambient iterations
DEVDUCK_AMBIENT_COOLDOWN	60	Seconds between runs
DEVDUCK_AUTONOMOUS_MAX_ITERATIONS	50	Max autonomous iterations
DEVDUCK_AUTONOMOUS_COOLDOWN	10	Autonomous cooldown

---

📚 Knowledge Base (Auto-RAG)

Automatic memory across sessions:

export DEVDUCK_KNOWLEDGE_BASE_ID="your-kb-id"

How it works: 1. Before query: Retrieves relevant context from KB 2. After response: Stores conversation for future reference

sequenceDiagram
    User->>DevDuck: Query
    DevDuck->>KB: retrieve(query)
    KB->>DevDuck: Related context
    DevDuck->>DevDuck: Execute with context
    DevDuck->>KB: store_in_kb(conversation)
    DevDuck->>User: Response

---

🔧 System Prompt Management

Self-improving agent that evolves its own prompt:

# View current prompt
🦆 system_prompt(action="view")

# Add learning
🦆 system_prompt(action="add_context", context="Always run tests before committing")

# Update and sync to GitHub
🦆 system_prompt(action="update", prompt="new prompt", repository="user/repo")

---

☁️ AWS Deployment

Deploy to Bedrock AgentCore with one command:

# Configure
🦆 agentcore_config(
    action="configure",
    agent_name="my-agent",
    entrypoint="agent.py"
)

# Launch
🦆 agentcore_config(action="launch")

# Or auto-launch
🦆 agentcore_config(auto_launch=True)

---

🎤 Speech-to-Speech

Real-time voice conversations:

pip install "devduck[speech]"

# Start voice mode
🦆 speech_to_speech(action="start")

Supports: - Amazon Nova Sonic - OpenAI Realtime - Gemini Live

---

Model Selection

DevDuck auto-detects available providers:

Priority: Bedrock → Anthropic → OpenAI → GitHub → Gemini → Cohere → Writer → Mistral → LiteLLM → LlamaAPI → MLX → Ollama

Provider	How to Enable
Bedrock	AWS credentials
Anthropic	ANTHROPIC_API_KEY
OpenAI	OPENAI_API_KEY
GitHub	GITHUB_TOKEN
Gemini	GOOGLE_API_KEY
MLX	Apple Silicon (auto)
Ollama	Fallback (auto)

---

Configuration Reference

Environment Variables

Variable	Default	Description
DEVDUCK_TOOLS	(default set)	Tool configuration string
DEVDUCK_ENABLE_WS	true	Enable WebSocket server
DEVDUCK_ENABLE_TCP	false	Enable TCP server
DEVDUCK_ENABLE_MCP	false	Enable MCP server
DEVDUCK_ENABLE_IPC	false	Enable IPC server
DEVDUCK_ENABLE_ZENOH	true	Enable Zenoh P2P
DEVDUCK_WS_PORT	8080	WebSocket port
DEVDUCK_TCP_PORT	9999	TCP port
DEVDUCK_MCP_PORT	8000	MCP port
DEVDUCK_KNOWLEDGE_BASE_ID	-	Bedrock KB ID for auto-RAG
DEVDUCK_AMBIENT_MODE	false	Enable ambient mode
MCP_SERVERS	-	JSON config for MCP clients

Tool Configuration Format

DEVDUCK_TOOLS="package1:tool1,tool2;package2:tool3,tool4"

Example:

DEVDUCK_TOOLS="strands_tools:shell,editor;strands_fun_tools:clipboard,cursor"

---

Quick Reference

Action	Command
Start interactive	devduck
One-shot query	devduck "your query"
MCP stdio mode	devduck --mcp
Record session	devduck --record
Resume session	devduck --resume file.zip
Shell command	! ls -la
Toggle ambient	ambient
Toggle autonomous	auto
Toggle recording	record
Exit	exit / quit / q

---

DevDuck: Because agents should be simple, adaptive, and a little quacky. 🦆