Skip to main content

AI agents

corgi is designed to be driven by AI agents and scripts, not only typed by hand. It detects non-interactive environments and never hangs on a prompt, speaks pure JSON when asked, and exposes stable exit and error codes an agent can branch on - so an LLM can run your stack, read real status, and fix the right thing.

Non-interactive mode​

corgi auto-detects when it must not prompt and either skips the prompt or exits with a clear error (exit code 2) instead of hanging. It triggers on:

  • a CI env var (CI=true, …);
  • an agent env var: CLAUDECODE, CLAUDE_CODE, ANTHROPIC_AGENT;
  • no TTY on stdin or stdout (piped / redirected).

Force prompts back on with the global --interactive flag.

JSON output​

The global --json flag makes stdout a pure machine-readable payload; human and log lines go to stderr. Errors have a stable shape:

{ "error": { "code": "E_PORT_CONFLICT", "message": "..." } }

The code is a stable string to branch on. Commands with pure-JSON stdout include status, doctor, list, config, ps, open, logs, restart, and db shell -e.

Detached lifecycle​

corgi run --detach (-d) starts every service as a detached process group that survives corgi exiting, writes .corgi/corgi_services/.state.json, and returns immediately. Inspect and control it without a daemon:

corgi run --detach --json        # start, print run-state, return
corgi status --ready --timeout 60s   # block until everything is healthy
corgi ps --json                  # running / crashed / stopped from state
corgi stop                       # stop everything from state

Run a branch without touching the repo​

Agents often need to run a specific branch - a PR under review, or their own work - without disturbing the developer's checkout. Use --service-branch, which runs the service from an isolated, reused git worktree:

corgi run --detach --service-branch api=feature/login

One agent can run a branch while another runs main, each isolated. Full details: Run a branch or worktree.

Safe agent recipe​

corgi doctor --json || exit 1                 # ports free, docker up, tools present
corgi run --detach --json                     # launch, returns immediately
corgi status --ready --timeout 90s || exit 1  # block until healthy
corgi ps --json                               # inspect real status
# ... do work ...
corgi stop

Install corgi's skills​

Claude Code - one marketplace, one plugin:

/plugin marketplace add Andriiklymiuk/corgi
/plugin install corgi@corgi

or from a shell:

claude plugin marketplace add Andriiklymiuk/corgi
claude plugin install corgi@corgi

Restart Claude Code afterwards: a newly installed plugin's skills appear on the next start.

Any other agent - Codex, Cursor, Cline, Droid, Antigravity and the rest read the same skills through the skills CLI:

npx skills add Andriiklymiuk/corgi

It writes them to .agents/skills/ and wires up whichever agent it finds. Use one method or the other, not both.

Or paste this at your agent and let it do the reading:

Install corgi's agent skills: run npx skills add Andriiklymiuk/corgi, or read them directly from https://github.com/Andriiklymiuk/corgi/tree/main/plugins/corgi/skills

  • run boots the stack, debug diagnoses it, stories ships tracker tickets as draft PRs, review reviews existing PRs, ship releases a mobile app. Then use them on this project: it has a corgi-compose.yml, so prefer corgi run / corgi doctor / corgi status over inventing commands.

It adds:

  • /corgi-run - boot the stack (or a slice) detached and wait until healthy; tunnel, logs, remote-backend, emulator-host, and per-service branch/worktree (--service-branch/--service-dir) modes included.
  • /corgi-debug - diagnose a stack local-first (ps/status/doctor/logs), or pull runtime/deployed logs for a bug from your stack's own provider (Coralogix, CloudWatch/ECS, Datadog… - auto-detected from your README), on demand.
  • /corgi-ci - generate (or fix) the CI pipeline that boots the whole stack and runs cross-repo e2e on every PR - GitHub Actions or GitLab CI, with caching, health gates, and log artifacts baked in. See Run the stack in CI.
  • /corgi-suggest - ranked, evidence-backed product + engineering improvements, each tied to a measurable outcome; specs the one you pick and can open a tracker story.
  • corgi:stories - turn tracker issues or a feature description into spec'd, tested, reviewed draft PRs (each service in its own worktree).
  • corgi:review - review existing GitHub/GitLab PRs/MRs against your repo's standards and the linked ticket.
  • /corgi-new (scaffold a compose file) and /corgi-describe (service map + Mermaid diagram).