Quick Start: Build a Project From Scratch

This guide walks you through creating a CodeSpeak project from scratch. You'll write a spec, build it, add features, and fix bugs — all by editing a Markdown file.

Prerequisites: Complete the Installation steps first.

Create a new project

mkdir my-project
cd my-project
codespeak init

CodeSpeak will create a directory structure and initialise a git repo:

my-project
├── .codespeak      # Internal state used by CodeSpeak
├── .gitignore
└── codespeak.json  # CodeSpeak project configuration

Write a spec

Create/open spec.cs.md in your favourite editor, and type away. Here's an example that may be fun to start with:

# Funny Geese Demo

The app animates geese (🪿) bouncing around the screen, tumbling.

## UX

A click on a free space creates a new medium-sized goose flying in a random direction.

A click on a goose makes it bigger. When a goose gets too big it disappears with an animated pop.

## Technology

- Use pure HTML + JS
- Use Tailwind CSS for styling

Build

codespeak build spec.cs.md

When the build is finished, you'll see a message in the terminal:

╭──────────── CodeSpeak Progress: Funny Geese Demo: Animating bouncing geese with click interactions ────────────╮
│ ✓ Process specification (0.1s)                                                                                 │
│ ✓ Collect project information (0.1s)                                                                           │
│ ✓ Implement specification (39.9s)                                                                              │
│ ╰─ ✓ Collect context & plan work (39.7s)                                                                       │
│ ✓ Finalize spec build (0.2s)                                                                                   │
╰───────────────────────────────────────────────  Alpha Preview  ────────────────────────────────────────────────╯
Processing spec 1/1: spec.cs.md
Built successfully.

An HTML file will be created in the project dir, you can open it with your browser:

.
├── codespeak.json
├── index.html       # <--- open this file
└── spec.cs.md

Enjoy the flying geese!

Add a feature

To improve your project, you can edit the spec and build again. CodeSpeak will turn the diff in the spec into a diff in the code. For example, let's add a slider to slow down/speed up the geese:

A click on a goose makes it bigger. When a goose gets too big it disappears with an animated pop.## UIThe bottom-right corner has a speed slider:- in the middle by default- moving the slider to the left slows the geese down- moving to the right speeds them up## Technology- Use pure HTML + JS

Now, let's build again:

codespeak build spec.cs.md

The code has been updated. Check out the new version.

Add a Django back-end

Let's go for something more serious than just a self-contained HTML page:

## UI### Speed SliderThe bottom-right corner has a speed slider:- in the middle by default- moving the slider to the left slows the geese down- moving to the right speeds them up### StatsIn the top-right corner, a leaderboard of all players is displayed. For each player, it shows:- name- number of geese created- number of geese popped 🎉Every player gets a random name from a list of names built by combining a cute adjective with an animal name, e.g. "Huggable Alpaca" and an emoji avatar, e.g. 🦙.Stats are updated in real time.## Technology- Use pure HTML + JS- HTML + JS- Django- Use Tailwind CSS for styling

Build the project:

codespeak build spec.cs.md

Now, you can start the Django server:

uv run manage.py runserver

Open the page in your browser, the URL is in your console (usually http://127.0.0.1:8000).

Remove a feature

If something doesn't seem like a good idea, edit the spec to remove it:

In the top-right corner, a leaderboard of all players is displayed. For each player, it shows:- name- number of geese created- number of geese popped 🎉Every player gets a random name from a list of names built by combining a cute adjective with an animal name, e.g. "Huggable Alpaca" and an emoji avatar, e.g. 🦙.

Build the project to see the changes:

codespeak build spec.cs.md

Fix bugs by editing the spec

If you see that something is not right, first try to fix the spec:

- number of geese createdEvery player gets a random name from a list of names built by combining a cute adjective with an animal name, e.g. "Huggable Alpaca" and an emoji avatar, e.g. 🦙.Match emojis to the animals used (don't use animals that don't have emojis).Stats are updated in real time.

codespeak build spec.cs.md

Fix bugs with Code Change Requests

When the spec is correct, but the code doesn't work the way you expect, it presents a problem: there's nothing to change in the spec, but then how will the issue get fixed.

Typical examples would be

• either a bug in the code, e.g. an exception, or something not working as specified,
• or a low-level detail, like when you want to change a color of some element on the screen that is not even mentioned in the spec.

For these situations, CodeSpeak supports Code Change Requests through codespeak change command.

For example, let's say we see that the number of geese is computed incorrectly for some reason. This is not a problem with the spec, it's a bug in the implementation.

So, let's tell CodeSpeak what's wrong in a Code Change Request:

codespeak change -m "Number of geese displayed is off by 1"

CodeSpeak will try its best to fix the bug. See the Code Change Requests guide for more details.

Next steps

• Work in an existing project — add CodeSpeak specs to an existing codebase
• Convert existing code to specs — use codespeak takeover to generate specs from code
• Managed files — understand how CodeSpeak tracks generated files