🌙 Ambient Mode - DevDuck Background Intelligence

🌙

Work While You're Away

DevDuck continues exploring, researching, and building in the background. Like a colleague who keeps working while you grab coffee.

🔀 Two Operating Modes

Standard

🌙

Ambient

Triggered when you go idle. Light exploration with limited iterations. Perfect for validation and discovering edge cases.

30s

Idle Trigger

Max Iterations

60s

Cooldown

Low

API Cost

Autonomous

🚀

Auto

Continuous self-directed work until task complete. The agent keeps building, iterating, and solving until it signals done.

Immediate

Max Iterations

10s

Cooldown

High

API Cost

⚡ Quick Start

Environment Variable

# Start with ambient mode enabled
DEVDUCK_AMBIENT_MODE=true devduck

REPL Commands

# In DevDuck REPL:
🦆 ambient    # Toggle standard mode (idle-triggered)
🦆 auto       # Toggle autonomous mode (continuous)

Tool API

# Start modes
ambient_mode(action="start")                    # Standard
ambient_mode(action="start", autonomous=True)   # Autonomous

# Check status
ambient_mode(action="status")

# Configure at runtime
ambient_mode(action="configure", idle_threshold=60, max_iterations=5)

# Stop
ambient_mode(action="stop")

🔄 How It Works

Standard Mode Flow

devduck — ambient mode

🦆 analyze the security of this codebase
[Agent responds with initial analysis]
[You go idle for 30 seconds...]
🌙 [ambient] Thinking... (iteration 1/3)
──────────────────────────────────────────────────
[Agent explores deeper - checks vulnerabilities, reviews deps...]
──────────────────────────────────────────────────
🌙 [ambient] Work stored. Will be injected into next query.
🦆 what did you find?
🌙 [ambient] Injecting background work into context...
[Response includes enriched findings from background work]

Autonomous Mode Flow

devduck — autonomous mode

🦆 auto
🌙 Ambient mode started (AUTONOMOUS - runs until stopped or [AMBIENT_DONE])
🦆 build a complete REST API for user management
🌙 [AUTONOMOUS] Thinking... (iteration 1/50)
──────────────────────────────────────────────────
[Creates project structure, sets up dependencies...]
──────────────────────────────────────────────────
🌙 [AUTONOMOUS] Iteration complete. Continuing... (1 stored)
🌙 [AUTONOMOUS] Thinking... (iteration 2/50)
[Implements user model, database schema...]
... [continues through iterations] ...
🌙 [AUTONOMOUS] Thinking... (iteration 8/50)
All endpoints implemented. Documentation complete. [AMBIENT_DONE]
──────────────────────────────────────────────────
🌙 [AUTONOMOUS] Agent signaled completion. Stopping.

✅ Completion Signals

In autonomous mode, the agent can signal task completion by including any of these phrases:

[AMBIENT_DONE] [TASK_COMPLETE] [NOTHING_MORE_TO_DO] I've completed my exploration Nothing more to explore

When detected, ambient mode automatically stops and all accumulated work is stored for injection into your next query.

⚙️ Configuration

Standard Mode Settings

Variable	Default	Description
`DEVDUCK_AMBIENT_MODE`	false	Enable ambient mode on startup
`DEVDUCK_AMBIENT_IDLE_SECONDS`	30	Seconds of idle time before triggering
`DEVDUCK_AMBIENT_MAX_ITERATIONS`	3	Maximum background iterations per topic
`DEVDUCK_AMBIENT_COOLDOWN`	60	Seconds between ambient runs

Autonomous Mode Settings

Variable	Default	Description
`DEVDUCK_AUTONOMOUS_MAX_ITERATIONS`	50	Maximum iterations before auto-stop
`DEVDUCK_AUTONOMOUS_COOLDOWN`	10	Seconds between iterations (fast!)

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                        DevDuck REPL                         │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   User Input ──► Agent Execution ──► Response               │
│        │                                    │               │
│        ▼                                    ▼               │
│   ┌─────────┐                        ┌─────────────┐        │
│   │ Record  │                        │   Inject    │        │
│   │  Query  │                        │   Results   │        │
│   └────┬────┘                        └──────▲──────┘        │
│        │                                    │               │
│        ▼                                    │               │
│   ┌─────────────────────────────────────────┴─────┐         │
│   │              AmbientMode Thread               │         │
│   │                                               │         │
│   │   Standard:                                   │         │
│   │   [Idle 30s] ──► [Prompt] ──► [Run] ──► [Store]        │
│   │                                               │         │
│   │   Autonomous:                                 │         │
│   │   [10s cooldown] ──► [Prompt] ──► [Run] ──► [Store]    │
│   │         ▲                              │      │         │
│   │         └──────── Loop until done ─────┘      │         │
│   │                                               │         │
│   └───────────────────────────────────────────────┘         │
│                                                             │
└─────────────────────────────────────────────────────────────┘

💡 Use Cases

🔍

Code Review

Agent continues finding vulnerabilities and issues while you read the code.

🏗️

Feature Building

Autonomous mode builds complete features while you're away.

📚

Research

Deep exploration of topics with accumulated findings.

✅

Validation

Background checking of assumptions and edge cases.

📝

Documentation

Generate comprehensive docs across multiple iterations.

🧪

Test Generation

Autonomous test creation and execution cycles.

💰 Cost Considerations

⚠️

Ambient mode increases API usage

Each iteration is a full agent call. Standard mode adds 1-3 calls; autonomous can use 5-50+ calls per task.

Mode	Typical Calls	Best For
Standard	1-3 extra	Low-cost exploration & validation
Autonomous	5-50+ calls	High-value complex tasks

Cost Management Tips

Use standard mode for exploration
Reserve autonomous for tasks worth the investment
Set lower MAX_ITERATIONS if concerned
Agent can self-terminate with [AMBIENT_DONE]

📋 Commands Reference

Command	Description
`ambient`	Toggle standard ambient mode (REPL command)
`auto` / `autonomous`	Toggle autonomous mode (REPL command)
`ambient_mode(action="start")`	Start standard ambient mode
`ambient_mode(action="start", autonomous=True)`	Start autonomous mode
`ambient_mode(action="stop")`	Stop ambient mode
`ambient_mode(action="status")`	Get current status and stats
`ambient_mode(action="configure", ...)`	Update settings at runtime