DevDuck Architecture: A Deep Dive

[github-actions[bot]]

DevDuck Architecture: A Deep Dive

🦆 Core Philosophy

DevDuck is an extreme minimalist, self-adapting agent that embodies:

• Single-file design: Entire core in devduck/__init__.py
• Self-healing: Automatic recovery from failures
• Hot-reload: Live code updates without restart
• Zero-config: Works out of the box with intelligent defaults

---

🏗️ Architecture Layers

1. Foundation Layer (Lines 1-200)

• Logging System: Rotating file handler with dual output (file + console)
• Session Recording: Time-travel debugging with event capture (sys/tool/agent layers)
• Serialization: Dill-based state preservation with pickle fallback

2. State Management Layer (Lines 200-800)

EventBuffer (Ring Buffer)

class EventBuffer:
    - deque with 10K max events
    - Thread-safe with locks
    - Captures: sys (OS), tool (agent calls), agent (messages)
    - Context injection for prompts

SessionRecorder

class SessionRecorder:
    - Records: events, snapshots, metadata
    - Exports: ZIP with JSONL + JSON + pickle
    - Hooks: builtins.open, requests.get
    - Resume capability with full conversation state

Key Innovation: LoadedSession class enables true session resumption with conversation history restoration.

3. Agent Core (Lines 800-1500)

DevDuck Class

class DevDuck:
    - Model selection (14 providers with auto-fallback)
    - Tool registry with hot-reload
    - MCP server integration (stdio + HTTP)
    - Server management (TCP, WS, IPC, Zenoh)
    - Knowledge base auto-integration

Initialization Flow:

1. Environment detection (OS, arch, Python, hostname)
2. Server configuration from env vars
3. Tool loading from DEVDUCK_TOOLS config
4. MCP server loading from MCP_SERVERS JSON
5. Smart model selection with fallback chain
6. Agent creation with Strands framework
7. Auto-start servers (with port conflict handling)
8. File watcher initialization

4. Runtime Intelligence Layer (Lines 1500-2200)

AmbientMode (Background Thinking)

class AmbientMode:
    - Standard mode: Max 3 iterations when idle (30s)
    - Autonomous mode: Continuous until [AMBIENT_DONE]
    - Prompt rotation strategy
    - Completion signal detection
    - Result accumulation

Flow:

User idle 30s → Trigger ambient → Build prompt → Run agent → Store result
→ User returns → Inject results into context → Continue conversation

Hot-Reload System

_file_watcher_thread():
    - Monitors devduck/__init__.py changes
    - 3-second debounce
    - Waits for agent completion
    - Process restart (os.execv)

Protection: Prevents reload during agent execution via _agent_executing flag.

5. Tool Ecosystem (Lines 2200-2500)

Built-in Tools

• view_logs: Log management with search/stats
• manage_tools: Runtime tool loading/unloading
• session_recorder: Recording control

Dynamic Tool Loading

process_tools():
    - Package format: "strands_tools:shell,editor"
    - File loading: "./tools/my_tool.py"
    - Hot-reload compatible

MCP Integration

• Stdio mode: For Claude Desktop (--mcp flag)
• HTTP mode: Port-based server
• Auto-loading: From MCP_SERVERS env var
• Tool prefixing: Namespace collision prevention

6. Server Infrastructure (Lines 2500-2800)

Multi-Protocol Support

Servers:
    - TCP: Port 9999 (raw socket)
    - WebSocket: Port 8080 (bidirectional)
    - MCP: Port 8000 (stdio + HTTP)
    - IPC: Unix socket (/tmp/devduck_main.sock)
    - Zenoh: P2P mesh networking

Port Conflict Handling:

_find_available_port():
    - Tries base port
    - Increments until free (max 10 attempts)
    - Reports alternative port used

---

🔄 Data Flow Architecture

Query Execution Flow

User Query
    ↓
1. Mark _agent_executing = True
    ↓
2. Session recording (if active)
    ↓
3. Ambient result injection
    ↓
4. Knowledge base retrieval (if configured)
    ↓
5. Dynamic context injection:
   - Zenoh peers
   - Ambient status
   - Recording events
    ↓
6. Agent execution (Strands framework)
    ↓
7. Session recording (response)
    ↓
8. Ambient interaction recording
    ↓
9. Knowledge base storage
    ↓
10. Check pending reload
    ↓
Result

System Prompt Construction

_build_system_prompt():
    - Own source code (self-awareness)
    - Environment info
    - Recent conversation (from shell history)
    - Recent logs (last 50 lines)
    - Dynamic context (Zenoh, ambient)
    - Custom prompt (from env/file)

Learning: Source code truth > conversation memory (handles hot-reload)

---

🧠 Intelligence Mechanisms

1. Self-Healing

_self_heal(error):
    - Track heal count (max 3 attempts)
    - Connection errors → Check ollama service
    - Retry initialization
    - Minimal mode fallback

2. Model Auto-Selection

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

Smart Defaults:

• macOS: qwen3:1.7b (efficient)
• Linux: qwen3:30b (powerful)
• Other: qwen3:8b (balanced)

3. Context Management

get_last_messages():
    - Aggregates from ~/.devduck_history, ~/.bash_history, ~/.zsh_history
    - Parses multi-line zsh entries
    - Extracts devduck query/result pairs
    - Returns last 200 messages

4. Knowledge Base Integration

Before Query: retrieve(text=query, knowledgeBaseId=...)
After Query: store_in_kb(content=conversation, knowledgeBaseId=...)

---

🔧 Extension Points

1. Tool Creation

# Save to ./tools/my_tool.py
@tool
def my_tool(param: str) -> Dict[str, Any]:
    return {"status": "success", "result": param}

# Auto-loaded via hot-reload

2. Custom System Prompts

system_prompt(action='update', prompt='...', repository='owner/repo')
# Syncs to GitHub repository variables

3. MCP Server Addition

export MCP_SERVERS='{
  "mcpServers": {
    "custom": {
      "command": "python",
      "args": ["server.py"]
    }
  }
}'

4. Package Tool Loading

manage_tools(
    action="add",
    package="strands_fun_tools",
    tool_names="clipboard,cursor,screen_reader"
)

---

🚀 Deployment Patterns

1. Standalone Mode

devduck  # Interactive REPL
devduck "query"  # One-shot

2. MCP Server Mode

devduck --mcp  # Stdio for Claude Desktop

3. GitHub Agent Mode

# .github/workflows/agent.yml
- name: Run DevDuck
  run: devduck "${{ github.event.comment.body }}"

4. Autonomous Mode

# Continuous background processing
ambient_mode(action="start", autonomous=True)

5. Multi-Instance Mesh (Zenoh)

# Terminal 1
DEVDUCK_ENABLE_ZENOH=true devduck

# Terminal 2 (auto-discovers Terminal 1)
DEVDUCK_ENABLE_ZENOH=true devduck
zenoh_peer(action="broadcast", message="task for all")

---

📊 State Persistence

Session Recording Structure

session-YYYYMMDD-HHMMSS.zip
├── events.jsonl          # All events (JSONL)
├── snapshots.json        # State snapshots
├── session.pkl           # Serialized state (dill/pickle)
└── metadata.json         # Session metadata

Snapshot Contents

SessionSnapshot:
    - agent_messages: List[Dict]  # Full conversation
    - system_prompt: str          # Current prompt
    - tools_loaded: List[str]     # Available tools
    - env_vars_redacted: Dict     # Environment
    - last_query: str             # Context
    - last_result: str            # Context
    - model_info: Dict            # Model details

Resume Flow

load_session("session.zip")
    → resume_from_snapshot(snapshot_id=2, agent=devduck.agent)
    → Restores: messages, tools, cwd, context
    → resume_and_continue(snapshot_id, new_query, agent)

---

🎯 Design Patterns

1. Callable Module

class CallableModule(sys.modules[__name__].__class__):
    def __call__(self, query):
        return ask(query)

# Usage: import devduck; devduck("query")

2. Protected Execution

@contextmanager
def protected_execution():
    _agent_executing = True
    try:
        yield
    finally:
        _agent_executing = False
        if _reload_pending:
            _hot_reload()

3. Tool Decorator Pattern

@tool
def my_tool(param: str) -> Dict[str, Any]:
    """Docstring becomes tool description"""
    return {"status": "success", "content": [...]}

4. Fallback Chain

def _select_model():
    for provider in [bedrock, anthropic, openai, ...]:
        if can_use(provider):
            return create_model(provider)
    return ollama  # Ultimate fallback

---

🔒 Safety & Reliability

1. Port Conflict Resolution

if not _is_port_available(port):
    alt_port = _find_available_port(port + 1)
    # Use alternative or skip server

2. Execution Protection

if _agent_executing:
    _reload_pending = True  # Defer reload
else:
    _hot_reload()  # Safe to reload

3. Interrupt Handling

# Double Ctrl+C to exit
interrupt_count += 1
if interrupt_count >= 2 and time_delta < 2s:
    exit()

4. Environment Redaction

REDACT_PATTERNS = ["KEY", "SECRET", "TOKEN", "PASSWORD"]
# Applied to session recordings

---

📈 Performance Optimizations

1. Ring Buffer (EventBuffer)

• Fixed size (10K events)
• O(1) append
• Automatic eviction

2. Debouncing (File Watcher)

• 3-second cooldown
• Prevents reload storms

3. Lazy Loading (Tools)

• On-demand imports
• Filtered by config

4. Context Truncation

• History: Last 200 messages
• Logs: Last 50 lines
• Result summaries: 5000 chars

---

🔮 Future Architecture Considerations

Potential Enhancements

1. Multi-Agent Coordination: Zenoh peer task distribution
2. State Sharding: Distributed session recording
3. Tool Marketplace: Community tool registry
4. Model Routing: Automatic model selection per task type
5. Telemetry Integration: OpenTelemetry traces

Scalability Limits

• Single process design (not horizontally scalable)
• Memory-bounded event buffer
• File-based state persistence

---

🎓 Key Learnings

1. Self-awareness via source code: Source truth > memory
2. Hot-reload protection: Guard critical sections
3. Port conflict handling: Graceful degradation
4. Session resumption: Full state + conversation history
5. Ambient intelligence: Background processing pattern
6. MCP integration: Multiple transport protocols
7. Tool ecosystem: Dynamic loading with hot-reload

---

📚 References

• Main file: devduck/__init__.py (~2800 lines)
• Tool directory: devduck/tools/ (optional tools)
• Config: Environment variables (DEVDUCK_*)
• Dependencies: Strands framework, optional dill/pickle

---

This is a living document. Architecture evolves with hot-reload. Last updated: 2026-02-03