Agent Instructions

Project

ucode is a Python CLI that configures and launches coding agents through Databricks AI Gateway.

The package code lives in src/ucode/. Tests live in tests/.

Run the full test suite with uv run pytest.
Run focused tests with uv run pytest tests/<file>.py.
Run e2e tests with UCODE_TEST_WORKSPACE=<db_workspace_url> uv run pytest tests/test_e2e.py -v.
Run lint with uv run ruff check ..
Run the CLI from the current checkout with uv run ucode ....
Reinstall the local checkout as the ucode tool with uv tool install --reinstall ..

Use Python 3.12+.
Keep changes scoped to the requested behavior.
Follow the existing module boundaries: CLI orchestration in cli.py, agent-specific behavior in agents/<name>.py, shared agent dispatch in agents/__init__.py, Databricks calls in databricks.py, and presentation helpers in ui.py.
Prefer existing helpers for config file writes, state persistence, UI messages, and Databricks authentication.
Add or update focused tests for behavior changes.
Do not modify generated or lock files unless the dependency graph intentionally changes.

Keep user-facing CLI errors actionable.
Use warnings for recoverable setup problems and errors for launch/runtime blockers.
Preserve existing Rich UI conventions, including print_warning, print_err, print_success, print_section, and spinner.
Avoid broad refactors while fixing a narrow bug.