Octo Docs — Create a TypeScript Project

01 · Prepare

Prerequisites

Ensure your local environment has the required runtime and package manager before running the scaffolder.

Node.js 20+
Required to execute the CLI bundle and support modern ECMAScript standard modules.
pnpm 8+
Required for fast, disk-efficient dependency caching and workspace linking.

02 · Create

Quick start

Open a terminal in the directory that should contain the project, then run the current published release.

Recommended

pnpm dlx @markromolecule/octo@latest

Ready to copy.

03 · Decide

Prompt walkthrough

The guided configuration flow prompts you for the precise options that shape your project's features and templates.

Step 01

Name the project

Choose its directory and package identity.

Step 02

Choose the shape

Select Monorepo or one framework-native application.

Step 03

Pick frameworks

Choose the web and API tools that fit the project.

Step 04

Deliver context

Use the bundled snapshot or a Git-backed factory.

04 · Choose a shape

Generated modes

Octo supports two distinct template architectures depending on whether your project requires shared workspace modules.

Monorepo

Workspace

A pnpm and Turborepo workspace with web, API, database, UI, and shared packages wired together.

Best for:

Products with multiple applications or shared packages.

Core outputs:

apps/web with React + Vite, Next.js, or Astro
apps/api with Hono or Express
packages/db with Prisma, prisma-kysely, and Kysely
packages/ui, hooks, services, shared, tsconfig, and eslint-config
pnpm-workspace.yaml and turbo.json

Standard

Single App

A focused, framework-native application without workspace files or monorepo directories.

Best for:

Single applications that should keep their framework’s familiar shape.

Core outputs:

Official Vite, Next.js, or Astro project structure
Conventional TypeScript starter for Hono or Express
No pnpm workspace or Turborepo configuration
The same context-factory and project infrastructure baseline

05 · Deliver context

Context delivery

Choose how project guidance is copied now and refreshed later.

Method	What it does	Refresh
Bundled Snapshot	Copies the context-factory packaged with Octo. It is the fastest, most reproducible default.	No Git or network dependency during generation.
Git Submodule	Adds context-factory as a submodule and provides a context:pull path for upstream updates.	Requires access to the selected Git repository.
Direct Clone	Clones a standalone copy and removes its nested Git metadata for independent ownership.	Requires Git during setup; later refreshes replace the standalone copy rather than pulling it.

06 · Configure

CLI configuration

Point Git-backed modes at a repository your team owns.

Terminal

pnpm dlx @markromolecule/octo@latest \
  --context-repo https://github.com/your-org/context-factory.git

For repeated runs, configure the repository in your shell:

Terminal

export CONTEXT_FACTORY_REPO=https://github.com/your-org/context-factory.git
pnpm dlx @markromolecule/octo@latest

Precedence:--context-repo overrides CONTEXT_FACTORY_REPO.

07 · Optional

Global install

If you create projects frequently, install the executable once and use the shorter octo command.

Install globally

pnpm add --global @markromolecule/octo

Ready to copy.

Terminal

octo --version
octo

08 · Verify

After generation

Enter the project, install if needed, and validate its bundled context before changing features.

Terminal

cd your-project
pnpm install
pnpm context:validate

Read the generated agent entry point first. It routes tools into the context-factory without duplicating its rules.

Package README Browse source