Adding Jaunt To Your Project

This guide is for using Jaunt as a tool inside an existing Python repo, not for hacking on the Jaunt repo itself.

1) Install Jaunt

Install Jaunt however you vend it (local path, internal index, or git). You’ll also want pytest for jaunt test.

Examples:

# Package index:
uv add "jaunt[openai]"   # or jaunt[anthropic]

# Local checkout (editable):
uv add --editable /path/to/jaunt

# Ensure pytest is installed for `jaunt test`:
uv add pytest

If you use an editable local path install, also install the matching provider SDK (openai, anthropic, or cerebras) and aider-chat in that environment.

2) Add jaunt.toml

At your project root:

version = 1

[paths]
source_roots = ["src"]
test_roots = ["tests"]
generated_dir = "__generated__"

3) Pick A Good First Spec

Best first targets:

• validators
• parsers
• formatters
• glue code (boring, correctness-heavy utilities)

Avoid (for now):

• high-performance hot paths
• complex stateful systems with tight invariants

Optional: Switch The Internal Runtime To Legacy

Jaunt now defaults to the Aider-backed planning/editing loop. If you want the older direct-SDK runtime instead, add this to jaunt.toml:

[agent]
engine = "legacy"

You still run jaunt build and jaunt test the same way.

4) Write Spec Stubs In Your Normal Source Tree

Put @jaunt.magic specs in real modules under your package, next to the code that will call them. Treat them as your public API.

5) Run jaunt build

export OPENAI_API_KEY=...
jaunt build

6) Import And Use The Spec Module

You import the spec module, not the generated module. The decorator forwards calls into __generated__/.

7) Generated Code In Git: Commit Or Ignore?

Two reasonable workflows:

1. Commit generated code.
2. Ignore generated code.

Commit generated code:

• Deterministic installs. CI doesn’t need LLM access.
• You’ll see generated diffs in PRs.

Ignore generated code:

• Cleaner repo. Output stays disposable.
• CI must run generation (so you need API keys in automation).

Pick one and be consistent.

Next: CLI Reference.