README

Website: tessera-ai.net · Docs: tessera-ai.net/docs

Describe your project. AI builds it.

One command, one conversation, one production-ready codebase. Tessera turns the AI CLI tools you already have (Claude, Codex, Gemini) into an inspectable, resumable build orchestrator.

Important: Tessera uses your own AI CLI tools and your own subscription. Each call burns tokens from your plan. Generated code may contain bugs, security issues, or wrong implementations. Always review before shipping. See Disclaimer.

Install in 30 seconds

composer global require tessera/installer

Make sure the Composer global bin directory is in your PATH:

OS	Path
Windows	`%APPDATA%\Composer\vendor\bin`
macOS / Linux	`~/.composer/vendor/bin`

tessera --version
tessera doctor    # check that your system is ready

Build your first project

tessera new my-restaurant

Tessera asks five questions (business, languages, payments, design, scale), picks the right stack, and runs the AI build. Coffee break — the typical Laravel build is 10–15 minutes.

Full walkthrough →

See what AI is about to do

Before you spend a single token, compile and inspect the build plan:

tessera plan compile stacks/laravel.yaml
tessera plan show          # pretty-print every step
tessera plan diff a.json b.json    # what changed?

Every plan is hash-anchored. Tweak a prompt, recompile, diff — you see exactly what shifted. tessera plan reference →

Available stacks

Stack	Best for	Where the recipe lives
Laravel + Filament	CMS, e-commerce, admin panels	`stacks/laravel.yaml`
Node.js / Next.js	API servers, SaaS, real-time apps	`stacks/node.yaml`
Go	High-performance backends, microservices	`stacks/go.yaml`
Flutter	Mobile (iOS + Android + web)	`stacks/flutter.yaml`
Static	Landing pages, portfolios, event sites	`stacks/static.yaml`

Every stack is described in YAML. The same engine drives them all. Authoring a custom stack →

What you get out of the box

Inspectable plans. tessera plan compile/show/diff — no tokens spent until you say go.
Quality gates. Each step declares post-checks (exists_any, exists_all) so the AI saying "done!" against an empty directory fails loudly.
Skippable enrichment. Polish steps and SETUP.md generators that hit a transient rate limit don't abort a 25-minute build.
Build trace. Every run leaves .tessera/state.json + .tessera/events.jsonl + .tessera/plan.json. Post-mortem any build with jq and a few seconds.
Resume. Crash, Ctrl+C, network drop — run the same command, pick up where it left off. Atomic state writes survive interrupts.
Cross-OS process control. Windows taskkill /F /T, Unix pgrep -P + posix_kill. Tessera never leaves zombie AI subprocesses pinned to your terminal.
Plan-aware AI routing. Claude Max gets all the steps; free-tier accounts hit fallback chains. Rate limits cause a 2-minute cooldown and a tool switch, not a build crash.
AI tool isolation. Every AI subprocess — whether spawned through the adapter path or the legacy router — runs under an allowlist that passes only that provider's own credentials. ANTHROPIC_API_KEY never reaches Codex; OPENAI_API_KEY never reaches Claude; and unrelated secrets (GITHUB_TOKEN, COMPOSER_AUTH, the ssh-agent socket, CI tokens) never reach any AI CLI. Detection probes run with no credentials at all.
Pluggable adapters. Adding Groq, Ollama, or your own AI →

Quick reference — CLI commands

tessera doctor                                       # is my system ready?
tessera new <dir>                                    # the main command
tessera new <dir> --force                            # overwrite existing dir
tessera new <dir> --stack=<name>                     # skip AI stack selection (names: tessera stacks)
tessera new <dir> --requirements-fixture=<path>      # skip interactive Q&A (loads JSON)
tessera plan compile <yaml> [-o <out.json>]          # compile manifest → plan.json
tessera plan show [<plan.json>]                      # pretty-print a plan
tessera plan diff <a.json> <b.json>                  # semantic diff (exit 0/1/2)
tessera stacks                                       # list available stacks + system readiness
tessera tools                                        # which AI tools are installed?
tessera --version
tessera --help

Full CLI reference on the docs site →

Environment variables

Optional. The installer asks for your AI plans interactively on first run and saves the answers to ~/.tessera/config.json, so later runs skip the questions. The environment variables below always take precedence over the saved config.

TESSERA_CLAUDE_PLAN=max       # max | pro | free
TESSERA_CODEX_PLAN=plus       # plus | free
TESSERA_GEMINI_PLAN=free      # pro | free
TESSERA_TOOL_PREFERENCE=gemini,claude,codex   # custom tool order
TESSERA_TOOL_EXCLUDE=codex                    # never use this tool
TESSERA_SAFE_AI=1             # opt out of --dangerously-skip-permissions for Claude (see below)
TESSERA_AI_TIMEOUT=900        # seconds per AI step (default 900)
TESSERA_ISOLATE_AI_CONFIG=0   # opt out of interview behavioral-config isolation

By default the requirements interview runs the AI CLI isolated from your personal instruction files (claude --safe-mode, codex --ignore-user-config) so the interview is always in English and machine-independent. Auth is preserved. Set TESSERA_ISOLATE_AI_CONFIG=0 only if a CLI flag ever breaks authentication on your setup.

Full security & permission model →

AI permission mode

TESSERA_SAFE_AI=1 affects only Claude. Here is the exact per-tool breakdown:

Tool	Default behaviour	With `TESSERA_SAFE_AI=1`
claude	Launched with `--dangerously-skip-permissions` — no per-action approval prompts.	`--dangerously-skip-permissions` is removed. Claude pauses for approval on each action; the installer will fail loudly rather than silently hang.
codex	Runs inside Codex's own sandboxed approval model. Tessera passes `--skip-git-repo-check` but no auto-approve flag. Whether Codex prompts depends on your installed version's defaults.	No change. `TESSERA_SAFE_AI` is ignored for Codex. A warning is printed to remind you of this.
gemini	Gemini CLI's default approval flow is whatever ships on your machine. Tessera passes no permission flag. For API-key authenticated sessions this is typically non-interactive by default.	No change. `TESSERA_SAFE_AI` is ignored for Gemini. A warning is printed to remind you of this.

Summary: if you set TESSERA_SAFE_AI=1 on a system where Codex or Gemini is the only available tool (or is preferred via TESSERA_TOOL_PREFERENCE), Claude's behaviour is unaffected (it is not running), and Tessera will emit a one-time warning that the flag has no effect on the resolved tool. The build will proceed using that tool's own defaults.

If you need guaranteed non-interactive, unattended behaviour with Codex or Gemini, configure those tools' own approval settings outside of Tessera (e.g. Codex's ~/.codex/config.toml, or ensure your Gemini API key is set so the CLI does not prompt for auth).

After the build

cd my-restaurant
cat SETUP.md              # what to configure (env vars, API keys, deploy)
php artisan serve          # for Laravel — npm run dev for static/node, etc.

Each stack's SETUP.md is junior-developer-friendly: env keys with the URL where to get them, payment provider step-by-step, deployment checklist. AI writes it as part of the build.

For continuing changes:

Laravel — php artisan tessera "add a gallery to the homepage" (in-project AI Engine with project context).
Other stacks — use your AI CLI directly: claude "add JWT auth" / codex "create REST endpoints" / gemini "add a dark mode toggle". The AI reads your codebase and knows the structure.

Testing

vendor/bin/phpunit

477 tests, 1090 assertions — all passing with zero AI tokens. CI runs on Ubuntu, Windows, and macOS with PHP 8.4–8.5.

Contributing & adding a stack

Contributing guide → · How to author a stack →

The minimal recipe: drop stacks/<your-stack>.yaml, add a *Stack.php lifecycle class with preflight() / postSetup() / completionInfo(), register in StackRegistry. The YAML drives the AI portion; the PHP class only handles tool-specific lifecycle.

Disclaimer

AI Token Usage. Tessera calls AI CLI tools installed on your system. Each call consumes tokens from your own subscription plan or API quota. Tessera does not provide, manage, or pay for AI access. A typical project build uses 5–10 AI calls.

Generated Code. AI-generated code may contain bugs, security vulnerabilities, incorrect business logic, or incompatible dependencies. Tessera includes safeguards (quality gates, PHP lint, test loops, namespace verification), but you are responsible for reviewing, testing, and validating all generated code before production.

Third-Party Services. Tessera may scaffold integrations with third-party services (payment providers, cloud APIs, email services). These integrations need manual configuration and validation. Tessera is not affiliated with and makes no guarantees about any third-party service.

No Warranty. This software is provided "as is", without warranty of any kind. The authors are not liable for damages arising from the use of this software or any code it generates. Use at your own risk.

Full disclaimer →

License

Tessera is source-available, not open source.

Use case	Cost	Licence
Personal projects, learning, OSS, non-profit, government	Free	PolyForm Noncommercial 1.0.0
Client work for pay (agency / freelance)	from €249/yr	Commercial — Solo
Agency / small product team (up to 10 devs)	€799/yr	Commercial — Studio
Larger teams, custom SLA, private registry	Custom	Commercial — Enterprise

Generated code is yours in either lane — the licence covers the installer itself, not the projects it scaffolds.

tessera / installer

Maintainers

Package info

Statistics

Security