Turn a
SPEC.mdinto an installable, tested Python package.
spek is a small LLM-powered coding agent. You write a markdown file
describing what you want, point spek at it, and a few minutes later
there's a working Python package on disk that builds and passes its own
tests.
For the design rationale and a worked example end-to-end, see Here is how I built a simple coding agent.
- Python 3.11+
uv(recommended) orpip- A running Docker daemon —
spekruns every shell command and file write inside a sandboxed container. If Docker isn't running,spek buildrefuses to start. - An Anthropic API key in the environment (
ANTHROPIC_API_KEY).
The PyPI distribution is spek-cli; the binary is still spek:
uv tool install spek-cli # recommended: isolated, on $PATH
# or:
pip install spek-cliVerify:
spek --helpspek looks for .env in the current directory or any ancestor of the
spec file. Copy the template and fill it in:
cp .env.example .env
$EDITOR .env # paste your ANTHROPIC_API_KEYYou can also override the model:
ANTHROPIC_API_KEY=sk-ant-...
ANTHROPIC_MODEL=claude-sonnet-4-6 # optional
ANTHROPIC_BASE_URL=https://api.anthropic.com # optional, for proxiesTwo commands:
spek init my-project # scaffold SPEC.md skeleton
$EDITOR my-project/SPEC.md # describe what you want
spek build my-project/SPEC.md \
--workdir my-project --confirm-plan # run the agentWhen the run finishes green, my-project/ contains a normal Python
project (pyproject.toml, src/, tests/) you can use immediately:
cd my-project
uv run pytest # tests pass
uv run <your-cli> --help # the binary you specifiedThe repo ships with a worked example at
examples/weather-tool/SPEC.md:
spek build examples/weather-tool/SPEC.md --workdir /tmp/weatherA run produces a working weather-converter CLI with 27 tests passing.
The full session log and final plan are described in BLOG.md.
spek --help
usage: spek [-h] {init,build} ...
init Scaffold an empty SPEC.md and .spek/.
build Run the agent against a SPEC.md spec.
Useful spek build flags:
| Flag | What it does |
|---|---|
--workdir DIR |
(required) Directory for the package; bind-mounted at /work inside the container. |
--fresh |
Wipe .spek/ before starting. Use after significant spec changes so the agent re-plans from scratch. |
--confirm-plan |
Pause after the plan phase and require approval (or edit) of .spek/plan.md. Recommended. |
--max-steps N |
Cap on tool calls. Default 120. |
--max-seconds N |
Wall-clock cap. Default 1800. |
--quiet |
Suppress progress output. The journal still records every event. |
Everything is scoped to the working directory. After a successful run:
<workdir>/
├── SPEC.md # your input (untouched)
├── pyproject.toml # generated
├── src/... # generated
├── tests/... # generated
└── .spek/
├── journal.jsonl # full event log (resume + audit)
├── plan.md # the plan (numbered checklist)
└── command_config.json # build/test/lint commands the agent uses
There is no global state and no ~/.config/spek. Wipe .spek/ and the
next run starts from scratch.
make install # uv-managed venv with dev extras
make test # pytest
make lint # ruff + black --check
make typecheck # mypy strict
make build # sdist + wheel into ./distFull target list: make help.
MIT.
