Deployment

Deployment

CodingDude is designed to be a single-user, single-command deployment on your own machine.

The shape of an install

<install dir>/            # the repository: src/, frontend/, tests/, docs/
  .venv/                  # uv-managed environment
  frontend/dist/          # built UI, served by the server
~/.codingdude/            # CODEDUDE_HOME: config, token, skills, DBs, traces, logs

Two things are code (src/, frontend/dist) and one is state (~/.codingdude/). Upgrades replace the first and must not touch the second.

First install

git clone https://github.com/cybersenses/codingdude.git
cd codingdude
uv sync
uv run codingdude serve

Open http://127.0.0.1:8765, configure a provider key, verify it, add a project.

Upgrading

1. Stop the server (or use codingdude restart --status to see what is running, then restart deliberately).
2. Pull the new code:

   git pull
   uv sync                 # resolves dependency changes

3. Rebuild the frontend if it changed:

   cd frontend && npm ci && npm run build && cd ..

   The server serves frontend/dist; a source change without a rebuild is the classic "my fix is not in the UI" bug, visible as a version mismatch in the StatusFooter.
4. Start it again and check /health — version, git_sha and started_at tell you exactly what is running.

Config changes never need a restart. They load per run. Only code changes do.

Windows notes

• bash resolves to Git Bash explicitly, never the WSL stub (which fails with "no installed distributions").
• Prompts travel by file, not argv, because of the 32k command-line limit.
• Timeouts kill the whole process tree (taskkill /T), so a grandchild process cannot hold pipes open and wedge a run.
• Use G:\path, not G:path — a drive-relative path is rejected on purpose.

Gates before you believe anything

gates.bat        :: uv run ruff check src tests tools, uv run mypy, uv run pytest -q

Frontend:

cd frontend && npm run lint && npm run test && npm run build

CI runs the same on windows-latest in three jobs: (1) lint, type-check and pytest; (2) the frontend — lint, vitest, build; (3) the scripted benchmark. Python tests and linters are venv-scoped: run them through uv run, not from a bare shell.

Operations

Task	Command
Is it running, and which build?	curl -s http://127.0.0.1:8765/health
Restart after code changes	uv run codingdude restart
Status only, change nothing	uv run codingdude restart --status
Logs	~/.codingdude/logs/server.log, worker-*.log
Trace of a session	~/.codingdude/traces/<session>.jsonl
Token	~/.codingdude/server-token

Backups

What matters is state, not code:

• ~/.codingdude/config.toml, server-token, mcp.json, skills/, DIRECTIVES.md
• the SQLite databases (sessions, planning, memory, usage)
• each project's ROADMAP.md, CONTEXT.md, AGENT.md

Copy the config home while the server is stopped. The SQLite store runs in WAL mode, so a hot copy without the -wal file is an inconsistent snapshot.

Publishing your wiki or docs

If you fork this project and want a GitHub wiki, remember that GitHub has no API and no gh command for wiki pages: the wiki repository (https://github.com/<owner>/<repo>.wiki.git) does not exist until someone creates the first page in the browser, and after that it is plain git. GitHub Pages, by contrast, is configured from the repository's own content.