This quick start guide will walk you through creating a CodeSpeak project from scratch. We will build a project that runs with Python and uv.

If you are interested in using CodeSpeak in an existing project, check out this tutorial.

Prerequisites

Install uv

CodeSpeak uses uv as its Python package manager.

curl -LsSf https://astral.sh/uv/install.sh | sh

Restart your terminal (or run source ~/.bashrc / source ~/.zshrc), then verify:

uv --version

Get an Anthropic API key

CodeSpeak is BYOK (Bring Your Own Key). Get an API key at platform.claude.com/settings/keys.

You can provide the key in two ways:

• Paste it when CodeSpeak prompts you (this creates an .env.local file in your project directory)
• Set the environment variable: export ANTHROPIC_API_KEY=<your-key>

Install CodeSpeak

uv tool install codespeak-cli

Verify the installation:

codespeak --version

Log in

codespeak login

Log in with Google or email/password.

Create new project

# New project dir
mkdir my-project
cd my-project

# Initialise a CodeSpeak project
codespeak init --mixed

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

Create the 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

Now, it's time to build your project:

codespeak build --spec spec.cs.md  # You will be asked for an Anthropic API key

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!

Adding a new 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 spec.cs.md

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

Adding 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 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 spec.cs.md

Fixing bugs in 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.

Let's see if it helps:

codespeak build --spec spec.cs.md

Great! The bug is fixed for new users.

IN case you need to reset the DB in the django app (in case old emojis are stuck from previous runs):

python manage.py flush

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.

Fix bugs with Code Change Requests

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.