This hackathon brings together developers, builders, and open-source enthusiasts to explore the power of Gemini CLI. Over the course of the event, participants will prototype creative projects ranging from functional web applications to automated workflows that highlight the versatility of Gemini CLI’s new capabilities—such as slash commands and GitHub Actions integration.

The event is designed not only as a showcase of what can be built in a short sprint, but also as a collaborative feedback loop between the Gemini team and the developer community. Attendees will gain hands-on experience, share ideas, and learn from one another while the Gemini team observes real-world use cases, challenges, and successes. Submissions will be judged on creativity, functionality, and depth of CLI integration, with opportunities to continue contributing beyond the hackathon through issue reporting, feature requests, and open pull requests.

By the end of the day, participants will have built something meaningful, connected with peers, and helped shape the evolution of Gemini CLI as an open-source project—demonstrating how rapid prototyping and automation can accelerate both personal innovation and the broader AI ecosystem.

Buildathon Handbook — Gemini CLI

Welcome — you’re building a fast, local-first prototype. This handbook gives pragmatic resources, architecture patterns, safety tips, and a submission checklist so you can ship a reproducible demo in 4 hours.

Essentials: start here

• Follow Google’s Gemini CLI quickstart, (provided at kickoff as well) to install and authenticate. Do this first — set up takes the longest.
• Secure credentials: use env vars or local config files (do NOT commit keys to your repo). Common patterns:
• export GEMINI_API_KEY=... or use your cloud SDK credential helper
• Add .env to .gitignore and include an example .env.example in your repo
• Verify the CLI works before you start: run the quick demo from the official docs and confirm you can call a model.

Starter repo & dev loop (recommended layout)

• Minimal repo structure:
• README.md (how to run + where Gemini is called)
• /src (scripts that call Gemini CLI or API)
• /data (sample input files — include small synthetic data if needed)
• /demo (recording instructions / example output files)
• .env.example, requirements.txt / package.json
• Fast dev loop suggestions:
• Keep a single top-level script that demonstrates the end-to-end flow (run_demo.sh or app.py demo)
• Use small, deterministic inputs for the demo so results are reproducible
• Log both the local inputs and the model outputs to disk for judging

Architecture patterns & ideas (pick one; keep it small)

• Local File Wrangler (Research Wrangler)
• Pattern: parse local PDFs/markdown -> extract key facts -> produce structured JSON summary
• Tools: local PDF parser, small prompt chain for extraction, Gemini for summarization
• Headless Agent (CLI Lab Assistant)
• Pattern: natural-language request -> translate to shell commands -> preview -> run -> summarize
• Safety: always require a dry-run/confirmation step before destructive commands
• Story Forge (multimodal)
• Pattern: prompt -> generate story text + request images from Gemini (if available) or a stable-diffusion API -> save assets to disk
• Writing Stitcher (context stitching)
• Pattern: collect scattered MD notes -> feed outline + notes -> ask Gemini to assemble
• Data-Aware Notifier
• Pattern: local CSV/log ingestion -> periodic query -> Gemini-generated human summary/alert

Gemini integration patterns (practical tips)

• Chain-of-thought vs stepwise extraction: for multi-stage tasks split into extract -> refine -> compile. Persist intermediate artifacts on disk so you can debug.
• Tool-calling or plugin-style wrapper: call local scripts (formatters, regex extractors, CLI tools) from your orchestration layer; reserve Gemini for language-heavy tasks.
• Multimodal: if using images/audio, keep files small and include sample assets. Show Gemini touching local assets in the demo (e.g., open/save to a /demo folder).
• Eval loop: add a small automated check that verifies output structure (simple tests increase scoring for Technical Excellence & Architecture).

Prompts & prompt-engineering tips

• Keep prompts explicit about input source and desired output format (JSON, markdown, bullet list).
• Provide examples (1–2-shot) inside the prompt for structured outputs.
• Ask Gemini to include a reproducible “thoughts” or provenance block at the end: what files it read, what tools it called.

Local data & privacy guidance

• Only bring data you have the right to use. Use synthetic data when in doubt.
• Never hardcode secrets in the repo. Use env vars or secret managers.
• In README, clearly call out what local resources the prototype reads/writes so judges can understand the data flow.

Demo & video checklist (≤ 3 minutes)

• Start with one-sentence problem statement and why local data matters (10–15s).
• Show the repo briefly (README + key files) and where Gemini is called (15–20s).
• Run the end-to-end demo live or screen-recorded: show local inputs, the CLI invocation, and the saved outputs (80–100s).
• Point out any safety confirmations, tests, or logs you added (10–20s).
• Close with 10–15s: what’s next and how this could be extended.

Submission checklist (required to be judged)

1. Public or invite-only repo: include install + run steps, .env.example, and a small sample dataset if possible.
2. ≤ 3-minute demo video that shows the app running and what local resources are used.
3. Short README checklist: problem/use case, how to run, where Gemini is called, what’s local, what’s hard/interesting, what’s next.
4. Optional: add automated tests or a small test script that verifies core behavior.

Judging rubric reminder (use to shape your demo)

• Technical Excellence (20%): make it work reliably and reproducibly.
• Solution Architecture & Documentation (20%): clear repo + README + setup steps.
• Gemini Integration (30%): depth and creativity — tool-calling, multimodal, chaining, provenance.
• Impact & Innovation (30%): meaningful problem, local-first workflow others can reuse.

Quick debugging & performance tips

• If tokens/timeouts are an issue, split the job into smaller calls and cache intermediate results.
• Log request/response sizes and runtime for the demo so you can explain latency choices.
• Keep dependencies minimal — judges will run minimal install steps.

Safety, rate limits & cost awareness

• Estimate how many model calls your demo uses and show a cost/time tradeoff in the README.
• For any destructive actions (file delete, shell exec), add an explicit confirm flag and show the dry-run in the demo.

Mentors & office hours

• Use the roaming mentors for architecture feedback and quick help wiring Gemini to local scripts.
• If you get blocked on auth or CLI install, ask a mentor immediately — small infra issues can cost you a demo.

Example tiny README snippet (copy into your repo)

Problem: Aggregate downloads folder PDFs into structured summaries.  
Run: set GEMINI_API_KEY, then `./run_demo.sh` (reads /data, writes /demo/summaries)  
Where Gemini is called: src/extract_and_summarize.py -> calls Gemini to extract bullet points and create JSON output  
Local: /data (input PDFs), /demo (outputs)  
Next: add incremental indexing and vector search for recall  

Good luck — keep the scope tiny, prove the core idea, and show clear reproducibility. We’ll see you at the kickoff and during mentor loops!