Concepts

Concepts

CodingDude's vocabulary is deliberately narrow, because each term maps to a mechanism. Using the wrong word usually means misunderstanding the machinery. The canonical glossary is CONTEXT.md.

Session

A continuous conversation between you and the agent within one project, persisted and resumable after close. A session can contain many runs.

Avoid: chat, conversation.

Workdir

The project directory a session operates in. Every file tool resolves paths through a containment check and refuses anything outside it — including the editor, the render endpoints and the file API.

Avoid: workspace, project root.

Run

One execution of the agent loop, spawned as its own worker subprocess. Runs have a status (running, finished, failed, cancelled, interrupted), their own trace, usage record and terminal event.

Approval

Explicit consent before the agent executes a gated action. Three tiers:

Tier	Behaviour
automatic	safe, read-mostly actions (read files, grep, status, plan)
pattern-approvable	gates once, then Approve pattern covers matching commands for the session
always-gated	pushes, PR creation, installs, destructive filesystem operations — never pattern-unlockable

Pattern approval is session-scoped by design; it is not a persistent allowlist. Headless runs abort on a gate (exit code 2) unless --yolo.

Avoid: permission, confirmation.

Headless run

A non-interactive single-task execution with no UI:

uv run codingdude run "fix the failing test in tests/test_auth.py" --budget 2.00

Exit codes: 0 finished · 1 failed · 2 a gated action needed approval · 3 budget exceeded.

Delegation

A sub-agent spawned by the main agent for a bounded task, with its own restricted toolset and its own spend slice. Delegations are read-only by default, never hold approval authority, and report back to the parent.

Avoid: dispatch, handoff.

Budget cap

A per-session spending limit. Exceeding it hard-stops the run and is not bypassed by --yolo. Distinct from the per-call ceilings — the budget cap reads the session's usage ledger.

Memory entry

A durable fact banked across sessions, scoped globally or to a workdir, recalled by relevance. Separate from project notes, which are read on every run in that project, and from directives, which are always injected.

Project context

AGENT.md at a workdir root: durable user-authored instructions, layered on top of the global DIRECTIVES.md.

Ticket, roadmap item, PRD, tech design

Four different planning objects with four different lifecycles — see Planning. They are not synonyms, and the difference between delivered and sunset is the difference between "shipped and in force" and "shipped and retired".

Trace

Two unrelated things share the word:

• Session trace — a JSONL file per session (~/.codingdude/traces/<session>.jsonl) that the Trace panel replays and evidence checks read. Controlled by [trace].
• OTLP trace — spans exported to a local collector for timeline analysis. Controlled by [telemetry], off by default.

See Observability.

Claim / evidence

The agent's rule: never claim work is complete without running the verification command in that session and reading its output. Plan steps carry structured evidence — command, exit code, and the output line that proves the step.