From e0c788736bd1a0a6ccd2c5489349ef603f8c2922 Mon Sep 17 00:00:00 2001 From: skulidropek <66840575+skulidropek@users.noreply.github.com> Date: Thu, 12 Mar 2026 14:06:48 +0000 Subject: [PATCH 1/9] docs(readme): simplify user guide --- README.md | 277 ++++++++++-------------------------------------------- 1 file changed, 52 insertions(+), 225 deletions(-) diff --git a/README.md b/README.md index 682b6131..d1694caf 100644 --- a/README.md +++ b/README.md @@ -1,248 +1,75 @@ # docker-git -`docker-git` generates a disposable Docker development environment per repository (or empty workspace) and stores it under a single projects root (default: `~/.docker-git`). +`docker-git` поднимает отдельную Docker-среду для каждого репозитория, issue или PR. +Проекты по умолчанию хранятся в `~/.docker-git`. -Key goals: -- Functional Core, Imperative Shell implementation (pure templates + typed orchestration). -- Per-project `.orch/` directory (env + local state), while still allowing shared credentials across containers. -- Shared package caches (`pnpm`/`npm`/`yarn`) across all project containers. -- Optional Playwright MCP + Chromium sidecar so Codex and Claude Code can do browser automation. +## Зачем это нужно -## Quickstart +- Один репозиторий — один контейнер, без конфликтов между проектами. +- Можно открывать GitHub issue и PR как отдельные рабочие среды. +- Для существующего проекта можно отдельно включить Playwright MCP. -From this repo: +## Что нужно + +- Docker Engine или Docker Desktop +- Доступ к Docker без `sudo` +- Node.js и `npm` + +## Установка + +```bash +npm i -g @prover-coder-ai/docker-git +``` + +Альтернатива: ```bash -pnpm install +pnpm add -g @prover-coder-ai/docker-git +``` -# Interactive TUI menu (default) -pnpm run docker-git +Проверка: -# Create an empty workspace container (no git clone) -pnpm run docker-git create +```bash +docker-git --help +``` -# Clone a repo into its own container (creates under ~/.docker-git) -pnpm run docker-git clone https://github.com/agiens/crm/tree/vova-fork --force +## Быстрый старт -# Clone an issue URL (creates isolated workspace + issue branch) -pnpm run docker-git clone https://github.com/agiens/crm/issues/123 --force +Авторизация GitHub: -# Open an existing docker-git project by repo/issue URL (runs up + tmux attach) -pnpm run docker-git open https://github.com/agiens/crm/issues/123 +```bash +docker-git auth github login --web +``` -# Reset only project env defaults (keep workspace volume/data) -pnpm run docker-git clone https://github.com/agiens/crm/issues/123 --force-env +Клонировать репозиторий в отдельную среду: -# Same, but also enable Playwright MCP + Chromium sidecar for Codex/Claude -pnpm run docker-git clone https://github.com/agiens/crm/tree/vova-fork --force --mcp-playwright +```bash +docker-git clone https://github.com/org/repo ``` -## API Docker (separate runtime) +Клонировать issue как отдельную среду: + +```bash +docker-git clone https://github.com/org/repo/issues/123 +``` -HTTP API (`packages/api`) has a dedicated Docker image and compose file: +Открыть уже созданный проект: ```bash -docker compose -f docker-compose.api.yml up -d --build -curl -s http://127.0.0.1:3334/health +docker-git open https://github.com/org/repo/issues/123 ``` -By default API port `3334` is published to host (`127.0.0.1:3334`). - -Useful env overrides: -- `DOCKER_GIT_API_BIND_HOST` (default: `127.0.0.1`) -- `DOCKER_GIT_API_PORT` (default: `3334`) -- `DOCKER_GIT_PROJECTS_ROOT_HOST` (host path, default: `/home/dev/.docker-git`) -- `DOCKER_GIT_PROJECTS_ROOT` (container path, default: `/home/dev/.docker-git`) - -Detailed federation subscription workflow and JSON examples are documented in `packages/api/README.md`. - -## Parallel Issues / PRs - -When you clone GitHub issue or PR URLs, docker-git creates isolated project paths and container names: -- `.../issues/123` -> `///issue-123` (branch `issue-123`) -- `.../pull/45` -> `///pr-45` (ref `refs/pull/45/head`) - -This lets you run multiple issues/PRs for the same repository in parallel without container/path collisions. - -Force modes: -- `--force`: overwrite managed files and wipe compose volumes (`docker compose down -v`). -- `--force-env`: reset only project env defaults and recreate containers without wiping volumes. - -Agent context for issue workspaces: -- Global `${CODEX_HOME}/AGENTS.md` includes workspace path + issue/PR context. - -## Projects Root Layout - -The projects root is: -- `~/.docker-git` by default -- Override with `DOCKER_GIT_PROJECTS_ROOT=/some/path` - -Structure (simplified): - -```text -~/.docker-git/ - authorized_keys - .orch/ - env/ - global.env # shared tokens/keys (GitHub, Git, Claude) with labels - auth/ - codex/ # shared Codex auth/config (when CODEX_SHARE_AUTH=1) - gh/ # GH CLI auth cache for OAuth login container - .cache/ - git-mirrors/ # shared git clone mirrors - packages/ # shared pnpm/npm/yarn caches - // - docker-compose.yml - Dockerfile - entrypoint.sh - docker-git.json - .orch/ - env/ - project.env # per-project env knobs (see below) - auth/ - codex/ # project-local Codex state (sessions/logs/tmp/etc) +Включить Playwright MCP для существующего проекта: + +```bash +docker-git mcp-playwright --project-dir . ``` -## Codex Auth: Shared Credentials, Per-Project Sessions - -Default behavior: -- Shared credentials live in `/home/dev/.codex-shared/auth.json` (mounted from `/.orch/auth/codex`). -- Each project keeps its own Codex state under `/home/dev/.codex/` (mounted from project `.orch/auth/codex`). -- The entrypoint links `/home/dev/.codex/auth.json -> /home/dev/.codex-shared/auth.json`. - -This avoids `refresh_token` rotation issues that can happen when copying `auth.json` into every project while still keeping session state isolated per project. - -Disable sharing (per-project auth): -- Set `CODEX_SHARE_AUTH=0` in `.orch/env/project.env`. - -## Claude Code Defaults - -On container start, docker-git syncs Claude Code user settings under `$CLAUDE_CONFIG_DIR/settings.json`: -- `permissions.defaultMode = "bypassPermissions"` so local disposable containers behave like docker-git Codex containers (no permission prompts). -- Existing unrelated Claude settings are preserved. - -## Playwright MCP (Chromium Sidecar) - -Enable during create/clone: -- Add `--mcp-playwright` - -Enable for an existing project directory (preserves `.orch/env/project.env` and volumes): -- `docker-git mcp-playwright [] [--project-dir ]` - -This will: -- Create a Chromium sidecar container: `dg--browser` -- Configure Codex MCP server `playwright` inside the dev container -- Configure Claude Code MCP server `playwright` inside `$CLAUDE_CONFIG_DIR/.claude.json` -- Provide a wrapper `docker-git-playwright-mcp` inside the dev container - -Template attribute behavior: -- `--mcp-playwright` sets `enableMcpPlaywright=true` in `docker-git.json`. -- On container start, docker-git syncs Playwright MCP config for both Codex and Claude based on this attribute/env. - -Concurrency (many Codex sessions): -- Default is safe for many sessions: `MCP_PLAYWRIGHT_ISOLATED=1` -- Each Codex session gets its own browser context (incognito) to reduce cross-session interference. -- If you want a shared browser context (shared cookies/login), set `MCP_PLAYWRIGHT_ISOLATED=0` (not recommended with multiple concurrent sessions). - -## Runtime Env Knobs (per project) - -Edit: `/.orch/env/project.env` - -Common toggles: -- `CODEX_SHARE_AUTH=1|0` (default: `1`) -- `CODEX_AUTO_UPDATE=1|0` (default: `1`) -- `CLAUDE_AUTO_SYSTEM_PROMPT=1|0` (default: `1`, auto-attach managed system prompt to `claude`) -- `DOCKER_GIT_ZSH_AUTOSUGGEST=1|0` (default: `1`) -- `MCP_PLAYWRIGHT_ISOLATED=1|0` (default: `1`) -- `MCP_PLAYWRIGHT_CDP_ENDPOINT=http://...` (override CDP endpoint if needed) -- `PNPM_STORE_DIR=/home/dev/.docker-git/.cache/packages/pnpm/store` (default shared store) -- `NPM_CONFIG_CACHE=/home/dev/.docker-git/.cache/packages/npm` (default shared cache) -- `YARN_CACHE_FOLDER=/home/dev/.docker-git/.cache/packages/yarn` (default shared cache) - -## Compose Network Mode - -Default mode is shared: -- `--network-mode shared` (default) -- Shared compose network name: `--shared-network docker-git-shared` - -Shared mode keeps one external Docker network for all docker-git projects, which reduces address pool pressure when many projects are created. - -If you need strict per-project isolation: -- `--network-mode project` - -In project mode, each project uses `-net` (Docker-managed bridge network). - -## Troubleshooting - -MCP errors in `codex` UI: -- `No such file or directory (os error 2)` for `playwright`: - - `~/.codex/config.toml` contains `[mcp_servers.playwright]`, but the container was created without `--mcp-playwright`. - - Fix (recommended): run `docker-git mcp-playwright []` to enable it for the existing project. - - Fix (recreate): recreate with `--force-env --mcp-playwright` (keeps volumes) or `--force --mcp-playwright` (wipes volumes). -- `handshaking ... initialize response`: - - The configured MCP command is not a real MCP server (example: `command="echo"`). - -MCP errors in `claude` UI: -- `MCP server "playwright" not found`: - - The container/project was created without `--mcp-playwright` (or `enableMcpPlaywright=false` in `docker-git.json`). - - Fix: run `docker-git mcp-playwright []` or recreate/apply with `--mcp-playwright`. - -Docker permission error (`/var/run/docker.sock`): -- Symptom: - - `permission denied while trying to connect to the docker API at unix:///var/run/docker.sock` -- Check: - ```bash - id - ls -l /var/run/docker.sock - docker version - ``` -- Fix (works in `fish` and `bash`): - ```bash - sudo chgrp docker /var/run/docker.sock - sudo chmod 660 /var/run/docker.sock - sudo mkdir -p /etc/systemd/system/docker.socket.d - printf '[Socket]\nSocketGroup=docker\nSocketMode=0660\n' | sudo tee /etc/systemd/system/docker.socket.d/override.conf >/dev/null - sudo systemctl daemon-reload - sudo systemctl restart docker.socket docker - ``` -- Verify: - ```bash - ls -l /var/run/docker.sock - docker version - ``` -- Note: - - Do not run `pnpm run docker-git ...` with `sudo`. - -Docker network pool exhausted (`all predefined address pools have been fully subnetted`): -- Symptom: - - `failed to create network ... all predefined address pools have been fully subnetted` -- Quick recovery: - ```bash - docker network prune -f - ``` -- Long-term fix: - - Configure Docker daemon `default-address-pools` in `/etc/docker/daemon.json`. - - Prefer `docker-git` shared network mode (`--network-mode shared`). - -Clone auth error (`Invalid username or token`): -- Symptom: - - `remote: Invalid username or token. Password authentication is not supported for Git operations.` -- Check and fix token: - ```bash - pnpm run docker-git auth github status - pnpm run docker-git auth github logout - pnpm run docker-git auth github login --web - pnpm run docker-git auth github status - ``` -- Token requirements: - - Token must have access to the target repository. - - For org repositories with SSO/SAML, authorize the token for that organization. - - Recommended scopes: `repo,workflow,read:org`. - -## Security Notes - -The generated Codex config uses: -- `sandbox_mode = "danger-full-access"` -- `approval_policy = "never"` - -This is intended for local disposable containers. Do not reuse these defaults for untrusted code. +## Где лежат проекты + +По умолчанию: `~/.docker-git` + +## Подробности + +- Все команды и флаги: `docker-git --help` +- API-документация: [packages/api/README.md](packages/api/README.md) From 46221ad6e764af7ad843f9183144b1546d69eee4 Mon Sep 17 00:00:00 2001 From: skulidropek <66840575+skulidropek@users.noreply.github.com> Date: Thu, 12 Mar 2026 14:13:28 +0000 Subject: [PATCH 2/9] docs(readme): tighten auth and example commands --- README.md | 57 ++++++++++++------------------------------------------- 1 file changed, 12 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index d1694caf..aa903769 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,7 @@ # docker-git -`docker-git` поднимает отдельную Docker-среду для каждого репозитория, issue или PR. -Проекты по умолчанию хранятся в `~/.docker-git`. - -## Зачем это нужно - -- Один репозиторий — один контейнер, без конфликтов между проектами. -- Можно открывать GitHub issue и PR как отдельные рабочие среды. -- Для существующего проекта можно отдельно включить Playwright MCP. +`docker-git` создаёт отдельную Docker-среду для каждого репозитория, issue или PR. +По умолчанию проекты лежат в `~/.docker-git`. ## Что нужно @@ -19,57 +13,30 @@ ```bash npm i -g @prover-coder-ai/docker-git -``` - -Альтернатива: - -```bash -pnpm add -g @prover-coder-ai/docker-git -``` - -Проверка: - -```bash docker-git --help ``` -## Быстрый старт - -Авторизация GitHub: +Из этого репозитория: ```bash -docker-git auth github login --web +pnpm install +pnpm run docker-git --help ``` -Клонировать репозиторий в отдельную среду: +## Авторизация ```bash -docker-git clone https://github.com/org/repo +pnpm run docker-git auth github login --web +pnpm run docker-git auth codex login --web +pnpm run docker-git auth claude login --web ``` -Клонировать issue как отдельную среду: +## Пример ```bash -docker-git clone https://github.com/org/repo/issues/123 +docker-git clone https://github.com/agiens/crm/tree/vova-fork --force --mcp-playwright ``` -Открыть уже созданный проект: - -```bash -docker-git open https://github.com/org/repo/issues/123 -``` - -Включить Playwright MCP для существующего проекта: - -```bash -docker-git mcp-playwright --project-dir . -``` - -## Где лежат проекты - -По умолчанию: `~/.docker-git` - ## Подробности -- Все команды и флаги: `docker-git --help` -- API-документация: [packages/api/README.md](packages/api/README.md) +`docker-git --help` From 5e1603cf54b5d5f2b847e98dbc6058f2cdd12824 Mon Sep 17 00:00:00 2001 From: skulidropek <66840575+skulidropek@users.noreply.github.com> Date: Thu, 12 Mar 2026 14:23:08 +0000 Subject: [PATCH 3/9] docs(readme): clarify auth and flags --- README.md | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index aa903769..a08a83c6 100644 --- a/README.md +++ b/README.md @@ -16,19 +16,12 @@ npm i -g @prover-coder-ai/docker-git docker-git --help ``` -Из этого репозитория: - -```bash -pnpm install -pnpm run docker-git --help -``` - ## Авторизация ```bash -pnpm run docker-git auth github login --web -pnpm run docker-git auth codex login --web -pnpm run docker-git auth claude login --web +docker-git auth github login --web +docker-git auth codex login --web +docker-git auth claude login --web ``` ## Пример @@ -37,6 +30,9 @@ pnpm run docker-git auth claude login --web docker-git clone https://github.com/agiens/crm/tree/vova-fork --force --mcp-playwright ``` +- `--force` пересоздаёт окружение и удаляет volumes проекта. +- `--mcp-playwright` включает Playwright MCP и Chromium sidecar для браузерной автоматизации. + ## Подробности `docker-git --help` From a81c49c121cf49203cbc737529d46c4fc3538ced Mon Sep 17 00:00:00 2001 From: Skuli Dropek <66840575+skulidropek@users.noreply.github.com> Date: Thu, 12 Mar 2026 18:33:57 +0400 Subject: [PATCH 4/9] Fix clone command in README example Updated the clone command in the README to point to the correct GitHub issue. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index a08a83c6..97a798bd 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ docker-git auth claude login --web ## Пример ```bash -docker-git clone https://github.com/agiens/crm/tree/vova-fork --force --mcp-playwright +docker-git clone https://github.com/ProverCoderAI/docker-git/issues/122 --force --mcp-playwright ``` - `--force` пересоздаёт окружение и удаляет volumes проекта. From 0e99b1d1865363352f0b5fb53228f3beaf7e938a Mon Sep 17 00:00:00 2001 From: skulidropek <66840575+skulidropek@users.noreply.github.com> Date: Thu, 12 Mar 2026 14:43:29 +0000 Subject: [PATCH 5/9] docs(readme): add auto mode note --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 97a798bd..61f2b0e5 100644 --- a/README.md +++ b/README.md @@ -32,6 +32,7 @@ docker-git clone https://github.com/ProverCoderAI/docker-git/issues/122 --force - `--force` пересоздаёт окружение и удаляет volumes проекта. - `--mcp-playwright` включает Playwright MCP и Chromium sidecar для браузерной автоматизации. +- `--auto` работает вместе с `--claude` или `--codex`: агент выполняет задачу автономно, а `docker-git` ждёт завершения и очищает контейнер. ## Подробности From 51b7cff16ff2f4f00ed089c6399f682c7e69d5f7 Mon Sep 17 00:00:00 2001 From: skulidropek <66840575+skulidropek@users.noreply.github.com> Date: Thu, 12 Mar 2026 14:44:47 +0000 Subject: [PATCH 6/9] docs(readme): restore crm example --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 61f2b0e5..7a4821e7 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,7 @@ docker-git auth claude login --web ## Пример ```bash -docker-git clone https://github.com/ProverCoderAI/docker-git/issues/122 --force --mcp-playwright +docker-git clone https://github.com/agiens/crm/tree/vova-fork --force --mcp-playwright ``` - `--force` пересоздаёт окружение и удаляет volumes проекта. From cd56f6d45cdd7d84c7eb7a92931d735cd42daf09 Mon Sep 17 00:00:00 2001 From: skulidropek <66840575+skulidropek@users.noreply.github.com> Date: Thu, 12 Mar 2026 14:47:09 +0000 Subject: [PATCH 7/9] docs(readme): clarify supported url formats --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 7a4821e7..006d3a5c 100644 --- a/README.md +++ b/README.md @@ -26,8 +26,10 @@ docker-git auth claude login --web ## Пример +Можно передавать ссылку на репозиторий, ветку (`/tree/...`), issue или PR. + ```bash -docker-git clone https://github.com/agiens/crm/tree/vova-fork --force --mcp-playwright +docker-git clone https://github.com/ProverCoderAI/docker-git/issues/122 --force --mcp-playwright ``` - `--force` пересоздаёт окружение и удаляет volumes проекта. From 3762865e4f5fddded46e1a3c5da2724823275f1a Mon Sep 17 00:00:00 2001 From: skulidropek <66840575+skulidropek@users.noreply.github.com> Date: Thu, 12 Mar 2026 21:02:57 +0000 Subject: [PATCH 8/9] docs(readme): add auto mode example --- README.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 006d3a5c..4d14a49b 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,14 @@ docker-git clone https://github.com/ProverCoderAI/docker-git/issues/122 --force - `--force` пересоздаёт окружение и удаляет volumes проекта. - `--mcp-playwright` включает Playwright MCP и Chromium sidecar для браузерной автоматизации. -- `--auto` работает вместе с `--claude` или `--codex`: агент выполняет задачу автономно, а `docker-git` ждёт завершения и очищает контейнер. + +Автоматический запуск агента: + +```bash +docker-git clone https://github.com/ProverCoderAI/docker-git/issues/122 --force --claude --auto +``` + +- `--auto` работает вместе с `--claude` или `--codex`: агент сам выполняет задачу, создаёт PR и после завершения контейнер очищается. ## Подробности From ca8429cbb60299265391c17844eca9fa824df4a3 Mon Sep 17 00:00:00 2001 From: skulidropek <66840575+skulidropek@users.noreply.github.com> Date: Fri, 13 Mar 2026 07:41:12 +0000 Subject: [PATCH 9/9] docs(readme): update auto mode usage --- README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 4d14a49b..48a0eb0e 100644 --- a/README.md +++ b/README.md @@ -38,10 +38,12 @@ docker-git clone https://github.com/ProverCoderAI/docker-git/issues/122 --force Автоматический запуск агента: ```bash -docker-git clone https://github.com/ProverCoderAI/docker-git/issues/122 --force --claude --auto +docker-git clone https://github.com/ProverCoderAI/docker-git/issues/122 --force --auto ``` -- `--auto` работает вместе с `--claude` или `--codex`: агент сам выполняет задачу, создаёт PR и после завершения контейнер очищается. +- `--auto` сам выбирает Claude или Codex по доступной авторизации. Если доступны оба, выбор случайный. +- `--auto=claude` или `--auto=codex` принудительно выбирает агента. +- В auto-режиме агент сам выполняет задачу, создаёт PR и после завершения контейнер очищается. ## Подробности