Skip to content

Developing a py-worker

Generation copied .env.example to .env, created .venv, installed requirements.txt into it, and made the first commit.

  1. Set HOME_PATH in .env to the project’s absolute path (pwd in the project directory).

  2. Point it at the API’s services: DB_* and REDIS_* exactly as the API has them. With the API’s yarn dc:up running, the defaults match.

  3. Model the tables you need under models/, mirroring the API’s Prisma schema, using Base and the mixins in models/mixins.py.

  4. Run it:

    Terminal window
    source .venv/bin/activate
    python worker.py
  5. Send it a job on the hello queue from the API, and watch logs/workers/hello.log.

The project’s own task skills carry the full steps for each of these.

  1. Create workers/<name>/process.py with an async def <name>_process(job, job_token).
  2. Start it in worker.py: create_worker("<queue>", <name>_process), and add await <worker>.close() to the cleanup block.
  3. Produce to the same queue name from the API.

With --with temporal, the worker connects to localhost:7233 (the dev server in the API’s compose.yml) and polls task queue python:

Terminal window
temporal workflow execute --type example --task-queue python \
--workflow-id try-py --input '{"name":"python"}'

Add a workflow class to temporal/workflows.py and an activity to temporal/activities.py, then register both in the lists in utils/temporal.py. Workflow code must be deterministic: use workflow.now() and workflow.random(), never I/O.

requirements.txt pins every package. Add one with .venv/bin/pip install <pkg> and pin its version in requirements.txt; the Docker image installs exactly that file.

The project ships its own guidance for Claude Code, generated with it and stripped to the features it has:

  • CLAUDE.md at the root: the worker’s commands, layout and rules (models mirror the API’s tables by hand, queue names match the producer, its own Temporal task queue). Claude Code loads it in every session in the project.
  • Task skills in .claude/skills/<name>/SKILL.md: step-by-step recipes that point at the template’s own example code. Ask for the task in plain words (“add an endpoint for invoices”) and the matching skill loads.
SkillShips withWhat it does
add-workerEvery project

Add a BullMQ job handler to this Python worker for a queue the Node API produces to — the handler, its registration and its shutdown.

add-modeldatabase

Add a SQLAlchemy model to this Python worker that mirrors one of the API's Prisma tables, so a job handler can read or write it.

add-workflowtemporal

Add a Temporal workflow and its activities to this Python worker — durable, multi-step work in Python that the API starts by name.

A skill that belongs to a feature arrives with it: adding the feature later with stack add brings its skill and its CLAUDE.md sections too. Both are yours to edit as the project grows its own conventions. See Building with Claude Code for the whole workflow, from a design to a backlog.