tatara

tatara — where your new AI project begins. Damit beginnt dein neues KI-Projekt.

A tatara is the traditional Japanese smelting furnace that turns sand into tamahagane steel. This script is that furnace for software projects: one command scaffolds a fresh project with Git, Beads issue tracking and a ready-to-use Claude Code workflow — then hands off to an interactive Claude session that turns your idea into a concept and a plan.

The script speaks English and German and picks the language from your locale.

English · Deutsch

---

English

What it does

Run tatara with no arguments for an interactive wizard, or tatara <name> to scaffold straight away. tatara creates ~/Development/<name>/ and sets it up with:

<name>/
  .git/                          Git repo (default branch: main)
  .beads/                        local Beads issue DB (stealth, git-ignored)
  .claude/
    settings.json                PostToolUse hook -> post-commit-verify.sh
    hooks/post-commit-verify.sh  prints `git show HEAD --stat` after each commit
    skills/kickoff/SKILL.md      kickoff routine, launched via claude /kickoff
  CLAUDE.md                      project guidance with build/stack placeholders
  README.md                      minimal, name + description
  .gitignore                     macOS / IDE / secrets defaults

It is Claude Code-centric: it writes CLAUDE.md plus the .claude/ machinery and relies on the six global subagents in ~/.claude/agents/. Along the way it:

• self-heals — missing global ~/.claude/* files are bootstrapped on the fly, so tatara <name> works even on a fresh setup;
• pins the architect model — architect and architect-reviewer run on Opus (model: opus in the agent files; a stronger-sounding model is a hypothesis the review has to confirm, and in practice Opus plans came out of review with fewer HIGH findings at the same cost);
• prepares Claude Code — if claude is missing it offers to install it (official installer, with a y/N prompt); if you are not logged in it points you to claude auth login. This is non-blocking: the scaffold is built either way;
• kicks off — after the scaffold it offers to launch claude /kickoff, an interactive routine that interviews you about the project idea, drafts a technical concept, estimates the effort and moves it into the workflow.

Example hooks

examples/hooks/ holds three further hook scripts from the book Schein oder Sein (rm-rf guard, stop notification, done-proof). They are not part of the scaffold; see examples/hooks/README.md for what they do and how to register them.

Install

git clone https://github.com/alfhellmund/tatara.git
ln -s "$(pwd)/tatara/tatara" ~/.local/bin/tatara   # make sure ~/.local/bin is on $PATH
tatara --bootstrap-globals                          # one-time: create missing ~/.claude/* files

You can also just run tatara <name> right away — missing globals are created automatically.

Usage

tatara                        interactive wizard (on a terminal); otherwise help
tatara <NAME> [DESCRIPTION]   create a new project under ~/Development/<NAME>
tatara --check                check prerequisites, Claude status, model + language
tatara --bootstrap-globals    create missing global ~/.claude/* files
tatara --snapshot-globals     write the current ~/.claude/* files back into the script
tatara -h | --help            help

Environment variables

TATARA_INTERACTIVE       1 forces the wizard, 0 disables prompts (default: auto via TTY)
TATARA_LANG              force language: de | en               (default: auto via locale)
PROJECTS_ROOT            base directory for new projects       (default: ~/Development)

Language

tatara detects the language from your locale (LC_ALL / LC_MESSAGES / LANG): a German locale gives German output, everything else defaults to English. Both languages are embedded in the single script — no extra files, works offline. Force it with TATARA_LANG=de or TATARA_LANG=en.

Requirements

Runs on macOS and Linux (bash 3.2+). Windows is supported via WSL (no native port). Missing git and bd are installed on demand (with a y/N prompt) via Homebrew (macOS) or apt / dnf / pacman / zypper (Linux); on Linux without Homebrew, bd uses the official Beads install script. The only prerequisite you install yourself is a package manager (macOS: Homebrew).

jq is required for two things: --snapshot-globals reads the hook registration out of ~/.claude/settings.json, and --bootstrap-globals merges it back in. The generated per-project commit hook needs it at runtime too. Without jq the hook registration is skipped with a warning; everything else works.

git needs a configured identity — set git config --global user.name "..." and git config --global user.email "..." once; without it tatara stops before creating the project (the initial commit would otherwise fail).

Claude Code is the intended environment: if claude is missing, tatara offers to install it; logging in stays manual (claude auth login, browser OAuth). tatara --check reports the status of claude plus the optional CLIs gemini and codex — it never installs gemini/codex.

Author & License

Made by Alf Hellmund. MIT — see LICENSE.

---

Deutsch

Was es macht

tatara ohne Argumente startet einen interaktiven Assistenten, tatara <name> legt direkt an. tatara erstellt ~/Development/<name>/ und richtet es ein mit:

<name>/
  .git/                          Git-Repo (Default-Branch: main)
  .beads/                        lokale Beads-Issue-DB (stealth, git-ignoriert)
  .claude/
    settings.json                PostToolUse-Hook -> post-commit-verify.sh
    hooks/post-commit-verify.sh  zeigt `git show HEAD --stat` nach jedem Commit
    skills/kickoff/SKILL.md      Kickoff-Routine, Start via claude /kickoff
  CLAUDE.md                      Projekt-Leitfaden mit Build-/Stack-Platzhaltern
  README.md                      minimal, Name + Beschreibung
  .gitignore                     macOS- / IDE- / Secrets-Standard

Das Skript ist auf Claude Code zugeschnitten: Es schreibt CLAUDE.md und die .claude/-Maschinerie und nutzt die sechs globalen Subagenten in ~/.claude/agents/. Dabei:

• heilt es sich selbst — fehlende globale ~/.claude/*-Dateien werden bei Bedarf angelegt, sodass tatara <name> auch frisch funktioniert;
• legt es das Architekt-Modell fest — Architekt und Architekt-Reviewer laufen auf Opus (model: opus in den Agent-Dateien; ein stärker klingendes Modell ist eine Hypothese, die der Review bestätigen muss, und in der Praxis kamen Opus-Pläne mit weniger HIGH-Findings bei gleichen Kosten aus dem Review);
• bereitet es Claude Code vor — fehlt claude, bietet es die Installation an (offizieller Installer, mit y/N-Rückfrage); bist du nicht eingeloggt, weist es auf claude auth login hin. Das blockiert nicht — das Gerüst entsteht so oder so;
• gibt es den Startschuss — nach dem Gerüst bietet es claude /kickoff an, eine interaktive Routine, die dich zur Projektidee befragt, ein technisches Konzept entwirft, den Aufwand schätzt und in den Workflow überführt.

Beispiel-Hooks

examples/hooks/ enthält drei weitere Hook-Skripte aus dem Buch Schein oder Sein (rm-rf-Guard, Stop-Benachrichtigung, Done-Proof). Sie gehören nicht zum Gerüst; was sie tun und wie man sie registriert, steht in examples/hooks/README.md.

Installation

git clone https://github.com/alfhellmund/tatara.git
ln -s "$(pwd)/tatara/tatara" ~/.local/bin/tatara   # ~/.local/bin muss im $PATH sein
tatara --bootstrap-globals                          # einmalig: fehlende ~/.claude/*-Dateien anlegen

Du kannst auch direkt tatara <name> ausführen — fehlende Globals werden automatisch angelegt.

Nutzung

tatara                         interaktiver Assistent (am Terminal); sonst Hilfe
tatara <NAME> [BESCHREIBUNG]   neues Projekt unter ~/Development/<NAME> anlegen
tatara --check                 Voraussetzungen, Claude-Status, Modell + Sprache
tatara --bootstrap-globals     fehlende globale ~/.claude/*-Dateien anlegen
tatara --snapshot-globals      aktuelle ~/.claude/*-Dateien zurück ins Skript schreiben
tatara -h | --help             Hilfe

Umgebungsvariablen

TATARA_INTERACTIVE       1 erzwingt den Assistenten, 0 unterbindet Prompts (Default: Auto via TTY)
TATARA_LANG              Sprache erzwingen: de | en                (Default: Auto via Locale)
PROJECTS_ROOT            Basisverzeichnis fuer neue Projekte        (Default: ~/Development)

Sprache

tatara erkennt die Sprache aus der Locale (LC_ALL / LC_MESSAGES / LANG): eine deutsche Locale ergibt deutsche Ausgabe, alles andere ist standardmäßig Englisch. Beide Sprachen sind im einen Skript eingebettet — keine Zusatzdateien, funktioniert offline. Erzwingen mit TATARA_LANG=de oder TATARA_LANG=en.

Voraussetzungen

Läuft auf macOS und Linux (bash 3.2+). Windows wird über WSL unterstützt (kein nativer Port). Fehlende Tools git und bd werden bei Bedarf (mit y/N-Rückfrage) installiert — via Homebrew (macOS) oder apt / dnf / pacman / zypper (Linux); auf Linux ohne Homebrew zieht bd das offizielle Beads-Install-Skript. Einzige selbst zu installierende Voraussetzung ist ein Paketmanager (macOS: Homebrew).

jq wird an zwei Stellen gebraucht: --snapshot-globals liest die Hook-Registrierung aus ~/.claude/settings.json, --bootstrap-globals mischt sie dort wieder ein. Der erzeugte projektlokale Commit-Hook braucht es zur Laufzeit ebenfalls. Ohne jq wird die Registrierung mit einer Warnung übersprungen, alles andere läuft.

git braucht eine konfigurierte Identität — einmalig git config --global user.name "..." und git config --global user.email "..." setzen; ohne sie bricht tatara vor dem Anlegen des Projekts ab (der Initial-Commit würde sonst scheitern).

Claude Code ist die vorgesehene Umgebung: fehlt claude, bietet tatara die Installation an; der Login bleibt manuell (claude auth login, Browser-OAuth). tatara --check meldet den Status von claude sowie der optionalen CLIs gemini und codex — gemini/codex werden nie installiert.

Autor & Lizenz

Von Alf Hellmund. MIT — siehe LICENSE.