{"id":34634805,"url":"https://github.com/andriiklymiuk/corgi","last_synced_at":"2026-07-01T13:00:46.705Z","repository":{"id":59769805,"uuid":"539068667","full_name":"Andriiklymiuk/corgi","owner":"Andriiklymiuk","description":"Corgi helps to send someone your project yml file, init and run it in minutes.  Auto git cloning, db seeding, concurrent running and much more.","archived":false,"fork":false,"pushed_at":"2026-06-26T06:09:48.000Z","size":17165,"stargazers_count":35,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-26T08:06:21.944Z","etag":null,"topics":["corgi","docker","golang","makefile","microservices"],"latest_commit_sha":null,"homepage":"https://andriiklymiuk.github.io/corgi/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Andriiklymiuk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"docs/agents.md","dco":null,"cla":null}},"created_at":"2022-09-20T15:46:34.000Z","updated_at":"2026-06-26T06:08:00.000Z","dependencies_parsed_at":"2025-12-24T17:00:41.953Z","dependency_job_id":null,"html_url":"https://github.com/Andriiklymiuk/corgi","commit_stats":null,"previous_names":[],"tags_count":295,"template":false,"template_full_name":null,"purl":"pkg:github/Andriiklymiuk/corgi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Andriiklymiuk%2Fcorgi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Andriiklymiuk%2Fcorgi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Andriiklymiuk%2Fcorgi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Andriiklymiuk%2Fcorgi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Andriiklymiuk","download_url":"https://codeload.github.com/Andriiklymiuk/corgi/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Andriiklymiuk%2Fcorgi/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35007278,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-01T02:00:05.325Z","response_time":130,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["corgi","docker","golang","makefile","microservices"],"created_at":"2025-12-24T17:00:10.955Z","updated_at":"2026-07-01T13:00:46.691Z","avatar_url":"https://github.com/Andriiklymiuk.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg width=\"300\" height=\"300\" src=\"./resources/corgi.png\"\u003e\n\n  # 🐶 CORGI 🐶\n\n  **Run your whole local stack from one file — repos, databases, env, every service. And let AI agents plan, build, and review work across it.** \n\n  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n  [![Homebrew](https://img.shields.io/badge/install-brew-orange.svg)](#install)\n\n  [![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=Andriiklymiuk_corgi\u0026metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=Andriiklymiuk_corgi)\n  [![Bugs](https://sonarcloud.io/api/project_badges/measure?project=Andriiklymiuk_corgi\u0026metric=bugs)](https://sonarcloud.io/summary/new_code?id=Andriiklymiuk_corgi)\n  [![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=Andriiklymiuk_corgi\u0026metric=code_smells)](https://sonarcloud.io/summary/new_code?id=Andriiklymiuk_corgi)\n\n[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=Andriiklymiuk_corgi\u0026metric=security_rating)](https://sonarcloud.io/summary/new_code?id=Andriiklymiuk_corgi)\n[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=Andriiklymiuk_corgi\u0026metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=Andriiklymiuk_corgi)\n\n[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=Andriiklymiuk_corgi\u0026metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=Andriiklymiuk_corgi)\n[![Lines of Code](https://sonarcloud.io/api/project_badges/measure?project=Andriiklymiuk_corgi\u0026metric=ncloc)](https://sonarcloud.io/summary/new_code?id=Andriiklymiuk_corgi)\n[![Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=Andriiklymiuk_corgi\u0026metric=sqale_index)](https://sonarcloud.io/summary/new_code?id=Andriiklymiuk_corgi)\n\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=Andriiklymiuk_corgi\u0026metric=alert_status)](https://sonarcloud.io/summary/new_code?id=Andriiklymiuk_corgi)\n[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=Andriiklymiuk_corgi\u0026metric=coverage)](https://sonarcloud.io/summary/new_code?id=Andriiklymiuk_corgi)\n[![Duplicated Lines (%)](https://sonarcloud.io/api/project_badges/measure?project=Andriiklymiuk_corgi\u0026metric=duplicated_lines_density)](https://sonarcloud.io/summary/new_code?id=Andriiklymiuk_corgi)\n\n\u003c/div\u003e\n\nCorgi is how you run your project locally — every day, with one command. You describe the stack once in a `corgi-compose.yml`, and `corgi run` brings the whole thing up: repos cloned, databases seeded, `.env` files written, every service started. It even starts Docker for you, so the infra just happens and you stop thinking about it.\n\nOnboarding falls out for free: hand a teammate the same file and they go from nothing to a running stack in minutes — no setup call, no digging through old READMEs, no \"works on my machine\". And because corgi never blocks on a prompt and speaks plain JSON, an AI agent or a CI job can drive it exactly the way you do.\n\nInstall it and take a ready-made example for a spin:\n\n```bash\nbrew install andriiklymiuk/homebrew-tools/corgi\ncorgi run -l      # browse runnable examples, pick one to try\n```\n\nHere's what `corgi run` does, end to end — one file in, whole stack out:\n\n```text\ncorgi-compose.yml  ─►  corgi run\n                         ├─ clone missing repos\n                         ├─ start + seed databases (in Docker)\n                         ├─ write + wire .env between services\n                         └─ run services as host processes\n                                    ↓\n                         whole stack running 🐶   (Ctrl-C tears it all down)\n```\n\nThat's the _running_ side. corgi works the other direction too: because it already knows how your services fit together, its [Claude Code plugin](#ai-agents-mcp--claude-code) lets an agent **work across the stack** — read your Linear/Jira board, pick up ready tickets, turn them into draft PRs, and review them for you.\n\n## Why corgi?\n\nWiring up a multi-service project by hand is the same slog every time — joining a team, setting up a new laptop, or starting a fresh repo. You end up having to:\n\n- clone four different repos,\n- install Postgres, Redis, Kafka… and the right Go / Node / Yarn versions,\n- create the databases and fill them with test data,\n- copy `.env` files and point each service at the others,\n- pick ports that don't clash,\n- and finally start everything in the right order, across a row of terminal tabs.\n\nThat's most of a day gone — and it breaks again on the next laptop.\n\n`docker-compose` handles the _containers_. Corgi handles everything around them too: the repos, the seeded data, the env wiring, the tools you need. Your databases run in Docker; your services run as normal processes (`go run .`, `yarn dev`). One file, one command — and it keeps paying off long after setup, because it's also how you run the stack from then on.\n\nIn practice, a real multi-repo stack — backend, frontend, and a mobile app — can eat **more than a day** of cloning and debugging setup by hand. With corgi that drops to **~an hour** the first time someone uses it, and **~10 minutes** on the next project once they know the tool. And when you come back to a project months later and can't remember how to run it, the answer is just `corgi run` — no per-project setup scripts to write or keep alive.\n\n## What corgi does for you\n\n- **Your repos** — Corgi clones each service from its Git URL the first time you run. It can also pull them all at once, fork them, or run one service on a branch in a throwaway worktree — without disturbing the checkout you're working in.\n- **Your databases** — 38 ready-to-go drivers. Corgi starts them in Docker and **seeds** them from a dump or a remote DB, so you get real data instead of an empty schema. Open a shell with `corgi db shell` and the password is already filled in. Need AWS or Supabase locally? LocalStack and Supabase come up from the same file.\n- **Your services** — Everything starts together with the env vars already wired between them. They boot in parallel by default; when one genuinely needs another up first, gate it with `condition: ready` on the dependency (or `--gate-deps` for all of them). Press `Ctrl-C` and it all winds down cleanly. Prefer the background? `corgi run -d`, then check on it with `corgi ps`.\n- **The fiddly bits** — A preflight that catches missing tools and busy ports _before_ they bite (`corgi doctor`), live health (`corgi status -w`), public HTTPS URLs for webhook testing (`corgi tunnel`), saved logs, and a desktop ping when something crashes.\n- **Made for AI agents** — it speaks clean JSON, returns exit codes an agent can branch on, runs an MCP server, and ships a Claude Code plugin that plans from your Linear/Jira board, picks up ready tickets and turns them into draft PRs (and reviews them for you).\n\n## In your day-to-day\n\ncorgi flexes to whatever the day calls for:\n\n- **The whole stack.** `corgi run` brings up every database and service together.\n- **Just the databases.** Running a service straight from your IDE or debugger? `corgi db -u` brings the databases up on their own and leaves the rest to you.\n- **A phone or another device on your LAN.** `corgi run --host auto` puts your machine's LAN IP into the service-URL env vars instead of `localhost`, so a real device or simulator can reach your dev API (pass an explicit IP instead of `auto` if you prefer). Databases stay on `localhost`.\n- **Local, staging, or a mix.** Define an env tier once — a folder of per-service env files, plus whether to skip the local databases:\n  ```yml\n  envTiers:\n    staging:\n      dir: env/staging   # you create env/staging/\u003cservice\u003e.env with the staging URLs/keys\n      dbServices: none   # skip local databases — the staging env already points at staging's\n  ```\n  Then pick it with a flag — run everything locally, or just the frontend against staging:\n  ```bash\n  corgi run                                  # everything local\n  corgi run --tier staging --services web    # only the web app, talking to staging\n  ```\n  (A tier can also set `confirm: true` to prompt before you run against a sensitive one.)\n- **A new project.** The first thing to do in a fresh repo is write a `corgi-compose.yml` — `corgi create` or `/corgi-new` gets you one in a minute — so \"how do I run this?\" has a permanent answer.\n- **Hand work to Claude.** Drop a few tickets into `/corgi:stories` and Claude plans the feature across your services and opens a draft PR for each ([more below](#ai-agents-mcp--claude-code)).\n\nThe point isn't any single command — it's that you stop babysitting infrastructure and get back to building.\n\n## Quick start\n\n```bash\nbrew install andriiklymiuk/homebrew-tools/corgi   # or see Install below\n\ncorgi run -l        # browse runnable examples, pick one to try\n\n# in your own project, next to a corgi-compose.yml:\ncorgi doctor        # check required tools, ports, docker\ncorgi run           # start every database + service, together\ncorgi status -w     # watch each service turn healthy\n```\n\nDon't have a `corgi-compose.yml` yet? `corgi create` scaffolds one — or let Claude write it with `/corgi-new` (see [AI agents](#ai-agents-mcp--claude-code)).\n\n## What the file looks like\n\nHere's the whole setup for a seeded Postgres, an auto-cloned Go API, and a web app — wired together:\n\n```yml\ndb_services:\n  db:\n    driver: postgres\n    databaseName: app\n    port: 5432\n    seedFromFilePath: ./seed.sql            # loaded on first run\n\nservices:\n  api:\n    cloneFrom: https://github.com/acme/api.git   # cloned if ./api isn't there yet\n    path: ./api\n    port: 7012\n    depends_on_db:\n      - name: db                            # puts DB_HOST/DB_PORT/DB_NAME/... in api/.env\n    start:\n      - go run .\n  web:\n    cloneFrom: https://github.com/acme/web.git\n    path: ./web\n    depends_on_services:\n      - name: api                           # puts api's URL in web/.env\n    beforeStart:\n      - yarn install\n    start:\n      - yarn dev\n\nrequired:                                   # corgi doctor checks these; --fix installs them\n  docker:\n    checkCmd: docker -v\n  go:\n    why:\n      - Build and run the api\n    checkCmd: go version\n    install:\n      - brew install go\n```\n\nRun `corgi run` and it clones anything missing, starts Postgres in Docker and seeds it, writes the `.env` files (and sources them for you — no boilerplate), then runs `api` and `web` together. `Ctrl-C` shuts it all back down and runs any cleanup steps.\n\nWant to see every field? Run `corgi docs`, or browse the [examples repo](https://github.com/Andriiklymiuk/corgi_examples).\n\n## Getting it running on a real project\n\nThe examples use public repos. Real projects have private repos, prerequisites, and first-run hiccups — here's the honest version.\n\n**What you need:** `git`, and Docker (only if you declare `db_services`). Everything else lives in your project's `required:` block. Homebrew is just one way to install corgi itself, not a requirement. corgi runs on macOS, Linux, and Windows (PowerShell or WSL), so a mixed-OS team shares the same `corgi-compose.yml`.\n\nThat `required:` block is more than a checklist — it's a committed, runnable record of everything the project needs. Each entry has `why:` (so teammates know what it's for), `checkCmd:` (how to verify it — check a specific version here if you want), and `install:` (the commands to get it). `install:` runs whatever it takes: a `brew install`, a `pyenv`/`rbenv` install to pin Python 3.12 or Ruby 3.4, a native lib, a cert via `mkcert -install`. `corgi doctor` runs every `checkCmd`; `corgi doctor --fix` runs the `install:` steps for you — so \"what do I need installed?\" is answered in the file, not a wiki.\n\n**Private repos just work.** corgi clones with plain `git`, so your existing SSH keys or credential helper are used as-is — private GitHub/GitLab services clone fine if your `git` is already set up. There's no corgi-specific auth to configure.\n\n**Joining a team that already uses corgi?** `git pull`, then `corgi run`. No `corgi-compose.yml` yet? You don't have to hand-write it — `corgi create` (or `/corgi-new` with Claude) inspects the repos and scaffolds one. Adding corgi is a single committed file, and teammates who don't use it aren't affected, since everything corgi generates is gitignored (see below).\n\n**When the first run trips up:**\n- _Port already in use_ — `corgi doctor` names the process holding it; `corgi run --kill-port` frees it.\n- _Missing tool, or Docker not running_ — `corgi doctor --fix`.\n- _A clone failed_ — you don't have git access to that repo yet; fix your SSH/token and re-run.\n- _Seeding failed_ — check the `seedFromFilePath` path and that the dump matches the driver.\n- _Want a clean slate?_ `corgi stop` tears down a detached run; `corgi clean -i db,corgi_services` drops the databases and generated files (add `services` to also remove the cloned repos).\n\n### Secrets \u0026 env files\n\ncorgi writes each service's `.env` for you — DB host/port/credentials, sibling-service URLs — and sources it before your commands run. On first init it also adds `.env*` and `corgi_services/*` to your project's `.gitignore`, so **generated env files and any secrets in them never get committed**. Your own secrets (API keys, tokens) go in a service's env or a tier file like `env/staging/web.env` — also gitignored, also staying on your machine. The `corgi-compose.yml` itself holds config, not secrets, so it's safe to commit and share.\n\n**What gets wired.** A `depends_on_db` edge writes the database's connection vars — for Postgres that's `DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_USER`, `DB_PASSWORD`; other drivers use their own prefix (`REDIS_`, `MYSQL_`, `MONGO_`, …), and `envAlias:` renames it (`envAlias: DATABASE` → `DATABASE_HOST`, …). A `depends_on_services` edge writes `\u003cSERVICE\u003e_URL` (e.g. `API_URL=http://localhost:7012`). Run `corgi env \u003cservice\u003e` to see the exact, fully-resolved set a service will get, and where each value came from.\n\n**Low lock-in:** your services stay ordinary git repos, your databases are standard Docker images (corgi even writes a plain `docker-compose.yml` per database under `corgi_services/db_services/`), and the wiring is just `.env` files. Stop using corgi and you keep all of it.\n\n## Supported databases \u0026 services\n\nIn `services` you can run anything you like. In `db_services`, corgi ships managed drivers that handle the container, seeding, a native shell, and env vars for you. A couple are whole stacks rather than single containers — `localstack` stands up a fleet of AWS services, and `supabase` brings up auth, storage, and studio — all from the same file.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e38 database \u0026 infra drivers\u003c/strong\u003e (click to expand)\u003c/summary\u003e\n\n- [postgres](https://www.postgresql.org), [example](https://github.com/Andriiklymiuk/corgi_examples/tree/main/postgres)\n- [mongodb](https://www.mongodb.com), [example](https://github.com/Andriiklymiuk/corgi_examples/blob/main/mongodb/mongodb-go.corgi-compose.yml)\n- [rabbitmq](https://www.rabbitmq.com), [example](https://github.com/Andriiklymiuk/corgi_examples/blob/main/rabbitmq/rabbitmq-go-nestjs.corgi-compose.yml)\n- [sqs](https://docs.localstack.cloud/user-guide/aws/sqs/) — local AWS SQS, [example](https://github.com/Andriiklymiuk/corgi_examples/blob/main/aws_sqs/aws_sqs_postgres_go_deno.corgi-compose.yml)\n- [s3](https://docs.localstack.cloud/user-guide/aws/s3/) — local AWS S3 buckets\n- [redis](https://redis.io), [example](https://github.com/Andriiklymiuk/corgi_examples/blob/main/redis/redis-bun-expo.corgi-compose.yml)\n- [redis-server](https://redis.io)\n- [mysql](https://www.mysql.com)\n- [mariadb](https://mariadb.org)\n- [dynamodb](https://aws.amazon.com/dynamodb/)\n- [kafka](https://kafka.apache.org)\n- [mssql](https://www.microsoft.com/en-us/sql-server/sql-server-downloads)\n- [cassandra](https://cassandra.apache.org/_/index.html)\n- [cockroach](https://www.cockroachlabs.com)\n- [clickhouse](https://clickhouse.com)\n- [scylla](https://www.scylladb.com)\n- [keydb](https://docs.keydb.dev)\n- [influxdb](https://www.influxdata.com)\n- [surrealdb](https://surrealdb.com)\n- [neo4j](https://neo4j.com)\n- [arangodb](https://arangodb.com)\n- [elasticsearch](https://www.elastic.co/elasticsearch#)\n- [timescaledb](https://www.timescale.com)\n- [couchdb](https://couchdb.apache.org)\n- [dgraph](https://dgraph.io)\n- [meilisearch](https://www.meilisearch.com)\n- [mailpit](https://mailpit.axllent.org) — mail-mock SMTP + web UI (the local mail server Supabase uses); web UI port via `port2`\n- [faunadb](https://fauna.com)\n- [yugabytedb](https://www.yugabyte.com)\n- [skytable](https://skytable.io)\n- [dragonfly](https://www.dragonflydb.io)\n- [redict](https://redict.io)\n- [valkey](https://github.com/valkey-io/valkey)\n- [postgis](https://postgis.net)\n- [pgvector](https://github.com/pgvector/pgvector) — postgres + `pgvector` extension. Uses prefix `DB_`, same as plain `postgres`\n- [localstack](https://docs.localstack.cloud/) — single container for multiple AWS services (sqs, s3, sns, secretsmanager, ssm, kinesis), with `queues` / `buckets` / `topics` / `secrets` auto-created from config. Full docs: [docs/drivers/localstack.md](docs/drivers/localstack.md)\n- [supabase](https://supabase.com/docs/guides/local-development) — wraps `supabase init`/`start`. Emits `SUPABASE_*` + S3 vars, ports from config.toml. Seeds `buckets:` and `authUsers:` on `up`; `jwtSecret:` re-signs keys; `configTomlPath:` makes corgi own config.toml under `corgi_services/`; `port:`/`dbPort:`/`studioPort:`/`inbucketPort:` patch the matching `[section].port`. Full docs: [docs/drivers/supabase.md](docs/drivers/supabase.md)\n- `image` — generic docker-image driver for any public image (gotenberg, mailhog, jaeger, meilisearch, …). Set `image:` + `port:` + optional `containerPort:`/`environment:`/`volumes:`/`command:`. Full docs: [docs/drivers/image.md](docs/drivers/image.md)\n\n\u003c/details\u003e\n\n**Once a database is up**, corgi keeps helping:\n\n- **Seed it** with real data from a file (`seedFromFilePath:`) or another database (`seedFromDb:`). `corgi run --seed` loads it; the dump format is chosen per driver automatically.\n- **Open a shell** with `corgi db shell [name]` — the right tool (`psql`, `mongosh`, `redis-cli`, …) with credentials already filled in. Add `-e '\u003cquery\u003e'` to run one query and exit.\n- **Manage them** from the `corgi db` menu — bring containers up or down, seed, or dump.\n\n## Working across many repos\n\nThis is the part `docker-compose` leaves to you. Corgi treats your repos as part of the stack:\n\n- **Auto-clone** — a service with `cloneFrom:` is cloned the first time its folder is missing. `cloneFrom:` is optional — a service with just a `path:` (a monorepo subfolder, or a repo you keep checked out yourself) is used in place, no cloning. Mix both freely in one file.\n- **`corgi pull`** — `git pull` everything at once, including nested corgi projects.\n- **`corgi fork`** — fork the cloned repos to your own GitHub/GitLab and update the file to match.\n- **Run a service on a branch** — point one service at a branch or another folder for a single run, no file edit needed:\n\n```bash\n# run api's feature branch in its own worktree — your checkout stays exactly as it is\ncorgi run --service-branch api=feature/login\n\n# mix and match: api on a branch, web from a folder, everything else as usual\ncorgi run --service-branch api=feature/login --service-dir web=/tmp/wt/web\n\n# or actually switch the checkout in place (refuses if you have uncommitted changes)\ncorgi run --service-checkout api=hotfix/x\n```\n\nThe worktrees live under `corgi_services/.worktrees/` and are reused between runs, so dependencies and uncommitted work stick around. List or clean them with `corgi worktree list` / `corgi worktree prune`. Great for trying a PR branch, comparing two branches side by side on different ports, or letting an agent work on a branch while you keep running `main`.\n\n## The rest of the toolbox\n\n**Check before you run.** `corgi doctor` confirms your required tools are installed, Docker is running, and the ports are free — and tells you which process is hogging a port if one isn't. Add `--fix` and it'll start Docker, install what's missing, and free the ports for you.\n\n**Watch it stay healthy.** `corgi status` pings every service. Use `-w` to watch live, or `-r` to block until everything's ready (handy in scripts). Set a `healthCheck:` path on a service and corgi will hit it over HTTP instead of just checking the port.\n\n**Keep it running in the background.** `corgi run -d` starts everything detached and returns right away — no daemon, corgi just remembers what it started. Check in with `corgi ps`, restart one piece with `corgi restart --service api`, or stop it all with `corgi stop`.\n\n**Read the logs later.** `corgi run --logs` saves each service's output; `corgi logs` lets you browse and follow past runs, with crashes clearly marked.\n\n**Get pinged on a crash.** `corgi notifications on` sends a desktop notification when a service falls over mid-run.\n\n**Share a local service over HTTPS.** `corgi tunnel` gives your services public URLs — perfect for testing webhooks (Stripe, GitHub apps, e-sign callbacks) without any signup:\n\n```bash\ncorgi tunnel                       # tunnel every service that has a port\ncorgi tunnel api                   # just one\ncorgi tunnel --port 3030           # a raw port, skip the compose lookup\ncorgi tunnel --provider ngrok      # default is cloudflared (free, no signup)\n```\n\nBy default it uses [Cloudflare Quick Tunnels](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/do-more-with-tunnels/trycloudflare/) — free and anonymous, but the URL changes every restart. For a stable URL, use a Cloudflare named tunnel (login required) or another provider. If a provider needs auth, corgi tells you the exact login command up front instead of failing halfway.\n\n## AI agents, MCP \u0026 Claude Code\n\ncorgi is meant to be driven by AI agents and CI, not just typed by hand. It's a small single Go binary — no daemon, no runtime to install — that notices when it's running in an agent or pipeline and never blocks on a prompt, prints clean JSON with `--json`, and returns predictable exit codes (`0` ok, `1` failed, `2` bad usage) plus a documented [error-code list](docs/agents.md) — so a tool can read what happened and react. That same non-interactive contract is exactly what a CI job needs, so it's light to drop into one. There are quiet, scriptable entry points too: `corgi env` (the exact env a service will see, and where each value came from), `corgi exec`, `corgi test`, and `corgi run --dry-run --json` to preview a run without touching anything. `corgi mission-control` (alias `mc`) is the one-glance view — the live stack plus each service's git/PR/CI state — with `--json` for a single snapshot or `--watch` to follow it. And `corgi memory` is an opt-in, committed `.corgi/memory/` store of stack decisions and recurring fixes (with a `corgi memory lint` secret-scan) that the skills read before acting. Full guide: [docs/agents.md](docs/agents.md).\n\n### MCP server\n\nRun `corgi mcp` and any MCP-speaking agent can control your stack through proper tools instead of guessing at shell commands. It runs over stdio by default (no network at all), or over HTTP with `--http` / `--tunnel` when you want it remote. It exposes around a dozen tools — bring up, tear down, status, env, exec, test, logs, db queries — plus read-only resources like the compose schema and live status. One caution: plain `--http` has no auth; corgi only adds a bearer token when you expose it through a public tunnel. Full docs: [docs/mcp.md](docs/mcp.md).\n\n### Claude Code plugin\n\nIf you use [Claude Code](https://claude.com/claude-code), install the plugin:\n\n```\n/plugin marketplace add Andriiklymiuk/corgi\n/plugin install corgi@corgi\n```\n\nUsing another agent (Cursor, Codex, Copilot, …)? Install the skills via [skills.sh](https://www.skills.sh):\n\n```\nnpx skills add Andriiklymiuk/corgi\n```\n\nNow Claude recognizes any project with a `corgi-compose.yml` and reaches for real `corgi run` / `corgi doctor` / `corgi status` commands instead of inventing its own. The plugin adds slash-commands plus auto-invoking skills that cover the whole loop — plan, run, debug, suggest, ship, review:\n\n- **Plan the work — `/corgi-tracker`.** Standup / status, triage, or decompose an epic into tickets — from Linear or Jira. Its edge over the tracker's own UI: it ties each ticket to its **real code state** — branch, draft/open/merged PR, CI — across every service, so drift like \"In Progress but no branch\" or \"Todo but the PR already merged\" surfaces. Read-only until one confirm gate guards any tracker write; hands the tickets it shapes to `/corgi:stories`.\n- **Drain the queue — `/corgi-queue`.** Pick up build-ready tickets and build them — pass explicit Linear/Jira links, or a scope in plain words (the **`agent`** queue by default; also _in ready_, _from backlog_, _most impactful/ROI_, _bugs_). It drift-skips anything already merged or in-flight, you confirm the picks, then `/corgi:stories` branches per service and opens draft PRs — moving each ticket to In-Progress as work starts (which stops a loop from grabbing it twice). `/loop 1h /corgi-queue` drains on a schedule; you approve each batch's specs in one sign-off.\n- **Autopilot the loop — `/corgi-autopilot`.** A supervised loop that drains the agent queue into draft PRs — one spec gate per batch, a heartbeat, and a kill switch (`corgi autopilot stop`/`pause`/`status`). Schedule it with `/loop` or `/schedule`; it never merges.\n- **Run it — `/corgi-run`.** \"Run the stack\" — or a slice, with a tunnel + logs, against a remote backend, for a mobile emulator, or a single service on a feature/PR branch or worktree (`--service-branch`/`--service-dir`, the reviewer \"Run line\"). Boots **detached**, waits until healthy, and flags anything stuck.\n- **Debug it — `/corgi-debug`.** A service won't start, or you're chasing a bug and need runtime/deployed data. Local-first (`ps` / `status` / `doctor` / `logs`), then your stack's own logs/analytics provider (Coralogix, CloudWatch/ECS, Datadog… — auto-detected from your README) on demand.\n- **Suggest work — `/corgi-suggest`.** Ranked, evidence-backed product **and** engineering improvements, each tied to a measurable outcome; it specs the one you pick and can open a tracker story.\n- **Suggest on a schedule — `/corgi-suggest-proactive`.** The same ranking, pushed on a cadence: it takes the top idea, dedupes against open and recently-dismissed tickets (`corgi suggest-history`), and either proposes it or — only if you opt in — files exactly **one** rate-limited **draft** ticket. Never assigned, never built.\n- **Ship a batch — `/corgi:stories`.** Hand Claude some tracker issues (Linear or Jira) or just describe a feature. It investigates the codebase, writes a short spec for each item and waits for your sign-off, then branches per service, runs the tests, reviews its own changes, and opens **draft** PRs/MRs — each service in its own git worktree.\n- **Review the result — `/corgi:review`.** Point it at the PRs/MRs. It reviews them against your repo's standards and any linked ticket, checks that changes line up across services, and — after you preview — posts a summary plus inline suggestions. It also runs the **other way**: _\"fix the comments on this MR and answer them\"_ (or by story-id) — it applies the valid feedback, replies to and resolves the threads, and pushes the fixes to your branch.\n\n```\n/corgi-tracker                       # standup / triage / decompose, tied to real PR + CI state\n/corgi-queue                         # build the `agent` queue → draft PRs\n/corgi-queue most impactful          # or: in ready · from backlog · bugs · ABC-140 ABC-141\n/loop 1h /corgi-queue                # keep draining on a schedule (you approve each batch)\n/loop 1h /corgi-autopilot            # supervised loop: drain the queue → draft PRs (one gate/batch)\n/corgi-run                           # boot the stack detached, wait until healthy\n/corgi-debug                         # diagnose a service / pull deployed or CI logs\n/corgi-suggest                       # ranked, measurable improvement ideas\n/corgi:stories ABC-123 ABC-124       # spec → branch per service → draft PRs\n/corgi:review  \u003cpr-url\u003e              # review a PR — or \"fix the comments on this MR\"\n```\n\nShip and review wait for your go-ahead and only ever open **draft** PRs — they never merge or ship on their own. Two more helpers round things out: **`/corgi-new`** scaffolds a fresh `corgi-compose.yml` from a quick chat, and **`/corgi-describe`** writes a service map with a Mermaid diagram.\n\n#### Working the loop — say it however you'd say it\n\nNo slash-commands or jargon needed — talk to it like a teammate; it routes on **intent, not exact words**. The four jobs, the way people actually ask:\n\n- _\"How's the team doing — anything stuck?\"_ → a status read leading with blockers and **drift** (\"In Progress but no branch\", \"Done but the PR's still open\").\n- _\"Pile of new bug reports — sort and prioritize them?\"_ → labels, priorities, duplicates, and what needs more info, behind one confirm (triage).\n- _\"I want a referral program — break it into tasks across the services.\"_ → ordered, service-mapped tickets you approve, then build (decompose).\n- _\"I just joined — what should I pick up first?\"_ → it pulls the build-ready **`agent`** queue (or tickets you name), you confirm, and stories builds them into draft PRs.\n\n**What fires when you pick work.** Picking one ticket engages the loop: tracker correlates + drift-skips → stories builds (reads `corgi-compose.yml`, calls **debug** for runtime/staging or CI data, stands a producer up with **`corgi run`** so a consumer can verify, self-reviews, moves the ticket to In-Progress + assigns you, then Code Review when the draft PR opens) and points you to _review it_ / _run it_ / _debug it_ before you land it. **suggest** sits upstream — it proposes work before it's even a ticket. Full walkthrough: [docs/tracker.md](docs/tracker.md).\n\n## How it compares\n\nThe honest version of \"why not just use X\":\n\n- **vs `docker-compose`** — Compose runs containers; that's where it stops. corgi runs your whole inner loop: it clones the repos, runs and seeds the databases (it even generates a real `docker-compose.yml` per database under the hood), wires the env between services, checks your tools, and runs your services as ordinary host processes — so you keep your usual debugger and hot-reload, and your laptop runs N processes instead of N containers (lighter on RAM). Already have a Compose file? Keep it — let corgi own the repos, env wiring, and tool checks while Compose runs your containers; the two coexist fine.\n- **vs Tilt / Skaffold** — Great when your inner loop is Kubernetes and you want live container rebuilds. corgi deliberately keeps your services out of containers — no image rebuild between edits — so it's lighter for a \"repos + databases + processes\" stack, and not the tool if you genuinely need k8s.\n- **vs Procfile runners (foreman / overmind)** — They start a list of processes. corgi does that _and_ the repos, databases, seeding, env wiring, and tool checks around them.\n- **vs devcontainers / Nix** — These give you a more isolated, prebuilt environment — Nix in particular is fully hermetic. corgi takes the opposite bet: it runs on your real machine with your real tools, and its `required:` block still installs and pins exactly what each service needs (a `pyenv`/`rbenv` version, native libs, certs). Simpler to live in day to day; it's not a hermetic sandbox, by design.\n\n**What corgi isn't:** a deploy tool. It runs and tests your stack locally — shipping to staging/prod stays with your CI/CD (you test with corgi, then deploy as usual). It's also not the fit if your dev loop must run _inside_ Kubernetes, or if you want a fully sandboxed, OS-level environment (devcontainers/Nix territory).\n\n## Security \u0026 scope\n\ncorgi runs your stack on your own machine — the local inner loop — and can point local services at a staging or prod environment via env tiers. A few things worth knowing:\n\n- A `corgi-compose.yml` runs its `beforeStart` / `start` commands on your machine, so only run files you trust — especially `corgi run -t \u003curl\u003e`, which downloads and runs a remote one.\n- `corgi doctor --fix` starts Docker for you automatically, but **installing a tool or killing a port-holding process always asks first** (or needs `--yes` in CI).\n- `corgi mcp` runs over stdio (local, no network) by default. `--http` is **unauthenticated** — only expose it with `--tunnel`, which adds a bearer token. Its tools can start, stop, and run commands in your stack, so treat that URL + token like a credential.\n- `corgi tunnel` gives a local service a public HTTPS URL — exactly what you want for testing signing/webhook callbacks from an outside tool. The default Cloudflare quick-tunnel URL is public and ephemeral, so shut it down when you're done.\n- **No telemetry.** corgi collects no analytics and sends nothing about your usage anywhere — it runs entirely on your machine. The only outbound call it makes on its own is `corgi update` checking GitHub for a newer release.\n\n## Documentation\n\n- Full docs: https://andriiklymiuk.github.io/corgi/\n- 2-min video showcase: https://youtu.be/rlMCjs4EoFs?si=o3SQaymM55zxBCUY\n- Driving corgi from a script or agent? See [docs/agents.md](docs/agents.md) and [docs/mcp.md](docs/mcp.md).\n- Planning + picking up work from your tracker (Linear/Jira)? See [docs/tracker.md](docs/tracker.md).\n\n### VSCode users\n\nInstall the [corgi extension](https://marketplace.visualstudio.com/items?itemName=corgi.corgi) for syntax highlighting, autocompletion, and one-click commands.\n\n## Install\n\nOnce installed, `corgi` works from any folder.\n\n### macOS / Linux — [Homebrew](https://brew.sh)\n\n```bash\nbrew install andriiklymiuk/homebrew-tools/corgi\n```\n\n### macOS / Linux — install script\n\nNo Homebrew? This one-liner grabs the right binary for your OS/arch from GitHub releases:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/Andriiklymiuk/corgi/main/install.sh | sh\n```\n\nIt verifies the release's sha256 checksum before installing, to `/usr/local/bin` if it can, otherwise `~/.local/bin` (and adds it to your PATH for zsh/bash/fish).\n\nA few optional overrides:\n\n- `CORGI_VERSION=1.10.0` — pin a version\n- `CORGI_INSTALL_DIR=$HOME/bin` — force a directory\n- `CORGI_NO_MODIFY_PATH=1` — don't touch shell rc files\n\n### Windows — PowerShell\n\n```powershell\nirm https://raw.githubusercontent.com/Andriiklymiuk/corgi/main/install.ps1 | iex\n```\n\nInstalls to `%LOCALAPPDATA%\\corgi\\bin` and adds it to your user PATH.\n\n### Windows — [Scoop](https://scoop.sh)\n\n```powershell\nscoop bucket add corgi https://github.com/Andriiklymiuk/scoop-bucket\nscoop install corgi\n```\n\n### [mise](https://mise.jdx.dev) (tool/version manager)\n\n```bash\nmise use -g github:Andriiklymiuk/corgi\n```\n\nReads corgi's GitHub releases directly — no registry config needed.\n\n### [pkgx](https://pkgx.sh)\n\n```bash\npkgx corgi run        # one-off, no install\npkgx install corgi    # to PATH\n```\n\n### Verify\n\n```bash\ncorgi -h\n```\n\n`corgi update` (alias `corgi upgrade`) notices how you installed corgi and upgrades the same way. corgi is a single binary on a steady semver release train (1.x) — pin the whole team to one version with `CORGI_VERSION` (install script) or mise, so everyone runs the same corgi.\n\nWant to try it cold? Run the expo + hono example straight from a URL:\n\n```bash\ncorgi run -t https://github.com/Andriiklymiuk/corgi_examples/blob/main/honoExpoTodo/hono-bun-expo.corgi-compose.yml\n```\n\n### Shell tab-completion\n\nBrew installs `_corgi` (zsh), `corgi.bash`, `corgi.fish` automatically. After that:\n\n- `corgi run --services \u003cTAB\u003e` → service names from `corgi-compose.yml`\n- `corgi run --dbServices \u003cTAB\u003e` → db_services\n- `corgi script -n \u003cTAB\u003e` → script names per service (filters by `--services` if set)\n- `corgi tunnel \u003cTAB\u003e` → tunnelable services\n- `corgi clean -i \u003cTAB\u003e` → clean targets — and completions are wired for `corgi tunnel --provider`, `corgi run --omit`, and the global `--dockerContext` / `--fromTemplateName` too\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eCompletion showing filenames instead of names? (zsh fpath / Linux setup)\u003c/strong\u003e\u003c/summary\u003e\n\n**zsh users — if `\u003cTAB\u003e` shows files instead of names**, your shell isn't loading brew's site-functions dir. One-time fix in `~/.zshrc` (works for every brew CLI, not just corgi):\n\n```sh\n# macOS Apple Silicon\nFPATH=\"/opt/homebrew/share/zsh/site-functions:$FPATH\"\n# macOS Intel\nFPATH=\"/usr/local/share/zsh/site-functions:$FPATH\"\n# Linux (linuxbrew)\nFPATH=\"/home/linuxbrew/.linuxbrew/share/zsh/site-functions:$FPATH\"\n\nautoload -Uz compinit \u0026\u0026 compinit\n```\n\nAdd it BEFORE any existing `compinit` call. Then `rm -f ~/.zcompdump* \u0026\u0026 exec zsh`.\n\nWhy: brew drops completions in `\u003cbrew-prefix\u003e/share/zsh/site-functions/`, but plain zsh doesn't include that path in `$fpath` by default — so the file is installed but never loaded. Same gap affects `gh`, `kubectl`, `helm`, etc.\n\n**Linux native package managers** (apt/dnf/pacman) — corgi isn't packaged there yet. Use the install script (`curl ... install.sh | sh`), then generate the completion script manually:\n\n```sh\n# zsh\nmkdir -p ~/.zsh/completions\ncorgi completion zsh \u003e ~/.zsh/completions/_corgi\n# add once to ~/.zshrc:\nfpath=(~/.zsh/completions $fpath); autoload -Uz compinit \u0026\u0026 compinit\n\n# bash (needs bash-completion package)\ncorgi completion bash | sudo tee /etc/bash_completion.d/corgi \u003e/dev/null\n\n# fish\ncorgi completion fish \u003e ~/.config/fish/completions/corgi.fish\n```\n\n\u003c/details\u003e\n\n## Credits \u0026 thanks\n\n- `corgi tunnel` defaults to [cloudflared](https://github.com/cloudflare/cloudflared) ([Apache 2.0](https://github.com/cloudflare/cloudflared/blob/master/LICENSE)) and its free, no-signup [Quick Tunnels](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/do-more-with-tunnels/trycloudflare/). Big thanks to Cloudflare for shipping this open and free — makes local webhook testing painless.\n- Optional providers: [ngrok](https://ngrok.com) (closed source, free tier with authtoken) and [localtunnel](https://github.com/localtunnel/localtunnel) ([MIT](https://github.com/localtunnel/localtunnel/blob/master/LICENSE)) — thanks to both projects for the alternatives.\n- \u003ca href=\"https://www.freepik.com/free-vector/cute-corgi-dog-astronaut-floating-space-cartoon-vector-icon-illustration-animal-science-icon-concept-isolated-premium-vector-flat-cartoon-style_22271104.htm#query=corgi%20icon\u0026position=7\u0026from_view=keyword\"\u003eCorgi image by catalyststuff\u003c/a\u003e on Freepik\n\u003c/content\u003e\n\u003c/invoke\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandriiklymiuk%2Fcorgi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fandriiklymiuk%2Fcorgi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fandriiklymiuk%2Fcorgi/lists"}