Home

CodingDude Wiki

CodingDude is a personal, single-user coding agent. It plans, designs, implements, reviews and ships software-engineering work inside your own repository — built on pydantic-ai, driven from a loopback web UI, with tiered approvals for anything risky.

Current release: 0.4.0 · Licence: AGPL-3.0-or-later · © 2025 Cyberflex

uv sync                  # install
uv run codingdude serve  # web UI on http://127.0.0.1:8765
uv run codingdude run "add a --verbose flag to scripts/report.py"

What it does

Capability	In one line
Agentic engine	pydantic-ai agent loop with model failover, per-run worker processes, and context that compacts instead of dying
Tiered approvals	safe work runs; pushes, installs and destructive operations stop at an approval card
Code tools	AST-aware symbol edits, call graphs, impact analysis, dead code, mutation testing, benchmarks, coverage
Planning	PRDs → tech designs → roadmap items → tracer-bullet tickets, each with its own lifecycle and per-step evidence
Review gate	a push is refused unless a recorded two-axis review covers the exact diff being published
Spend control	hard max_cost_usd / max_total_tokens ceilings checked before each request, plus a session budget cap
Observability	JSONL session traces, and optional OTLP export to a collector you run yourself
Delegation	parallel sub-agents staffed by cognitive function, with their own spend slices and trace spans
Memory	durable facts, a solved-problem bank, project notes, and ADR-style design decisions across sessions
Skills	66 seeded procedural skills, loaded on demand rather than held in context

Start here

• Getting Started — install, configure a model, run your first task.
• Concepts — the vocabulary this project uses precisely (session, workdir, approval, delegation, budget cap).
• Web UI — every panel, and what it is for.
• Planning — the four lifecycles and where each one is stored.
• Review Gate — why publishing requires a recorded review.

Understand the system

• Architecture — server / worker / engine, modules, data model.
• Agents and Tools — toolsets, approvals, failover, delegation, long runs.
• Spend and Context — the three ceilings, the ledger, compaction, caching.
• Observability — traces, OTLP, cost views.
• Security — the posture, and its honest limits.

Operate and contribute

• Configuration · CLI · Deployment · Troubleshooting
• Skills and Directives — teach the agent new procedures and rules.
• Contributing — gates, review flow, living documentation.
• Release Notes — what changed, most recent first.

Where things live

Path	Contents
~/.codingdude/ (CODEDUDE_HOME)	config.toml, server-token, mcp.json, skills/, DIRECTIVES.md, SQLite DBs, traces/, logs/
your project	your code, ROADMAP.md, CONTEXT.md, AGENT.md, .codegraph/, optional .codingdude/mcp.json and .codingdude.toml

The one rule worth internalising

Evidence before claims. The agent must run the gate and read its output before saying work is done — and the review gate makes publishing require a deliberate, axis-labelled review of the exact diff. Nothing here asks you to trust a summary.

---

This wiki is a navigable summary. The repository is canonical: README · docs/USER-MANUAL.md · docs/TECHNICAL-DESIGN-MANUAL.md.