Development Guide¶

This page describes how the Omarchy Tweaker development environment is set up, how the quality tooling is configured, and how to work on the project day to day.

Omarchy Tweaker is a terminal-first, Python 3.13+ toolkit for customizing and automating personal Omarchy (Arch Linux) installations. The repository is currently in the scaffolding stage: the CLI entry point and the full tooling pipeline exist, while feature modules are still being built.

Quick Start¶

For the impatient, a complete local setup looks like this:

git clone https://github.com/Armoghans-Organization/Omarchy-Tweaker.git
cd Omarchy-Tweaker
uv sync --all-groups
uv run pre-commit install --install-hooks
uv run poe check

If every task passes, the environment is ready.

Requirements¶

uv can install and manage the required Python interpreter, so a system Python 3.13 is not strictly necessary.

Optional Tools¶

These are not required for development but are used by the developer workspace helpers:

• Zellij — terminal multiplexer used by session.sh / session.kdl.
• gum — styled shell output used by session.sh.

Setup¶

1. Clone the repository¶

git clone https://github.com/Armoghans-Organization/Omarchy-Tweaker.git
cd Omarchy-Tweaker

2. Install dependencies¶

uv sync --all-groups

The dev group provides the full quality toolchain:

• ruff — linting and formatting.
• mypy — strict static typing.
• pytest, pytest-mock, pytest-cov, pytest-rich — testing and coverage.
• bandit — Python security analysis.
• codespell — spelling checks.
• pre-commit — Git hook management.
• poethepoet — task runner.

The docs group provides:

• zensical — documentation site generator.
• git-cliff — changelog and release-note generation.

3. Install Git hooks¶

uv run pre-commit install --install-hooks

The project installs three hook types by default (see .pre-commit-config.yaml):

• pre-commit — fast checks on staged files.
• commit-msg — Conventional Commits validation.
• pre-push — full-project type checking and test suite.

4. Verify the setup¶

uv run poe check

This runs linting, formatting checks, type checking, and the test suite.

5. Optional: launch the developer workspace¶

./session.sh

This creates a dedicated Zellij session using session.kdl.

Project Layout¶

Omarchy-Tweaker/
├── .github/
│   ├── templates/                  # Git Cliff changelog / release-note templates
│   └── workflows/                  # ci.yml, docs.yml, release.yml
├── docs/                           # Zensical documentation sources
│   ├── changelog.md                # GENERATED — do not edit by hand
│   ├── development.md              # This page
│   ├── index.md
│   ├── release-notes.md            # GENERATED — do not edit by hand
│   ├── overrides/                  # Theme overrides
│   ├── stylesheets/                # Custom CSS
│   ├── favicons/ · images/         # Static assets
├── src/omarchy_tweaker/
│   └── __init__.py                 # CLI entry point (currently a welcome message)
├── tests/
│   ├── __init__.py
│   └── test_main.py                # CLI smoke test
├── .gitignore
├── .pre-commit-config.yaml         # Git hook definitions
├── .python-version                 # Pinned interpreter (3.13)
├── AGENTS.md                       # AI agent development guidelines
├── cliff.toml                      # Git Cliff configuration
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── LICENSE
├── pyproject.toml                  # Project metadata, tooling, and Poe tasks
├── Readme.md
├── SECURITY.md
├── session.kdl / session.sh        # Optional Zellij developer workspace
├── SUPPORT.md
├── uv.lock                         # Locked dependency graph
└── zensical.toml                   # Documentation site configuration

Generated Artifacts¶

The following are produced by tasks and must never be committed:

• dist/, build/ — package builds.
• site/ — compiled documentation.
• .cache/, .pytest_cache/, .mypy_cache/, .ruff_cache/.
• .coverage, htmlcov/.
• bandit-report.json.
• docs/changelog.md, docs/release-notes.md — regenerated from Git history.

When feature modules are added, they are expected to follow the target structure under src/omarchy_tweaker/ (for example cli/, core/, and models/). That structure does not exist yet.

Toolchain and Configuration¶

All tooling is configured in pyproject.toml.

Ruff — Linting and Formatting¶

Do not add inline suppressions merely to silence a warning. If a suppression is genuinely required, it must have a clear justification.

Mypy — Strict Typing¶

All public functions, methods, and modules should carry complete type annotations. Do not weaken strict mode to make code pass; resolve the underlying typing issue instead.

Bandit — Security Analysis¶

Pytest and Coverage¶

External commands, package-manager calls, privileged operations, filesystem writes, and service changes must be mocked. Tests must never modify the host system.

Poe the Poet — Task Runner¶

Tasks are defined under [tool.poe.tasks] in pyproject.toml.

Task Runner¶

Run any task with uv run poe <task>.

Linting¶

Formatting¶

Type Checking¶

Testing and Coverage¶

Security¶

Changelog and Release Notes¶

Documentation¶

Building and Cleanup¶

Combined Checks¶

Git Hooks (pre-commit)¶

The repository uses pre-commit to enforce quality gates before code reaches the remote. Local hooks invoke tools through uv run --locked so the environment matches the lockfile exactly.

Hook Stages¶

Hook Categories¶

Most hooks are configured with verbose: true, so the terminal shows exactly which hook is running, which files it touched, and the full tool output.

Common Commands¶

To skip a specific hook for one run:

SKIP=codespell uv run pre-commit run --all-files

Daily Development Workflow¶

A typical change follows this loop:

1. Create a branch (only with explicit authorization for AI agents — see AGENTS.md).
2. Make a focused change with tests and documentation updates.
3. Run the fast feedback loop:

uv run poe lint-fix
uv run poe format
uv run poe test

1. Run the full gate before committing:

uv run poe check

1. Commit using a Conventional Commit message.
2. Push (the pre-push hooks run Mypy and Pytest automatically).

For documentation, packaging, or pipeline changes, run the full pipeline instead:

uv run poe ci

Testing¶

Tests live under tests/ and use Pytest with Pytest-Mock and Pytest-Cov.

Running Tests¶

uv run poe test
uv run poe coverage

Run a single test or file directly:

uv run pytest tests/test_main.py -v
uv run pytest tests/test_main.py::test_main_prints_welcome_message -v
uv run pytest -k "welcome" -v

Guidelines¶

• Test public behavior, invalid input, error conditions, and edge cases.
• Name tests descriptively, for example test_install_package_handles_command_failure.
• Use pytest-mock (mocker) to isolate external dependencies.
• Use tmp_path for filesystem work instead of touching real user directories.
• Never install, remove, or modify real packages or system services during tests.
• Treat coverage as a signal, not a target: prioritize critical paths and failure handling over an arbitrary percentage.

Current Coverage¶

The suite currently contains a single CLI smoke test (tests/test_main.py). External system operations must be mocked as feature modules are introduced.

Commit Message Conventions¶

Commit messages are validated by the conventional-pre-commit hook in strict mode.

Format:

<type>(optional-scope): <description>

Allowed types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, and revert. The header is limited to 100 characters.

Examples:

feat: add package management commands
fix: handle missing configuration files
refactor(core): separate system operations from the CLI
docs: improve installation documentation
test: add package manager tests
chore: update development dependencies

Indicator a breaking change with ! after the type or scope, and/or a BREAKING CHANGE: footer:

feat(cli)!: rename the bootstrap command

Keep messages descriptive enough for git-cliff to build meaningful changelogs.

Documentation¶

Documentation is built with Zensical and configured in zensical.toml. The site navigation currently exposes:

• Home → index.md
• Development → development.md
• Changelog → changelog.md (generated)
• Release Notes → release-notes.md (generated)

Local Preview¶

uv run poe docs-serve

This starts a live-reload server. To build the site without serving it:

uv run poe docs-build

docs-build regenerates the changelog and release notes before compiling the site with --clean --strict, so broken links and invalid content fail the build.

Editing Documentation¶

• Source pages live in docs/.
• Theme overrides live in docs/overrides/.
• Custom styling lives in docs/stylesheets/extra.css.
• Never edit docs/changelog.md or docs/release-notes.md by hand; they are generated from Git history.
• Keep documentation accurate. Do not document features that are not implemented.

Deployment¶

The Documentation workflow (.github/workflows/docs.yml) builds and deploys the site to GitHub Pages on pushes to main and on v* tags. It uses uv run --frozen --group docs to guarantee a reproducible build.

CI/CD Pipeline¶

ci.yml — Continuous Integration¶

Triggered on pushes and pull requests to main, and manually via workflow_dispatch.

docs.yml — Documentation Deployment¶

Pushes to main or v* tags build the site and publish it to GitHub Pages.

release.yml — Release Automation¶

Triggered by tags matching v*. It:

1. Verifies that the Git tag matches the pyproject.toml version.
2. Builds the sdist and wheel.
3. Validates artifacts with twine check.
4. Generates RELEASE_NOTES.md, CHANGELOG.md, and the documentation copies with git-cliff.
5. Creates or updates the GitHub Release and uploads the artifacts.

Release Process¶

The project follows Semantic Versioning (MAJOR.MINOR.PATCH).

1. Update version in pyproject.toml.
2. Regenerate and review the changelog and release notes:

uv run poe changelog-preview
uv run poe release-notes-preview

1. Run the full pipeline:

uv run poe ci

1. Commit and push the version bump.
2. Create and push a tag that matches the version exactly:

git tag v0.1.0
git push origin v0.1.0

The release.yml workflow rejects a tag whose version does not match pyproject.toml.

Troubleshooting¶

uv.lock is out of date¶

Symptom: uv run --locked fails, or pre-commit hooks error while resolving dependencies.

uv lock
uv sync --all-groups

Commit the updated uv.lock when dependency changes require it. Do not edit the lockfile manually.

A pre-commit hook fails¶

uv run pre-commit run <hook-id> --all-files

Inspect the output, fix the issue, re-stage, and commit again. Use SKIP=<hook-id> only when a hook is genuinely not applicable.

Hooks report (no files to check)Skipped¶

Expected for validators whose file types are absent (for example JSON or XML). No action is needed.

Mypy strict errors appear during push¶

The pre-push stage runs full-project Mypy. Fix the annotations rather than adding # type: ignore. Verify locally with uv run poe typecheck.

Bandit generates bandit-report.json¶

That file is a generated artifact and is excluded from hooks and Git. Remove it with uv run poe clean or delete it manually.

Documentation build fails on missing generated files¶

Run uv run poe docs-generate (or uv run poe docs-build, which does it automatically) before building.

Contribution Checklist¶

Before opening a pull request, confirm that:

• The change is focused and does not include unrelated refactoring.
• Tests cover new behavior and failure paths.
• Documentation is updated where behavior changed.
• uv run poe check passes.
• uv run poe ci passes for packaging, docs, or pipeline changes.
• Commit messages follow Conventional Commits.
• No generated artifacts, secrets, or virtual environments are staged.

Additional contribution expectations are described in CONTRIBUTING.md and AGENTS.md.

Command Cheat Sheet¶