Keep this file short. It is an entry point, not a second design document.
- New: read Orientation (objectives, module layers, one turn's shape) and skim Common pitfalls — changes that look like cleanups and are not.
- Read design/DESIGN.md before changing cross-cutting behavior or module ownership; follow the nearest existing pattern before introducing a new abstraction or dependency.
- For main/subagent state ownership, read State ownership.
wizolt/agent/lifecycle.py: application session creation/resume, feature assembly, background task ownership and resource shutdown.Sessionstores state; it does not assemble features.wizolt/agent/engine.py: the agent turn loop composing context, model, and tools;wizolt/agent/hooks.pyis the one presentation seam (UiHooks) the agent shares with them.wizolt/agent/context.py,wizolt/model/,wizolt/agent/runner.py: context projection/compaction, provider request protocols (model/client.pywith the per-API adapters beside it), and the tool execution lifecycle.wizolt/ui/cli/update.py,wizolt/ui/cli/hints.py: the background version check and quick hints.wizolt/session/: durable semantic state (__init__.py) and snapshot persistence (store.py);store.pynever imports the package at module scope.wizolt/tools/,wizolt/image.py,wizolt/mcp/,wizolt/skill/: vertical features;tools/splits built-ins by capability, registry in__init__.py.skill/splits reading (skillfile), discovery, trust, invocation, and what the model was told (listing).wizolt/shellhooks.py: supported command-hook events, orchestrated by the runner, engine and compactor.wizolt/utils/: dependency-free helpers (process.ShellCommand,workspace.Workspace, parsers).wizolt/config.py,wizolt/providers/: config-file settings, the model capability catalog (providers/catalog.py), and evidence-backed compatibility policy (providers/compat.py).wizolt/ui/cli/,wizolt/ui/tui/,wizolt/ui/render.py: commands (cli/commands.py,cli/modals.py, agent selection incli/agents.py, the/statussnapshot and tabs incli/status.py,/themeincli/appearance.pywith its bar-format panel incli/formats.py), resume replay (cli/resume.py), TUI runtime (cli/runtime.py), view fragments (cli/view.py), interaction, and presentation state (cli/presentation.py).Viewand replay receive bounded dependencies rather than aCommandLoophandle.tests/: behavior-oriented tests grouped by subsystem and boundary.
- Tests: run targeted tests while iterating and
uv run pytestbefore completing behavior changes. That run excludes real-multiplexer acceptance tests (they need a terminal and real time); runuv run pytest -m tmuxanduv run pytest -m zellijwhen a change touches the terminal projection. The Zellij suite requires 0.45.1 (the CI pin) or a compatible later version. - Quality: run
uv run ruff check wizolt tests,uv run ruff format --check wizolt, anduv run pyright. - Docs: on user-facing doc changes, update the English source and build
html(make -C docs html). - Docs standard:
docs/is written for users, not for the people who changed the code.- Say what the reader gets and what it costs them. Leave out how it is implemented, why an alternative was rejected, and the taxonomy of ways it can fail.
- Prefer a number to a mechanism: "about eight recent messages survive" beats a paragraph on how the window is bounded.
- Add a trade-off only when the reader has to choose. Name the setting or the
/statusrow that answers it, and stop. - Rewriting a paragraph is usually better than appending one. A behavior change means the old sentence is wrong, not incomplete.
- Reasoning that is worth keeping but not worth showing a user goes in a code comment or a commit message.
- A
term-shotis a screenshot in HTML: when the colors or rows it depicts change, it is stale and has to be redrawn. Keep every<span>closed.
- Changelog: record notable changes under
Unreleased, including user-facing behavior, internal refactors, dependencies, tests/CI, and documentation or maintenance work. Performance claims need before/after measurements with the workload, environment and comparison revisions; link the recorded results and include meaningful trade-offs or regressions. - Release (only when requested): bump
pyproject.tomlandwizolt/base.py, move Unreleased entries under the dated version, run tests, quality checks, the doc build, anduv build, commitRelease X.Y.Z, and create the lightweight tagvX.Y.Z. Do not push or publish. - Performance baseline: branch reviews save comparisons under
benchmarks/results/, never replace the reference. After merging tomaster/main, rerun against the previous baseline in a comparable environment and update the reference before release. Investigate significant regressions first; record justified trade-offs instead of hiding them in a new baseline.
- Make the smallest cohesive change; no pass-through wrappers or speculative specialization.
- Prefer black-box tests at the narrowest stable public boundary; bug fixes cover the reproduced
failure, intended result, and important rejection paths (see
design/DESIGN.mdfor the full policy). - Mock external uncertainty, not the core behavior under test; keep tests deterministic and fast.
- Keep
CHANGELOG.mdaligned with notable project changes, including internal work. - Never rebuild or re-sync the project
.venv(nouv run --python X/uv sync --python Xwith a different interpreter): the developer's ownwizoltprocess runs out of it, and swapping it mid-session deletes modules under that process and crashes it. For cross-version testing, pointUV_PROJECT_ENVIRONMENTat a throwaway directory instead.