Project Scaffolding

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 StartCopy Anchor Link

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.

TemplatesCopy Anchor Link

CLI FlagsCopy Anchor Link

Skip the prompts by passing flags directly:

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:

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

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.

ProvidersCopy Anchor Link

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 StructureCopy Anchor Link

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 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 APICopy Anchor Link

The package also exports its building blocks:

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.