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
/plugin marketplace add fcakyon/claude-codex-settings
/plugin install polar-skills@claude-settingsWhat 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
apicontainer. - 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-settings2Manually: put the files in place
.claude/rules/shell-and-workflows.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/shell-and-workflows.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/shell-and-workflows.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/shell-and-workflows.mdManually: put the files in place
.clinerules/shell-and-workflows.mdStep 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