# Project Scaffolding

URL: https://cogitator.app/docs/getting-started/scaffolding

> Create new Cogitator projects in seconds with create-cogitator-app.

`create-cogitator-app` is an interactive CLI that scaffolds a Cogitator project from a template, wired to your chosen LLM provider, and installs its dependencies.

## Quick Start

```bash
npx create-cogitator-app
```

The prompts ask for:

1. Project directory (default `my-agents`)
2. Template
3. LLM provider
4. Package manager (pre-selected from the one running the command, otherwise pnpm)
5. Docker Compose (default yes)
6. Git repository (default yes)

The target directory must not exist or be empty. The scaffolder then writes the files, runs `<pm> install` (unless you pass `--no-install`) and, if chosen and git is installed, creates a repository. A failed install or git step is reported and left for you to run by hand.

## Templates

| Template     | What you get                                                                         |
| ------------ | ------------------------------------------------------------------------------------ |
| `basic`      | One agent with two tools (`src/index.ts`, `src/tools.ts`)                            |
| `memory`     | Agent with Redis-backed memory that remembers a conversation across runs             |
| `swarm`      | Hierarchical swarm: a reviewer supervising a researcher and a writer (`src/agents/`) |
| `workflow`   | DAG workflow of three agent nodes and a function node (`@cogitator-ai/workflows`)    |
| `api-server` | Express server exposing agents over HTTP (`@cogitator-ai/express`)                   |
| `nextjs`     | Next.js App Router chat app with a streaming route and `useCogitatorChat` UI         |

## CLI Flags

Skip the prompts by passing flags directly:

```bash
npx create-cogitator-app my-project \
  --template swarm \
  --provider openai \
  --pm pnpm \
  --docker \
  --no-git
```

Or accept the defaults for everything you don't pass:

```bash
npx create-cogitator-app -y
npx create-cogitator-app my-project --provider openai --yes
```

| Flag                       | Shorthand | Values                                                         |
| -------------------------- | --------- | -------------------------------------------------------------- |
| `[directory]`              |           | First positional argument; its last segment names the project  |
| `--template`               | `-t`      | `basic`, `memory`, `swarm`, `workflow`, `api-server`, `nextjs` |
| `--provider`               | `-p`      | `ollama`, `openai`, `anthropic`, `google`                      |
| `--pm`                     |           | `pnpm`, `npm`, `yarn`, `bun`                                   |
| `--docker` / `--no-docker` |           | Include Docker Compose                                         |
| `--git` / `--no-git`       |           | Initialize a git repository                                    |
| `--no-install`             |           | Write the files without installing dependencies                |
| `--yes`                    | `-y`      | Don't prompt; use the defaults for every missing value         |

An invalid flag value is ignored and asked for interactively; anything not given by a flag is prompted for. With `--yes` nothing is prompted and the defaults fill the gaps: `my-agents`, `basic`, `ollama`, the detected package manager, Docker Compose on, git on.

## Providers

| Provider    | Default Model       | Env Var                      |
| ----------- | ------------------- | ---------------------------- |
| `ollama`    | `qwen3:8b`          | `OLLAMA_BASE_URL` (optional) |
| `openai`    | `gpt-6.1-sol`       | `OPENAI_API_KEY`             |
| `anthropic` | `claude-sonnet-5-5` | `ANTHROPIC_API_KEY`          |
| `google`    | `gemini-3.8-flash`  | `GOOGLE_API_KEY`             |

The generated code sets `llm.defaultProvider` to the chosen provider, reads the key from the environment variable above and gives each agent the default model. `.env.example` lists the variables to set. Next.js loads `.env*` files on its own; the other templates do not, so export the variables in your shell or run with `tsx --env-file=.env src/index.ts`.

## Generated Structure

```
my-project/
├── src/
│   ├── index.ts        # entry point
│   └── tools.ts        # tool definitions (files vary by template)
├── package.json        # dev/start scripts (tsx), build, typecheck
├── tsconfig.json       # not for nextjs, which brings its own
├── cogitator.yml       # provider and model, for reference
├── .env.example
├── .gitignore
├── pnpm-workspace.yaml # with --pm pnpm
├── docker-compose.yml  # with --docker
└── README.md
```

`cogitator.yml` is in [`@cogitator-ai/config`](/docs/getting-started/configuration) format (`llm.defaultProvider`, `llm.defaultModel`, `memory` for the `memory` template, and `deploy.health.path: /api/health` for the `api-server` and `nextjs` templates, the route their app serves health on) and is read by `cogitator run` and `cogitator deploy`. The generated code configures `Cogitator` in `src/` itself and does not load it.

`docker-compose.yml` runs Redis 7 and Postgres 16 (credentials from `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB`, all defaulting to `cogitator`), plus Ollama when it is the provider.

Start the project with `npm run dev` (or `pnpm dev`, `yarn dev`, `bun dev`).

## Programmatic API

The package also exports its building blocks:

```ts
import { scaffold } from 'create-cogitator-app';

const result = await scaffold({
  name: 'my-agent',
  path: '/projects/my-agent',
  template: 'basic',
  provider: 'ollama',
  packageManager: 'pnpm',
  docker: false,
  git: true,
  install: false, // optional, default true
});

if (result.install.status === 'failed') console.error(result.install.error);
```

`scaffold()` writes the files, installs dependencies and initializes git like the CLI. Pass `install: false` to only write the files, for example when you embed the scaffolder and install later. It throws when the directory is not empty, and otherwise resolves to a `ScaffoldResult`: the generated `files`, and `install` and `git` steps that are each `{ status: 'done' }`, `{ status: 'skipped' }` or `{ status: 'failed', error }`. A failed step never throws, so the project stays on disk. `parseArgs(argv)` and `collectOptions(args)` turn command-line arguments into these options (prompting for the rest). `getTemplate(name)`, `templateChoices`, `defaultModels`, `providerConfig(provider)`, `providerEnvKey(provider)`, `detectPackageManager()` and `devCommand(pm)` are exported as well.