D.U.H. — Getting Started

Installation

D.U.H. requires Python 3.12+. Install from PyPI or from source during the alpha period.

From PyPI (recommended)

bash

# Core install (Anthropic + Ollama)
pip install duh-cli

# With OpenAI API support
pip install 'duh-cli[openai]'

# With Rich TUI rendering
pip install 'duh-cli[rich]'

# With security scanners (ruff, pip-audit, detect-secrets, cyclonedx)
pip install 'duh-cli[security]'

# Everything
pip install 'duh-cli[all]'

From Source

bash

git clone https://github.com/nikhilvallishayee/duh
cd duh
python3.12 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

Verify the install

bash

duh --version
duh doctor   # checks providers, keys, dependencies

Provider Setup

Anthropic Claude (default)

Set your API key as an environment variable. D.U.H. auto-detects it.

bash

export ANTHROPIC_API_KEY=sk-ant-...

# Or connect interactively in the REPL
duh
> /connect anthropic

OpenAI API

bash

export OPENAI_API_KEY=sk-...

duh --provider openai --model gpt-4o -p "your task"

ChatGPT Plus/Pro — Codex (OAuth, no API key)

D.U.H. is the only Python agent that supports ChatGPT Plus/Pro via OAuth. Run the connect flow in the REPL:

bash

duh
> /connect openai
# Opens browser → ChatGPT OAuth → stores token in ~/.config/duh/auth.json

# Then use Codex models
duh --provider openai_chatgpt --model gpt-5.2-codex -p "refactor auth.py"

Ollama (local models)

Start Ollama, pull a model, then point D.U.H. at it. No internet connection required after pull.

bash

# Start Ollama (runs on localhost:11434)
ollama serve

# Pull a coding model
ollama pull qwen2.5-coder:7b

# Use with D.U.H.
duh --provider ollama --model qwen2.5-coder:7b -p "write tests for auth.py"

litellm / OpenRouter (100+ models)

bash

pip install litellm

# Use any model via litellm proxy
duh --provider litellm --model gemini/gemini-2.0-flash -p "your task"

✓

Auto-detection: Pass --model claude-sonnet-4-6 and D.U.H. will auto-route to Anthropic. Pass --model gpt-5.2-codex and it routes to ChatGPT OAuth if tokens exist, or OpenAI API with your key. No --provider flag required.

First Session

D.U.H. has three modes: print mode (pipe-friendly, great for scripts), REPL mode (interactive), and SDK mode (NDJSON protocol). Start with print mode.

Print mode (-p)

bash

# Simple one-shot task
duh -p "add type hints to all functions in src/api.py"

# With a specific model
duh --model claude-haiku-4-5 -p "write a test for the login function"

# Limit turns (default: 30)
duh --max-turns 10 -p "fix all linting errors in src/"

# Auto-approve all tool calls (use with care)
duh --approval-mode full-auto -p "build a FastAPI CRUD app"

# JSON output (for scripts)
duh --output json -p "list the files in src/"

TUI / REPL Mode

Run duh with no arguments to enter the interactive REPL. Built on Rich — fast, clean, no Electron.

bash

duh                          # start REPL with auto-detected provider
duh --model gpt-4o           # start with a specific model
duh --continue              # resume the last session
duh --session <session-id>  # resume a specific session

In the REPL, type your task at the prompt. Tool calls show their inputs and outputs inline. Press Ctrl+C to interrupt a running task, Ctrl+D to exit.

ℹ

Approval mode in REPL: By default, D.U.H. shows each tool call and asks for approval. Use /model to switch models mid-session, or start with --approval-mode auto-edit to approve file edits automatically but prompt for shell commands.

Running a Security Scan

D.U.H. includes a built-in vulnerability scanner. It covers your project, not just D.U.H. itself.

bash

# Initialize security policy (one-time setup)
duh security init

# Run a full scan
duh security scan

# Scan with SARIF output (for GitHub Code Scanning)
duh security scan --format sarif --output results.sarif

# Run only the fast "minimal" tier
duh security scan --tier minimal

# Install pre-push git hook
duh security init --install-hooks

# Check scanner health
duh security doctor

⚠

First run: The security extra installs ruff, pip-audit, detect-secrets, and cyclonedx-bom. Run pip install 'duh-cli[security]' if you skipped it.

REPL Cheat Sheet

21 slash commands available in the interactive REPL. Type /help for full descriptions.

Session

/modelSwitch model mid-session
/statusSession info, token usage
/costAPI cost so far
/contextShow context window
/compactSummarize & compress context
/clearClear conversation history
/exitExit the REPL

Workflow

/planDesign-first two-phase mode
/undoUndo last file changes
/snapshotGhost filesystem snapshot
/changesShow all changed files
/gitShow git status
/tasksShow running tasks
/jobsBackground job status

Providers & Models

/connectOAuth / API key setup
/modelsList available models
/healthProvider health check

Search & Code

/searchSearch codebase
/briefSummarize project
/templateInsert code template
/prPR list/view/diff/checks (gh)
/helpFull command reference

SDK Mode (NDJSON)

D.U.H. implements the Claude Agent SDK NDJSON streaming protocol. Any tool or script that expects claude as a binary will work with duh as a drop-in replacement.

bash

# NDJSON stream (Claude Agent SDK protocol)
duh --output stream-json -p "fix auth.py"

# Pipe into any tool expecting the SDK protocol
duh --output stream-json -p "build API" | jq '.type'

# The stub provider works offline — great for CI
DUH_STUB_PROVIDER=1 duh -p "hello"   # → "stub-ok"

ℹ

Offline testing: Set DUH_STUB_PROVIDER=1 to run with the deterministic stub provider. It returns canned responses without any network calls — perfect for CI pipelines and unit tests.

Next Steps

Security deep dive — understand the 3-layer model and configure scanners
Compare with alternatives — benchmark data and feature matrix
Browse the 54 ADRs — every architectural decision is documented
Security policy — how to report vulnerabilities
Open an issue — bugs, questions, feature requests

✓

DUH.md: Create a DUH.md file in your project root (like CLAUDE.md) to give D.U.H. project-specific instructions. It's loaded automatically at session start.