Examples

Watch CogOS work.
Over the shoulder.

Real walkthroughs showing every step, every agent, and every decision CogOS makes. Pick a scenario and follow along.

Build a production-ready REST API in 90 seconds

You need a FastAPI backend with PostgreSQL, auth, tests, and docs. CogOS decomposes this into parallel agent tasks, produces working code, and validates the result before you see it.

Planner Architect Coder Tester cog-code-python cog-db-postgres cog-api-rest python.lint python.test
Planner
decompose
Architect
design
Researcher
gather context
Coder
implement
Tester
verify
Reviewer
approve
1

The Planner breaks the task into 5 subtasks — project scaffold, database models, auth logic, API routes, and test suite. Each subtask is routed to the agent best suited for it. The Python and PostgreSQL modules inject domain-specific prompt extensions so every agent writes idiomatic code.

bash — cog run
$ cog run "Build a FastAPI REST API with PostgreSQL, JWT auth, and tests"
 
[planner] Decomposing task into subtasks...
[planner] 5 subtasks identified (complexity: medium)
[modules] Activated: code-core, cog-code-python, cog-db-postgres, cog-api-rest
[cache] No cache hit — new task pattern
 
[architect] Designing: layered architecture (routes → services → models)
[architect] Schema: users, items, auth_sessions
 
[researcher] Gathering FastAPI 0.115 + SQLAlchemy 2.0 best practices...
[researcher] 18 patterns found
 
[coder] Step 1/5: Generating project scaffold...
Created: app/ main.py config.py requirements.txt
[coder] Step 2/5: Generating database models...
Created: app/models.py (User, Item, AuthSession)
[coder] Step 3/5: Generating auth service...
Created: app/auth.py (JWT + bcrypt)
[coder] Step 4/5: Generating API routes...
Created: app/routes/ (users.py, items.py, auth.py)
[coder] Step 5/5: Generating Alembic migrations...
Created: alembic/ alembic.ini
2

The Coder writes real, importable Python — not pseudocode. Each file follows FastAPI conventions the Researcher agent found. The cog-code-python module ensures async patterns, type hints, and Pydantic models are used correctly.

Agent Activity
planner
8s
architect
14s
researcher
22s
coder
42s
tester
26s
reviewer
10s
bash — validation & results
[tester] Generating test suite...
Created: tests/ test_auth.py test_routes.py test_models.py
 
[tool] python.test — running pytest...
================== test session starts ==================
collected 24 items
 
tests/test_auth.py ....... [ 29%]
tests/test_routes.py ............. [ 83%]
tests/test_models.py .... [100%]
 
24 passed in 1.82s
 
[tool] python.lint — running ruff check...
0 errors, 0 warnings
 
[reviewer] Code quality: excellent. All checks passed.
[cache] Pattern stored for future reuse
 
Result: SUCCESS
Tokens: 12,847 | Iterations: 6 | Files: 9 | Tests: 24/24
9
Files generated
24/24
Tests passing
~90s
Wall time
12.8k
Tokens used

Debug a failing production service end-to-end

A Python worker is crashing with a cryptic database error at 3 AM. CogOS traces the error path, identifies the root cause, writes the fix, and generates a regression test — all before your coffee is ready.

Researcher Coder Tester Reviewer cog-code-python cog-db-postgres filesystem.read shell.execute

Step 1: Read the error traceback

CogOS reads the failing file and the traceback. The Researcher agent identifies the stack: worker.pydb_client.pypsycopg2.OperationalError: connection pool exhausted.

Step 2: Trace the connection pool logic

The cog-db-postgres module tells CogOS that psycopg2 pool exhaustion usually means connections aren't being returned. CogOS uses filesystem.read to inspect db_client.py and finds a missing finally block.

Step 3: Identify the root cause

The reviewer confirms: get_connection() checks out a pool connection but early returns on error without returning it. Over time this drains the pool.

bash — original error
$ cog run "Fix this error: OperationalError: connection pool exhausted"
 
[tool] filesystem.read db_client.py
[researcher] Analyzing connection pool pattern...
[researcher] Root cause: missing connection return on error path (line 47)
 
psycopg2.OperationalError: connection pool exhausted
 
File "worker.py", line 23, in process_job
  conn = db.get_connection()
File "db_client.py", line 47, in get_connection
  return self.pool.getconn()
!

The bug is subtle. The get_connection() function has a try/except that catches auth errors and returns None — but the connection was already checked out from the pool before the auth check. Returning None leaks the connection. CogOS found this because the cog-db-postgres module flagged pool-exhaustion as a known pattern.

bash — fix applied
[coder] Generating fix...
Patched: db_client.py (added finally block with pool.returnconn)
 
- def get_connection(self):
-     conn = self.pool.getconn()
-     if not self._validate(conn):
-         return None  # BUG: leaks conn
 
+ def get_connection(self):
+     conn = self.pool.getconn()
+     try:
+         if not self._validate(conn):
+             self.pool.returnconn(conn)
+             return None
+         return conn
+     except Exception:
+         self.pool.returnconn(conn)
+         raise
 
[tester] Generating regression test...
Created: tests/test_db_pool.py (6 tests for connection lifecycle)
[tool] python.test
6 passed in 0.34s
1
Bug fixed
6
Regression tests
~45s
Wall time
0
Lint warnings

Containerize and deploy to AWS ECS

You have a working app and need it on AWS with Docker, an ECS task definition, a load balancer, and a CI/CD pipeline. CogOS uses its cloud and container modules to generate everything you need.

Planner Architect Coder cog-cloud-aws cog-infra-docker cog-infra-kubernetes aws.ec2.list
Dockerfile
containerize
ECR Push
image registry
ECS Task
task def
ALB
load balance
Live
verified
1

The Planner maps the full deployment pipeline. The cog-cloud-aws module knows ECS, ECR, ALB, and IAM conventions. The cog-infra-docker module ensures multi-stage builds and proper layer caching. Together they produce production-grade configs, not toy examples.

bash — deployment generation
$ cog run "Deploy this FastAPI app to AWS ECS with Docker and an ALB"
 
[modules] Activated: cog-cloud-aws, cog-infra-docker
[planner] 6 subtasks: Dockerfile, ECR repo, ECS task, ALB target, IAM roles, health check
 
[coder] Step 1/6: Generating multi-stage Dockerfile...
Created: Dockerfile (3 stages, 128MB final image)
[coder] Step 2/6: Generating ECR push script...
Created: scripts/push-ecr.sh
[coder] Step 3/6: Generating ECS task definition...
Created: ecs/task-definition.json (1 vCPU, 512MB, 1 replica)
[coder] Step 4/6: Generating ALB + target group config...
Created: terraform/alb.tf, terraform/main.tf
[coder] Step 5/6: Generating IAM task role...
Created: terraform/iam.tf (least-privilege policy)
[coder] Step 6/6: Generating health check endpoint...
Patched: app/main.py (added GET /health)
 
[tool] aws.ec2.list — verifying region us-east-1...
AWS credentials valid. Region: us-east-1
 
[reviewer] All configs follow AWS well-architected practices
Result: SUCCESS — 8 files generated
2

Why Terraform? The Architect agent chose it over raw AWS CLI scripts because the cog-cloud-aws module's prompt extensions recommend IaC for any deployment with more than 2 resources. The IAM role is scoped to exactly the permissions the ECS task needs — no wildcard actions.

8
Files generated
128MB
Docker image
~70s
Wall time
6
Subtasks

Scaffold a full-stack app with tests, CI, and docs

Start from nothing — a blank directory — and end up with a React frontend, FastAPI backend, PostgreSQL database, test suites, a GitHub Actions CI pipeline, and documentation. CogOS coordinates all 10 agents across the full stack.

Planner Architect Researcher Coder Tester Documenter Reviewer Optimizer cog-code-python cog-lang-javascript cog-db-postgres cog-web-css cog-git
Agent Activity
planner
10s
architect
28s
researcher
40s
coder
78s
tester
44s
reviewer
20s
1

All 10 agents contribute. The Planner decomposes into 8 subtasks. The Architect designs the folder structure and API contract. The Researcher gathers React 18 + FastAPI patterns. The Coder generates 22 files across frontend and backend. The Tester writes 38 tests. The Documenter writes a README. The Reviewer checks everything.

bash — full-stack scaffold
$ cog run "Build a task tracker app: React frontend, FastAPI backend, Postgres DB, tests, CI, docs"
 
[planner] 8 subtasks: scaffold, DB models, API, frontend, auth, tests, CI, docs
[architect] Monorepo layout: frontend/ backend/ shared/ .github/
 
╔════════════════════════════════╦══════════════════════╝
backend/ ........................ frontend/ ....................
├── app/ ........................ ├── src/ ....................
│  ├── main.py ................. │  ├── App.tsx .................
│  ├── models.py ............... │  ├── components/ ...........
│  ├── routes/ ................. │  ├── hooks/ .................
├── tests/ .................... ├── tests/ ....................
╚════════════════════════════════╦══════════════════════╝
 
[coder] 22 files generated across frontend + backend
[tester] Running backend tests...
24 passed
[tester] Running frontend tests (vitest)...
14 passed
 
[coder] Generating .github/workflows/ci.yml...
CI: lint → test → build → deploy (4 jobs)
 
[documenter] README.md generated (setup, usage, API docs, deploy instructions)
[optimizer] Dockerfile: multi-stage, 94MB final image (36% smaller)
 
Result: SUCCESS
Tokens: 28,412 | Iterations: 8 | Files: 22 | Tests: 38/38
22
Files generated
38/38
Tests passing
~3min
Wall time
28.4k
Tokens used
94MB
Docker image
8
Agents active

Try these yourself

Install CogOS and run any of these examples on your own machine. Free, local, open source.