Guide · Open source

How to use smol developer: install, run and prototype apps

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

smol developer is an open-source Python agent that takes a written product spec or prompt and generates a set of code files for a project. This guide shows developers and curious tinkerers how to clone and build it, run it from the command line, and call its functions from their own code. By the end you will know the prerequisites, the basic commands, and how to treat the output as a draft to review.

smol developersmol-ai/developer · ★ 12.2k · MIT Install options & downloads

Quick start

1Check prerequisites. Make sure Python is installed and get an OpenAI API key. Install Poetry with pip install poetry if you do not have it.
2Clone the repository. Run git clone on https://github.com/smol-ai/developer.git and move into the developer folder.
3Install dependencies. Run poetry install inside the folder to install the project dependencies.
4Write a prompt. Describe the app in a sentence, or put a longer spec in a markdown file such as prompt.md.
5Generate code. Run python main.py with your prompt, or pass --prompt prompt.md, and wait for the files to be written.
6Refine in a loop. Run the code, add missing detail or paste errors into the prompt, and regenerate until the result works for you.

What you need before you install smol developer

You need Python, Poetry, and an OpenAI API key. The README notes that Poetry can be installed with pip if you do not already have it. The project is MIT licensed and written in Python.

The README describes the default model as gpt-4-0613 and shows gpt-3.5-turbo-0613 as an alternative via a flag. It does not document other model providers.

Python
Poetry (install with pip install poetry if needed)
An OpenAI API key

pip install poetry

Install smol developer from the repository

Installation is a clone-and-build process. Clone the repository, move into the folder, and install dependencies with Poetry.

git clone https://github.com/smol-ai/developer.git
cd developer
poetry install

Run smol developer in Git Repo mode

Pass a short description of the app in quotes to main.py. The README's example is a HTML/JS/CSS Tic Tac Toe Game. For longer specs, put the prompt in a markdown file and pass it with --prompt. Add --debug True when you need debugging output.

The README's recommended workflow is human-in-the-loop: write a prompt, let main.py generate code, run and read the code, then refine the prompt and loop until the result is right. You can paste an error into the prompt as you would in a GitHub issue. For help locating specific code changes, the README mentions debugger.py, which reads the whole codebase.

Write a basic prompt for the app you want.
Run main.py to generate code.
Run and read the generated code.
Add missing detail to the prompt or paste in errors, then loop again.

python main.py "a HTML/JS/CSS Tic Tac Toe Game"
python main.py --prompt prompt.md
python main.py --prompt prompt.md --debug True

Use smol_dev as a library in your own app

The README describes library mode as the new feature in v1. Install the package with pip, then import the prompt functions. plan() returns a coding plan as a string. specify_file_paths() returns a list of filenames, and the README says it relies on OpenAI's Function Calling API to return JSON. generate_code_sync() returns the source for one file; an async generate_code() version also exists.

The README suggests reading main.py as the reference for how these functions fit together. You can review or edit the plan between steps, for example by asking the user to confirm it.

plan(prompt) returns the shared coding plan.
specify_file_paths(prompt, shared_deps) returns the file paths to write.
generate_code_sync(prompt, shared_deps, file_path) returns code for one file.
generate_code() is the async equivalent of generate_code_sync().

pip install smol_dev

from smol_dev.prompts import plan, specify_file_paths, generate_code_sync

prompt = "a HTML/JS/CSS Tic Tac Toe Game"
shared_deps = plan(prompt)
file_paths = specify_file_paths(prompt, shared_deps)
for file_path in file_paths:
    code = generate_code_sync(prompt, shared_deps, file_path)

Run the API mode with Agent Protocol

The README also documents an API mode that uses the Agent Protocol. Start the server with one of the two commands shown. You then create a task with a POST request to /agent/tasks, which returns a task_id, and execute one step by posting to that task's steps endpoint.

The README's example task asks for a Python script that writes 'Hello world!' to hi.txt. The README also provides a Python client library for the same flow.

poetry run api
# or
python smol_dev/api.py

curl --request POST \
  --url http://localhost:8000/agent/tasks \
  --header 'Content-Type: application/json' \
  --data '{"input": "Write simple script in Python. It should write '\''Hello world!'\'' to hi.txt"}'

curl --request POST \
  --url http://localhost:8000/agent/tasks/<task-id>/steps

Review the generated code before you rely on it

The README frames the output as a starting point, not finished software. Read the generated files, run them, and fix what is wrong. The README also says you can take over the codebase by hand at any point and stop using the AI once it gets in the way.

The README's examples include a Chrome extension, a ChatGPT plugin, a Pokemon app, and a full-stack React/Node/MongoDB app. These are demonstrations the README links to, not guarantees for your own prompts.

Read every generated file before running it.
Test the app and paste errors back into the prompt to refine it.
Edit the code by hand when the AI output stops adding value.

What people use it for

Prototyping a small app such as a Tic Tac Toe game by iterating on a written prompt.
Building a feature in your own Python app that generates a coding plan and file list from a prompt.
Exploring how an LLM can break a product spec into separate code files.
Generating a starter project from a spec, then taking over the code by hand.

Frequently asked questions

Is smol developer free to use?

smol developer is released under the MIT licence, as stated in the project's listing. The README does not cover API costs, but it does say you supply your own OpenAI API key, so you will need an OpenAI account to run it.

What do I need to install smol developer?

You need Python, Poetry (you can install it with pip install poetry), and an OpenAI API key. Then clone the repository, move into the folder, and run poetry install.

Can I use smol developer with models other than OpenAI?

The README describes an OpenAI-based setup and does not document other providers. If you need a different model, check the repository for details before you plan around it.

How is smol developer different from a starter template like create-react-app?

The README says that instead of fixed starters, smol developer lets you refine a scaffolding prompt in a loop. It generates the codebase from your spec, so you can change the prompt and regenerate rather than editing a rigid template.

Can I use smol developer in my own app?

Yes. Install it with pip install smol_dev and import plan, specify_file_paths and generate_code_sync from smol_dev.prompts. The README suggests reading main.py as an example of how to combine them.

Is the generated code production-ready?

No. The README frames the output as a starting point that a human must read, run and fix. Plan on reviewing and testing the code yourself.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

smol developer suits developers and tinkerers who are comfortable running Python, supplying an OpenAI key, and reviewing AI-generated code while prototyping a small app. It is a poor fit for anyone expecting production-ready output, non-programmers, or people who need a non-OpenAI model, since the README does not document those options. For those cases, the comparable projects listed here, such as GPT Engineer, Aider and OpenDevin, are worth a look.

Install options & downloads