Parallax
parallax, noun: the effect by which the position of an object seems to change when it is
looked at from different positions.
(Cambridge Dictionary)
Docs for humans and agents that always follow the code.
Website: https://lucazzola.github.io/parallax/
Your repo, seen from two positions
The object is your project, and it is seen from two positions. One is your agent's, working in
the code and changing more of it than you can read. The other is yours: your understanding of what
is going on, the picture you supervise through. Left alone, the two drift apart.
The moment your expectations are not met, when you think "that's not how I imagined it", is worth
inspecting. It might be a stale page, a real bug, a design flaw, or a misunderstanding. Parallax is
a Claude Code plugin that gives your repo docs that make those moments visible, and gives each one
somewhere to go.
The hard rule
The code is the oracle, docs follow, and neither implies correctness.
- When docs and code disagree, the page changes. No skill ever changes code to match a doc.
- If the code is buggy, the docs describe the buggy behaviour. A strange behaviour written in
plain words is easier to question.
- Docs are leads. Agents check a claim in the code before relying on it.
Install
/plugin install parallax --marketplace LuCazzola/parallax
If that form isn't available yet, use the two-step install:
/plugin marketplace add LuCazzola/parallax
/plugin install parallax@parallax
The automatic hook was tested on Claude Code 2.1.319.
Then, in the repo you want to document:
/parallax:setup
Preview the docs at any time. This needs only Python:
python3 docs/parallax/tools/serve.py
What you get
Your repo's docs split by who reads them:
| Guide | For | Holds |
|---|
| User Guide | People supervising the system | Design decisions and their consequences, so you can check them against your own picture |
| Agent Guide | Agents doing the work | Code map, recipes, testing, glossary |
| Tickets | Both | How tickets work, and the ideas table kept in the repo |
| API | Both | Reference generated from the code |
Plus an MkDocs Material site with a dark mode and colour-coded, zoomable diagrams, a docs check
that needs no AI, and ticket scripts that work without the plugin.
The skills
| Skill | Runs | Does |
|---|
parallax:setup | Once, by you | Builds the docs, or ports yours after showing you the mapping. Asks where to host them |
parallax:sync | Automatically after code changes | Moves pages to what the code does now, with the smallest edit |
parallax:dive | When sync doubts something, or when you ask | Sends a read-only diver to ask whether what docs and code agree on looks like a bug. Also the whole-repo health check |
parallax:gap | When your picture differs from the docs | Reads the code and decides: stale doc, real issue, design flaw, or misunderstanding |
parallax:ticket | When something should be kept for later | Files an idea in the repo, or a GitHub issue. Asks first on public repos |
sync fires through a hook: when an agent finishes a turn in which code changed, it is sent to
sync once per change. Every skill except setup applies only to repos with docs/parallax/parallax.toml,
so nothing changes anywhere else.
What setup changes in your repo
Everything Parallax builds lives in docs/parallax/: the pages, the site config, the scripts and the
settings. Your repo root stays as it was. Only three things sit outside that folder:
- A short block in
CLAUDE.md, between parallax markers, so agents without the plugin get the rule
.github/workflows/docs.yml, if you host with GitHub Actions- GitHub labels for tickets
Reasons the agent inferred are marked "Inferred, not confirmed" until you confirm them.
Hosting
Setup asks. GitHub Actions is recommended; local (serve.py, above) and your own host also work.
On a private repo, Pages needs a paid plan, and the site is normally public unless you are on
Enterprise, so setup warns you first.
Requirements
- Claude Code
- Python 3.11+ and
git (below 3.11 the hook stays silent and the checks don't run)
gh for GitHub issues (without it you get the ideas table)uv is optional and speeds up the first preview; Docker is never required
API reference generation is Python first; other languages are best effort.
Development
python3 -m unittest discover -s test
bash test/test_templates.sh # needs Docker, for this repo's tests only
test/scenarios/ holds the pressure scenarios used to prove each skill against a baseline.
License
MIT
