← Blog
|tutorial|By Andrey Breslav|

CodeSpeak Quick Start: Build a Project From Scratch

⚠️ CodeSpeak is in Alpha Preview: many things are rough around the edges. Please use at your own risk and report any issues to our Discord. Thank you!

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.

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

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

my-project
├── .codespeak      # Internal state used by CodeSpeak
├── .git
├── .gitignore
├── codespeak.json  # CodeSpeak project configuration
└── spec
    └── main.cs.md  # A sample spec, edit to specify what you want to build

Edit the spec

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

spec/main.cs.md
# 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  # You will be asked for an Anthropic API key

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

╭───────────────────────────────── CodeSpeak Progress ─────────────────────────────────╮
│ ✓ Process specification (0.                                                          │
│ ✓ Extract technical requirements from spec (13.1s)                                   │
│ ✓ Validating required tools (0.5s)                                                   │
│ ✓ Detect dependencies on external APIs and services (7.2s) - No external APIs found  │
│ ⊘ Check configuration of external APIs (0.0s) - No external APIs found              │
│ ✓ Setup project (0.0s)                                                               │
│ ✓ Implement specification (56.1s)                                                    │
│ ╰─ ✓ Collect context & plan work (55.8s)                                             │
│ ⊘ Generate CLI usage examples (0.0s) - No applicable actions                        │
│ ✓ Run sanity checks and fix problems with code (0.0s)                                │
│ ╰─ ✓ Running validation (pass 1) (0.0s)                                              │
│ ✓ Analyze source code and plan tests (0.0s)                                          │
│ ✓ Generate and fix tests (0.0s)                                                      │
│ App 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
    └── main.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:

spec/main.cs.md (diff)
 A click on a free space creates a new medium-sized goose flying in a random dire
 
 A click on a goose makes it bigger. When a goose gets too big it diappears with an animated pop.
 
+## UI
+
+The 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

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:

spec/main.cs.md (diff)
 A click on a goose makes it bigger. When a goose gets too big it diappears with
 
 ## UI
 
+### Speed Slider
+
 The 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
 
+### Stats
+
+In the top-right corner, a leaderboard of all players is displayed. For exach 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

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:

spec/main.cs.md (diff)
 The bottom-right corner has a speed slider:
 In the top-right corner, a leaderboard of all players is displayed. For exach 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 --skip-tests

Fixing bugs

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

spec/main.cs.md (diff)
 In the top-right corner, a leaderboard of all players is displayed. For exach pl
 - number of geese created
 
 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. 🦙.
+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 --skip-tests

Great! The bug is fixed for new users.

To reset the DB in a django app (old emojis are probably stuck from previous runs):

python manage.py flush

Fix bugs with Code Change Requests

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. To fix it, 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 Also