Skip to main content
rule CX Codex

shell-and-workflows — Claude Code rule for Docker workflows

The shell-and-workflows rule documents Docker commands for the project and explains where to run frontend and backend tests. Use it when managing services or checking a change.

Apache-2.0 ★ 1,216 updated 2026-10-24

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add fcakyon/claude-codex-settings
/plugin install polar-skills@claude-settings
Open on GitHub

What shell-and-workflows does

The rule covers dev docker commands for entering containers, running one-off commands, and handling the regular service cycle: start the stack, check status, follow logs, then stop it. It includes Alembic migration commands for api and worker, pnpm tests and linting for web, plus PostgreSQL access to the current instance. Run dev docker ports to find the worktree’s instance number and ports.

After git pull, hot reload handles most changes. Restart services when dependencies change; rebuild them if a Dockerfile or system dependency has changed. Backend tests do not run in the api container: their fixture expects S3 at http://127.0.0.1:9000, which containers cannot reach on the host. Run those tests on the host with uv run task test, following server/AGENTS.md. That distinction matters when choosing how to verify a backend change.

What it helps with

  • enter the right service container to inspect its environment
  • run a one-off command in Docker without opening an interactive shell
  • apply a database migration or create a new revision
  • check service status and follow application logs
  • choose the correct environment for frontend and backend tests

Example prompts for the agent

  • Show me how to start the project services and check their status with dev docker.
  • Give me the command to apply the current Alembic migrations in the api container.
  • Where should I run the web tests and backend tests for this project?

How to install shell-and-workflows

1Plugin marketplace

/plugin marketplace add fcakyon/claude-codex-settings
/plugin install polar-skills@claude-settings

2Manually: put the files in place

.claude/rules/shell-and-workflows.md

The paths frontmatter field limits the files

Step by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use

Questions about shell-and-workflows

How do I install shell-and-workflows in Claude Code?

Run /plugin marketplace add fcakyon/claude-codex-settings? Correct command formatting: first /plugin marketplace add fcakyon/claude-codex-settings, then /plugin install polar-skills@claude-settings.

What does the shell-and-workflows rule do?

It documents project Docker commands for containers, database migrations, logs, and tests. It also explains when to restart or rebuild services after pulling changes.

Where should I run backend tests?

Run them on the host with uv run task test, following server/AGENTS.md. The api container cannot reach the S3 endpoint at http://127.0.0.1:9000 that the test fixture requires.

Source text

shell-and-workflows.md · Apache-2.0
---
title: Shell Access and Common Workflows
category: Operations
tags: shell, exec, workflows, testing
---

# Shell Access and Common Workflows

## Shell into a container

```bash
dev docker shell api      # Python env (api)
dev docker shell worker   # Python env (worker)
dev docker shell web      # Node env
dev docker shell db       # postgres container (shared)
```

For one-off commands without an interactive shell, use `exec`:

```bash
dev docker exec api uv run alembic current
dev docker exec db psql -U polar -d polar_dev_<N> -c "SELECT 1"
dev docker exec redis redis-cli -n <N> dbsize
```

`exec`/`shell` auto-route by service name: app services hit this instance's
`polar-app-<N>` project, infra services hit `polar-shared`.

## Useful in-container commands

**api / worker (Python):**
```bash
uv run alembic upgrade head                             # run migrations
uv run alembic revision --autogenerate -m "message"     # create a migration
uv run alembic current                                  # show current revision
```
(Backend tests are the exception — they don't run in this container; see below.)

**web (Node):**
```bash
pnpm test
pnpm lint
```

**db (PostgreSQL):** the database is per-instance, so pass `polar_dev_<N>`, not
`polar`:
```bash
psql -U polar -d polar_dev_<N>
```

## Common workflows

**Daily development:**
```bash
dev docker up -d --wait     # start and wait until serving
dev docker ps               # confirm status
dev docker logs -f api      # watch as you work
dev docker down             # stop when done (data persists)
```

**After a git pull:** hot-reload handles most changes. If deps changed:
```bash
dev docker restart api worker web        # picks up new deps via startup uv sync / pnpm
# only if a Dockerfile or system dep changed:
dev docker up -b -d api worker web
```

**Run tests:**

Frontend unit tests run in the web container:
```bash
dev docker exec web pnpm test
```

Backend tests do **not** run in the `dev docker` api container. The suite's
session-wide `empty_test_bucket` fixture hard-requires S3 at
`http://127.0.0.1:9000` with `testing`-prefixed buckets, but containers can't
reach `localhost:9000` on the host — they use `minio:9000` internally with
per-instance `polar-s3-<N>` buckets. Run backend tests on the host with the
standard setup in `server/AGENTS.md` (`uv run task test`).

**Database operations:**
```bash
dev docker exec api uv run alembic upgrade head
dev docker exec api uv run alembic downgrade -1
dev docker exec db psql -U polar -d polar_dev_<N>
```

Find `<N>` (and the real ports) for the current worktree with `dev docker ports`.

© fcakyon · Apache-2.0 · fcakyon/claude-codex-settings

Similar IDE rules

All IDE rules for DevOps and infrastructure →

From the same set113

The whole set →
ui-image-gallery ui-image-gallery directs AI assistants to build image galleries using @nandorojo/galeria instead of custom modal popups. CX Codex +1 ★ 1,216repo stars rendering-resource-hints The rendering-resource-hints rule tells the agent when to call React DOM's resource-hint functions inside React components. It targets server components, letting the browser start fetching assets before the client even has the HTML. CX Codex +1 ★ 1,216repo stars animation-gesture-detector-press animation-gesture-detector-press is a React Native rule that keeps press animations on the UI thread, for buttons that scale or fade while pressed. CX Codex +1 ★ 1,216repo stars commit-staged commit-staged automates commit creation: checks staged diffs, runs /simplify on code edits, and writes conventional commits using session rationale. CX Codex +1 ★ 1,216repo stars js-request-idle-callback js-request-idle-callback — a rule that moves analytics, state saving and prefetching into idle browser time so the interface stops stuttering on every click. CX Codex +1 ★ 1,216repo stars pr-comment-resolver pr-comment-resolver inspects unresolved pull request reviews, applies necessary code updates, and drafts replies for reviewers. Ideal for clearing PR feedback without manual issue hunting. CX Codex ★ 1,216repo stars list-performance-item-types list-performance-item-types is a Claude Code rule for lists with mixed layouts. It guides the agent to assign item types and keep unlike cells in separate recycling pools. CX Codex +1 ★ 1,216repo stars manage-instances manage-instances — a rule for running multiple isolated app stacks in separate worktrees, each with its own database, Redis index, and host ports. CX Codex +1 ★ 1,216repo stars

Project sponsors

Companies that keep this analytics open