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

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

Now, restart your terminal or run source ~/.bashrc (source ~/.zshrc, depending on what terminal you are using).

Make sure uv is available:

uv --version

Get an Anthropic API key

CodeSpeak uses BYOK (Bring Your Own Key). Please get an API key at:

• https://platform.claude.com/settings/keys

Configure ANTHROPIC_API_KEY variable:

• either just 📋 paste your key when CodeSpeak asks you to (this will create an .env.local file in your project dir),
• or export ANTHROPIC_API_KEY=...

Install CodeSpeak

To install CodeSpeak with uv:

uv tool install codespeak-cli

Log in with Google or email/password:

codespeak login

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:

# 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:

--- a/spec/main.cs.md
+++ b/spec/main.cs.md
@@ -8,6 +8,13 @@ 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:

--- a/spec/main.cs.md
+++ b/spec/main.cs.md
@@ -10,12 +10,27 @@ 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:

--- a/spec/main.cs.md
+++ b/spec/main.cs.md
@@ -22,7 +22,6 @@ 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:

--- a/spec/main.cs.md
+++ b/spec/main.cs.md
@@ -24,6 +24,7 @@ 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.