Getting Started

Getting Started

From nothing to a completed agent run. Everything works on Windows (the primary platform); Linux and macOS use the same commands.

1. Prerequisites

• Python 3.12+
• uv — dependency and environment manager
• Git — the agent's diff, checkpoint and review machinery is git-based
• Optionally Node.js — only to rebuild the web UI from source
• Optionally the GitHub CLI (gh) — for issue mirroring, PR tools and CI tools

2. Install and start

uv sync                  # create the venv and install CodingDude
uv run codingdude serve  # server + web UI, default port 8765

The server prints its URL and token:

codingdude server on http://127.0.0.1:8765 token=xxxx

It binds 127.0.0.1 only — it is not reachable from the network.

First start creates ~/.codingdude/ (override the location with the CODEDUDE_HOME environment variable):

File	Purpose
config.toml	model lineup, providers, ceilings, telemetry
server-token	the login token, stable across restarts
mcp.json	MCP server configuration
skills/, DIRECTIVES.md	procedural skills and always-on rules, seeded on first boot
SQLite DBs, traces/, logs/, prompts/, uploads/	state, trace files, logs

3. Log in

Open http://127.0.0.1:8765. A local same-origin page logs in automatically (POST /auth/local attests loopback + same-origin, then issues a session cookie). Any non-browser client authenticates with the token from ~/.codingdude/server-token:

curl -H "Authorization: Bearer $(cat ~/.codingdude/server-token)" \
     http://127.0.0.1:8765/api/planning

GET /health is deliberately unauthenticated — it reports version, git_sha and started_at, which is how you detect a stale server.

4. Configure a model

Model names are always provider:model. Open the Config panel and either store a key for a built-in provider or add a custom OpenAI-compatible one, then press Verify keys — one minimal request per provider tells you the key works before you spend a run discovering it does not.

The default lineup:

[models]
main = "deepseek:deepseek-v4-pro"
subagent = "deepseek:deepseek-v4-flash"
fallback = "zai:glm-5.3"

Keys come from the environment (DEEPSEEK_API_KEY, ZAI_API_KEY, or <NAME>_API_KEY for custom providers) or from config.toml — the environment wins. Config changes apply from the next run; no restart needed. Worked examples for DeepSeek, the Z.AI GLM coding plan, OpenRouter and local models (Ollama / LM Studio) are in Configuration.

5. Add a project

Set the Workdir field to your project folder, click + New project, name it, save. Adding a project scaffolds what the agent expects and builds the codegraph symbol index:

• ROADMAP.md — the canonical planning store
• CONTEXT.md — domain glossary (AGENT.md carries your project rules)
• reference/ — checklists and manuals
• .codegraph/ — the tree-sitter symbol index

Any failure is reported in the UI; nothing is silently skipped.

6. Run your first task

Click + New session, type a prompt, send. A good first task is small and verifiable:

Add a --verbose flag to scripts/report.py that prints each step it takes. Run the script before and after to show the difference.

What you will see:

1. A plan appears first for non-trivial work, for you to approve.
2. Approval cards before anything risky — shell commands, pushes, installs, destructive file operations. Choose Approve once, Approve pattern (the same command for the rest of the session) or Deny.
3. ask_user forms may appear mid-run; answer inline and the run continues.
4. A terminal event — RUN_FINISHED, RUN_ERROR, RUN_CANCELLED — and a report with evidence: the gate output it ran, not a claim.

Per-run composer controls: model slot, image attachment, suggest (agent edits become revertable proposals instead of direct writes), a review checklist, fix until green (loop on test failures after the task), and yolo (auto-approve every gated action for this session — deliberately loud, because it removes your hands from the wheel).

7. Review what happened

• Review changes → opens the Diff panel: working tree vs HEAD, a symbol-level change summary, and an impact graph.
• path:line citations in chat are clickable and open the file at those lines — in fresh answers and replayed history alike.
• Every edit is checkpointed; the Trace panel lists checkpoints with a rewind button.
• Before a push, the agent must record a two-axis review of the exact diff. Fixing a finding voids the record, by design.

8. Stop and restart

Action	How
Interrupt a run	Stop in the chat (the worker process is terminated; the run records as interrupted)
Change config	Nothing to restart — it loads per run
Change CodingDude's own code	uv run codingdude restart
Change the frontend	rebuild frontend/dist, then hard-refresh the browser
Browser dropped mid-run	reconnect resumes the live run; a finished run replays from history

Next: Concepts for the vocabulary, or Web UI for what is on screen.