cuttlefish

Describe your site. An agent builds it.

An agentic static site generator for personal sites and portfolios —
you write the content, agents handle the look and layout.

cuttlefish changes the way your site looks in a blink — just like the fast, shape-shifting sea creature it's named after.

It has the building blocks you'd expect from a static site generator — content types, taxonomies, templates — and one deliberate omission: there's no theme to install, no CSS framework, and no build step for your styles and scripts. Your whole site is a handful of plain-text files and one stylesheet you never open by hand.

Want a minimal layout with a teal accent? A two-column projects grid? Bigger headings? Describe it, and a coding agent edits the files to match. The look of your site is something you talk your way into, not something you hand-tune.

How it works

Every site ships an AGENTS.md: the agent's source of truth for the file map, the config.toml schema, the templating rules, and the styling conventions. Point a coding agent at it and say what you want —

Switch to a serif font, give the header a dark background, and feature my three latest posts on the home page.

— and it edits the config, templates, and stylesheet to match. You review a diff, not a config dialect; there are no theme docs or class names to memorize. Then ctf build renders everything to public/, and ctf serve previews it live.

Quick start

Requires Python 3.11+.

pipx install cuttlefish-ssg
ctf init my-site
cd my-site
ctf build            # render to public/
ctf serve            # live-reloading preview at http://localhost:8000

Features

• Describe, don't hand-tune: No themes, no CSS framework, no build step — one plain stylesheet an agent edits to match what you describe.
• Agent-first: Every site ships an AGENTS.md documenting its schema and conventions, so an agent can author and style it reliably.
• Rebuild fast: Incremental builds cache the last render and rebuild only what changed — editing a post's body never touches your listing pages.
• Everything else you'd expect: Content types, taxonomies, Markdown with TOML front matter, standalone pages, pretty permalinks with pagination, sitemap.xml and robots.txt, and a live-reloading dev server.
• Recipes: A library of copy-in feature guides — reading time, breadcrumbs, comments — that an agent applies by editing your templates, CSS, and config. No plugin system, just packaged instructions.

Usage

root defaults to the current directory, so you can run ctf build and ctf serve from inside your site.

Documentation

Visit https://acaibowlz.github.io/cuttlefish/ to view the full documentation.

License

Released under the MIT License