Microtasks

A platform for serving and completing microtasks while waiting for claude code to finish thinking.

When entering a prompt, a claude code hook is called to procure a micro task for the user to complete, or dismiss.

This is an example of the typing test task:

Prerequisites

• Python 3.14
• uv (package manager)
• PostgreSQL 16

Setup

1. Set up environment:

cp .env.template .env.local

Edit .env.local with your local settings. The defaults work with the Docker PostgreSQL setup.

2. Install dependencies:

uv sync

3. Start PostgreSQL: Make sure postgres is running!

4. Run database migrations:

uv run alembic upgrade head

5. Start the dev server:

uv run uvicorn app.main:app --reload

Installing the Claude Code Hook

Microtasks uses a Claude Code hook to open a small task window each time you submit a prompt. The server must be running for tasks to appear.

To install the hook in your project:

uv run microtasks install

This adds a UserPromptSubmit hook to .claude/settings.local.json. When you submit a prompt in Claude Code, the hook fetches the next available task from the server and opens it in a floating window.

To temporarily disable prompts without removing the hook:

uv run microtasks disable
uv run microtasks enable

Or via a skill directly in claude:

/microtask-toggle on
/microtask-toggle off

To fully remove the hook:

uv run microtasks uninstall

You can manage which tasks are enabled via the admin panel at http://localhost:8000/admin.

Development

• API docs: http://localhost:8000/docs
• Admin panel: http://localhost:8000/admin
• Task dev harness: http://localhost:8000/dev/

Task dev harness

The task dev harness at /dev/ lets you preview and test individual task UIs in the browser. It lists all registered tasks and renders each one in an iframe at its configured dimensions, simulating how the task appears in the pywebview popup. Each preview generates a temporary task ID so completion callbacks work end-to-end.

To preview a specific task directly:

http://localhost:8000/dev/{task-slug}

Run tests

uv run pytest

Run all checks (ruff, mypy, pytest)

./scripts/check.sh

Auto-fix lint and formatting

./scripts/fix.sh

ruff check finds lint errors (some auto-fixable with --fix). ruff format handles code formatting. The scripts above combine these for convenience.

Individual tools

uv run ruff check src/ tests/    # lint
uv run ruff format src/ tests/   # format
uv run mypy src/                 # type check

Database migrations

# Create a new migration
uv run alembic revision --autogenerate -m "description"

# Apply migrations
uv run alembic upgrade head

# Rollback one migration
uv run alembic downgrade -1

Integrations

GitHub Project Board (Issue Sorter)

The issue-sorter task pulls issues from a GitHub repo and tracks ELO ratings on a GitHub Projects v2 board. Issues must be on a project board because ELO is stored as a custom number field — only board items can have custom fields.

This requires the GitHub CLI (gh) to be installed and authenticated with the project scope.

1. Install and authenticate gh

brew install gh
gh auth login
gh auth refresh -h github.com -s project

2. Set up a project board

Create a GitHub Projects v2 board on your repo and add your issues to it. The CLI will auto-discover the board and create an ELO number field if one doesn't exist.

3. Configure the command

uv run microtasks configure-github --repo owner/repo-name

The CLI will:

1. Test-run gh issue list against the repo to verify access
2. Discover the project board (or prompt you to pick one)
3. Find or create an "ELO" number field on the board
4. Save the repo, project ID, and field ID to the database

Only one config is stored at a time — running configure-github again replaces the previous one.

3. Verify

After configuring, you can check that issues are being fetched:

# Via the API
curl http://localhost:8000/tasks/issue-sorter/issues

# Or visit the admin panel to edit this
open http://localhost:8000/admin

Tech Stack

• Runtime: Python 3.14
• Package manager: uv
• Web framework: FastAPI
• ORM: SQLModel (SQLAlchemy + Pydantic)
• Database: PostgreSQL (via Docker)
• Admin: SQLAdmin
• Migrations: Alembic
• CLI: Typer
• Testing: pytest
• Linting: ruff
• Type checking: mypy