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:

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 →

Build from official Tessera packages

The default Laravel build AI-generates a bespoke CMS. The package flavor instead installs the maintained Tessera product as Composer packages — the skeleton app plus the feature modules you pick:

tessera new my-shop --tessera-packages                      # interactive module multi-select
tessera new my-shop --tessera-packages --tessera-modules=shop,blog   # preselect modules
tessera new my-shop --tessera-packages --tessera-modules=none        # core skeleton only

What it runs (Laravel-only; the flag forces the laravel stack):

1. composer create-project fernext/skeleton my-shop --stability=dev --repository={"type":"vcs","url":"…/tessera-skeleton"} — the skeleton's own composer.json carries the VCS repositories entries for core + modules, so later requires resolve.
2. For each selected module: composer require tessera/{module} then php artisan module:enable {module} (which runs the module's migrations).
3. The shared post-scaffold steps (database config, migrate, asset build, admin credential) run exactly as they do for the AI flavor.

Every step is resumable — a crash or Ctrl+C picks up from the last completed composer require / module:enable, and the module selection is persisted so a resumed run never re-prompts.

The target repositories (fernext/skeleton, fernext/core, fernext/shop, fernext/blog) are published by Phase D of the platform's package split. Package names and repo URLs are config-driven — see the TESSERA_* variables below to point the flow at forks or staging repos.

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

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 new <dir> --tessera-packages                 # install official Tessera packages (skeleton + modules)
tessera new <dir> --tessera-packages --tessera-modules=shop,blog  # preselect modules (shop,blog / none)
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

Package flavor (see Build from official Tessera packages). All optional — every value falls back to the built-in Tessera distribution:

TESSERA_FLAVOR=package        # package | ai — same as --tessera-packages, useful in CI
TESSERA_MODULES=shop,blog     # preselect modules (shop,blog / none); same as --tessera-modules
TESSERA_SKELETON_PACKAGE=fernext/skeleton                       # create-project target package
TESSERA_SKELETON_REPO=https://github.com/fer-next/skeleton   # its VCS repository
TESSERA_PACKAGE_STABILITY=dev # create-project --stability
TESSERA_SHOP_PACKAGE=fernext/shop      # override a module's package name…
TESSERA_SHOP_REPO=https://github.com/fer-next/shop   # …and its repo
TESSERA_BLOG_PACKAGE=fernext/blog
TESSERA_BLOG_REPO=https://github.com/fer-next/blog

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:

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

The full suite passes with zero AI tokens — no real AI calls are made. The Tests badge above tracks the live count and status; 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.

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

• Pricing & buy a commercial licence →
• Full Commercial License Agreement →
• Licence overview & FAQ →