AI Coding Agents

Coding agents like Claude Code, Codex and Cursor write good Hologram code once they have its docs and rules in context. This guide covers why Hologram suits agents, how to set up your project for them, and how to get the best results.

Why Hologram Suits Agents

An agent works best when it can hold the whole feature it's changing in one model. Hologram's architecture keeps that model small.

• One language, one repo. Your pages, components, browser logic and server logic are all Elixir in the same project. The agent never switches between a frontend and a backend codebase, or between two languages with different conventions.
• No client-server wiring. A feature that updates the UI and saves to the database lives in one page or component module: the template, the action that runs in the browser and the command that runs on the server. There's no REST endpoint, fetch call or JSON format for the agent to write and keep in sync, because Hologram handles the transport (see Architecture).
• Elixir is a strong language for models. In AutoCodeBench, a benchmark from Tencent's Hunyuan team that tests models on problems in 20 programming languages, Elixir ranked first.
• Docs written for agents. Since v0.9, Hologram ships its rules and full documentation in formats agents read directly, and every release updates them along with the code.

Hologram's upcoming data layer (see the Roadmap) takes this further. Think about what an agent has to write to put a list of records on the screen the usual way: a query, an endpoint, a fetch on the client, a cache key and its invalidation, an optimistic update, and a rollback for when the server disagrees. That's six places to be wrong, in three languages. With the data layer, it's a prop with a query on it. An agent can't forget to invalidate a cache it never has to touch.

The data layer also covers agents that use your app rather than write it. An agent writing through the data layer is just another client, gated by the same policies as every user, so there's no separate permission model for it. And when two agents write to the same row at once, which happens far more often with agents than with people, their changes merge per column.

Set Up Your Project

Hologram ships its rules for agents in the package, as usage-rules.md. Generate the instructions file your agent reads with one of these commands. For Claude Code:

$ mix holo.gen.claude_md

For Codex, Cursor, GitHub Copilot and the other agents that read AGENTS.md:

$ mix holo.gen.agents_md

The task writes the rules between <!-- hologram-start --> and <!-- hologram-end --> markers. If the file already exists, it replaces only the marked section and leaves the rest of your instructions alone. Run it again after each Hologram upgrade, so the rules match the version you have installed.

# My App

- Run tests with `mix test`.
- Database access goes in commands.

<!-- hologram-start -->
## Hologram

Hologram is a full-stack isomorphic Elixir web framework…

## Common Pitfalls

- **Never** use Phoenix/LiveView syntax…
…
<!-- hologram-end -->

If you already manage your agent rules with the usage_rules package, you don't need the Hologram tasks. Hologram's usage-rules.md is in the format it reads, so add hologram to the packages you sync.

What the Agent Gets

Hologram gives agents three files, each for a different job:

• usage-rules.md holds the conventions and common mistakes in a short form. It's what the generator tasks copy into CLAUDE.md or AGENTS.md, so it stays in the agent's context in every session.
• llms.txt is an index of the documentation pages, with a one-line description of each. The agent uses it to find and open only the page it needs.
• llms-full.txt is the full documentation in one file. It's large, so the agent reads the section it needs rather than keeping the whole file in context.

You don't have to point the agent at the last two. The rules in its instructions file already tell it where they are.

The copies on hologram.page follow the latest release. The package ships its own copies in deps/hologram, which match the version you have installed, and the rules send the agent to that llms-full.txt first.

Build on Existing Code

Agents follow the patterns they find in your project. Once your app has a few pages and components, the agent picks up how you structure state, name actions, split components and lay out templates, and new code comes out in the same style.

When you ask for something new, name an existing page or component that's close to it, for example: "make it work like the ProductCard component".

Let the Agent See Errors

Hologram reports most mistakes in terms an agent can act on. The compiler rejects a misspelled key filter, and a template that reads a missing var raises an error that names it and lists the vars the template has.

Client errors happen in the browser, so they don't appear in your server logs. In dev and test, Hologram shows them in an error overlay on top of the page, with the full Elixir stacktrace (see Configuration). An agent that runs your app in a browser, through a browser extension or a browser automation server, reads the overlay itself, so it can check its own work after each change. If yours can't, copy the error from the overlay and paste it to the agent as it is.

A First Prompt

Here's a prompt to try once your instructions file is in place. Adjust the feature and the names to your app:

Add a page at /notes that lists notes and has a form to add a new one.
Save notes to the database with Ecto, in a command.
Follow the structure of the existing pages and components in this project.
When you're done, open the page in the browser, add a note, and check
that it appears in the list and that no error overlay shows up.

The last line matters most. It turns "the code compiles" into "the feature works", and the agent does the checking instead of you.

Sponsored by

Main sponsor

Milestone sponsor

Performance sponsor

Innovation partner