duh-cli 0.7.0

One harness. Any model. Your machine.

Website | Comparisons | Getting Started | Security

$ duh -p "fix the bug in auth.py"
⠋ Thinking...
I'll read the file first to understand the issue.

⠸ Running Read(file="auth.py")
Found the bug: token validation checks `expires_at < now` but should be `<=` —
tokens expiring at exactly the current second are incorrectly rejected.

⠹ Running Edit(file="auth.py", old_string="expires_at < now", new_string="expires_at <= now")
✓ Applied edit to auth.py (line 42).

⠼ Running Bash(command="python -m pytest tests/test_auth.py -q")
...........
11 passed in 0.43s

Done in 3 turns.

A universal, open-source AI coding agent. One harness, any provider — Anthropic Claude, OpenAI API, ChatGPT Plus/Pro subscription (Codex-family models), local Ollama, or a deterministic stub for tests. Drop-in compatible with the Claude Agent SDK NDJSON protocol, so it can replace claude wherever that binary is expected.

Install

# From source (recommended during alpha)
git clone https://github.com/nikhilvallishayee/duh
cd duh
python3.12 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# From PyPI
pip install duh-cli                    # core: Anthropic + Ollama + httpx
pip install 'duh-cli[openai]'          # + OpenAI API key provider
pip install 'duh-cli[rich]'            # + Rich TUI rendering
pip install 'duh-cli[bridge]'          # + WebSocket remote bridge
pip install 'duh-cli[attachments]'     # + PDF attachment support (pdfplumber)
pip install 'duh-cli[security]'        # + vulnerability monitoring (ruff, pip-audit, detect-secrets, cyclonedx)
pip install 'duh-cli[all]'             # everything above

Quick start

duh -p "fix the bug in auth.py"                                  # print mode, auto-detect provider
duh --provider anthropic --model claude-sonnet-4-6 -p "hello"    # force Claude
duh --provider openai --model gpt-5.2-codex -p "refactor db"     # ChatGPT Plus/Pro Codex (OAuth)
duh                                                              # interactive REPL
duh doctor                                                       # diagnostics + health checks
duh security scan                                                # vulnerability scan (SARIF output)
duh security init --non-interactive                              # set up security policy
duh security doctor                                              # scanner health check

Providers

Provider and model auto-detect: give --model gpt-5.2-codex and D.U.H. will route to the ChatGPT/Codex Responses endpoint if OAuth exists; otherwise it falls back to the standard OpenAI Chat Completions adapter with your API key.

Slash commands (REPL)

/help /model /connect /models /cost /status /context /changes /git /tasks /brief /search /template /plan /pr /undo /jobs /health /errors /clear /compact /snapshot /exit

Run /help in the REPL for the full description of each command. Highlights: /connect openai runs the ChatGPT OAuth flow; /snapshot takes a ghost filesystem snapshot you can apply or discard; /plan switches to design-first two-phase execution; /pr list|view|diff|checks integrates with gh.

Built-in tools

Read, Write, Edit, MultiEdit, Bash, Glob, Grep, Skill, ToolSearch, WebFetch, WebSearch, Task, EnterWorktree, ExitWorktree, NotebookEdit, TestImpact, MemoryStore, MemoryRecall, HTTP, Docker, Database, GitHub, TodoWrite, AskUserQuestion, plus LSP (deferred, loaded via ToolSearch).

Security

D.U.H. ships a three-layer pluggable security module (ADR-053 + ADR-054) that addresses every published agent RCE in the 2024-2026 CVE corpus:

Layer 1 — Vulnerability monitoring (duh security CLI):

• 13 scanners across 3 tiers: Minimal (ruff-sec, pip-audit, detect-secrets, cyclonedx-sbom + 5 D.U.H.-specific scanners), Extended (semgrep, osv-scanner, gitleaks, bandit), Paranoid (GitHub Actions CodeQL, Scorecard, Dependabot)
• D.U.H.-specific scanners detect project-file RCE (CVE-2025-59536), MCP tool poisoning (CVE-2025-54136), sandbox bypass (CVE-2025-59532), command injection (CVE-2026-35022), and OAuth hardening violations
• SARIF output for GitHub Code Scanning, delta mode (--baseline), exception management with expiry
• duh security init wizard, duh security doctor, pre-push git hook installer

Layer 2 — Runtime hardening (ADR-054):

• Taint propagation: UntrustedStr subclass tags every string with its origin (user_input, model_output, tool_output, file_content, mcp_output, network) and propagates through all string operations
• Confirmation tokens: HMAC-bound tokens prevent model-originated tainted strings from reaching dangerous tools (Bash, Write, Edit) without explicit user confirmation
• Lethal trifecta check: Sessions with simultaneous read-private + read-untrusted + network-egress capabilities require explicit acknowledgement (--i-understand-the-lethal-trifecta)
• MCP Unicode normalization: NFKC normalization + rejection of zero-width, bidi, tag, and variation selector characters in MCP tool descriptions (GlassWorm defense)
• Per-hook filesystem namespacing: Each hook gets a private temp directory; cross-hook file access is blocked
• PEP 578 audit hook bridge: sys.addaudithook telemetry on open, subprocess.Popen, socket.connect, exec, import pickle — sub-500ns fast path
• Signed plugin manifests: TOFU trust store with sigstore-ready verification and revocation
• Provider differential fuzzer: Hypothesis property tests ensure all 5 adapters parse tool_use identically

Layer 3 — Sandboxing: Shell commands and MCP stdio servers are wrapped by the host OS sandbox: macOS Seatbelt (sandbox-exec profiles), Linux Landlock (syscall-level filesystem access control), and a network policy layer that blocks outbound traffic unless explicitly allowed (see duh/adapters/sandbox/). Approval behaviour is controlled with --approval-mode suggest|auto-edit|full-auto (reads only / reads+writes / everything), with --dangerously-skip-permissions as the hard bypass.

MCP (Model Context Protocol)

MCP servers connect via four transports: stdio (via the mcp SDK), SSE, streamable HTTP, and WebSocket. Configure with --mcp-config <file-or-json>. See ADR-010 and ADR-040.

Hooks

29 lifecycle events (6 original + 22 extended + AUDIT) including PreToolUse, PostToolUse, PostToolUseFailure, SessionStart, SessionEnd, UserPromptSubmit, PermissionRequest, PreCompact, PostCompact, FileChanged, SubagentStart, Elicitation, and more. Hooks support glob matchers, blocking semantics (a hook can refuse a tool call or rewrite its input), and both shell-command and Python-callable handlers. See ADR-013, ADR-036, ADR-044, ADR-045.

Tests and coverage

5665 tests, 100% line coverage, ~55s on a laptop. Includes 330+ security-specific tests (unit, integration, property-based), CVE replay fixtures, and performance regression gates. CI runs on GitHub Actions with a --cov-fail-under=85 floor (current actual: 100%).

.venv/bin/python -m pytest tests/                         # full suite
.venv/bin/python -m pytest tests/ --cov=duh               # with coverage
DUH_STUB_PROVIDER=1 .venv/bin/python -m pytest tests/     # force stub provider

Selected ADRs

Full list: docs/adrs/ (54 ADRs).

Development

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

# Run tests
.venv/bin/python -m pytest tests/

# Run with coverage
.venv/bin/python -m pytest tests/ --cov=duh --cov-report=term

# Offline / deterministic mode (no real provider calls)
export DUH_STUB_PROVIDER=1
duh -p "hello"     # → "stub-ok"

Source layout:

duh/
  kernel/        # agentic loop, sessions, tasks, plan mode, undo, skills, memory
  ports/         # abstract provider / tool / approver interfaces
  adapters/      # anthropic, openai, openai_chatgpt, ollama, stub, mcp_executor, mcp_transports
    sandbox/     # seatbelt, landlock, network policy
  auth/          # credential store + OpenAI ChatGPT PKCE OAuth
  providers/     # provider registry + model resolution
  tools/         # 25+ built-in tools (see list above)
  security/      # vulnerability monitoring, policy resolver, scanner plugins, CI templates
    scanners/    # 13 scanners (4 minimal, 5 D.U.H.-custom, 4 extended)
  cli/           # parser, main, runner, repl, sdk_runner, ndjson
  bridge/        # optional WebSocket remote bridge
  ui/            # Rich TUI rendering
  plugins/       # plugin loader, signed manifests, TOFU trust store
  hooks.py       # 29-event hook system with per-hook FS namespacing

License

Apache 2.0 — see LICENSE.