kickoff-cli 0.1.0

Turn a vague project idea into concrete first steps — instantly.

 ██╗  ██╗ ██╗  ██████╗ ██╗  ██╗ ██████╗ ███████╗███████╗
 ██║ ██╔╝ ██║ ██╔════╝ ██║ ██╔╝██╔═══██╗██╔════╝██╔════╝
 █████╔╝  ██║ ██║      █████╔╝ ██║   ██║█████╗  █████╗
 ██╔═██╗  ██║ ██║      ██╔═██╗ ██║   ██║██╔══╝  ██╔══╝
 ██║  ██╗ ██║ ╚██████╗ ██║  ██╗╚██████╔╝██║     ██║
 ╚═╝  ╚═╝ ╚═╝  ╚═════╝ ╚═╝  ╚═╝ ╚═════╝ ╚═╝     ╚═╝

Turn a vague project idea into concrete first steps — instantly.

You have an idea. You know it's something to do with bots, or scrapers, or machine learning. But you don't know which library to reach for, how to structure the folder, or what the first five commands should be.

kickoff answers all three in two seconds, completely offline.

---

Install

pip install kickoff

---

Usage

Offline mode (no API key needed)

kickoff "I want to build a REST API"
kickoff "scrape a website for prices"
kickoff "automate my daily report"
kickoff "train a model to classify images"

kickoff fuzzy-matches your description against a curated recipe database and prints:

• The best-matched project type
• Libraries to reach for (with a one-line reason for each)
• 5 real terminal commands to run right now
• A folder layout sketch
• The one gotcha that trips up beginners every time

AI mode (Claude-powered custom advice)

export ANTHROPIC_API_KEY=sk-ant-...
kickoff "a Slack bot that summarises threads using GPT-4" --ai

With --ai, kickoff sends your idea to Claude and gets back a fully customised recipe — same beautiful output, tailored exactly to what you described. Falls back to offline mode silently if the API is unavailable.

---

How it works

User input
    │
    ▼
matcher.py
    ├─ Exact keyword scan  ──── confidence: 100%
    └─ thefuzz partial_ratio ── confidence: 50–99%
            │ score < 50?
            └──► generic fallback
    │
    ▼ (with --ai flag)
ai.py  ──► POST /v1/messages  ──► claude-haiku-4-5-20251001
    │        JSON response parsed into recipe shape
    └─ failure? silent fallback to matcher.py
    │
    ▼
display.py  (Rich panels, colours, logo)

1. matcher.py first scans for verbatim keyword hits (e.g. "api" in the input triggers the REST API recipe with 100 % confidence). If nothing matches exactly, it uses thefuzz.partial_ratio to find the closest recipe. Scores below 50 fall back to the generic "Software Project" recipe.

2. ai.py (optional) calls the Anthropic API with a strict JSON-only system prompt and normalises the response into the same recipe shape that display.py expects.

3. display.py renders everything with Rich: a logo header, colour-coded panels, bold library names, green terminal commands, and a yellow gotcha warning.

---

Contributing recipes

Want to add a new project type? Open kickoff/recipes.py and add a new entry to the RECIPES dictionary. Each recipe needs:

Key	Type	Description
name	str	Human-readable project type name
keywords	list[str]	Words that trigger this recipe
libraries	list[tuple[str, str]]	(package_name, one_line_reason) pairs
steps	list[str]	Exactly 5 real terminal commands
structure	str	Multi-line folder layout string
gotcha	str	One specific, non-generic beginner mistake

The steps must be real, runnable terminal commands — not descriptions. The gotcha should be something you personally got burned by, not a generic reminder to write tests.

Once you've added the recipe, open a PR! The more specific and opinionated the better.