Forem: Sammii

How I built Lunary's birth chart reader

Sammii — Tue, 24 Mar 2026 08:00:00 +0000

The birth chart feature is the core of Lunary. Every other feature either feeds from it or refers back to it. Building it properly took longer than I expected, mostly because "properly" turned out to have more requirements than I'd initially scoped.

This is the story of how that feature was built: the calculation layer, the visual representation, the AI interpretation, and the iterations that got it from a rough prototype to something I'm proud of.

What a birth chart actually contains

A complete birth chart has more elements than most apps show. Lunary calculates and displays:

Planets: Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto, and Chiron. Each has an ecliptic longitude (position in the zodiac), a latitude (angular distance from the ecliptic plane), a declination (angular distance from the celestial equator), and a speed (degrees per day, which indicates retrograde when negative).

Points: The North Node (also called the True Node, computed from the Moon's orbital ascending node), the South Node (opposite the North Node), and the Part of Fortune (calculated from Ascendant + Moon - Sun, or the reversed formula for night charts).

House cusps: All 12 Placidus house cusps, computed from the local sidereal time at the birth location and time. The Ascendant is the 1st house cusp and the Midheaven (MC) is the 10th house cusp.

Aspects: All angular relationships between planets and points that fall within orb for the major aspect types (conjunction, sextile, square, trine, quincunx, opposition). Displayed as a grid showing each planet pair.

That's the data layer. The visual layer has to present all of this in a way that's readable.

The chart visual

The traditional birth chart wheel is a circle divided into 12 houses, with the zodiac signs running around the outside and planets placed at their positions within the wheel. This is the standard visual that anyone who has studied astrology will recognise, and departing from it creates friction.

Lunary's chart visual is an SVG rendered server-side. The zodiac outer ring, house lines, and planet glyphs are all drawn as SVG paths and text elements. The positions are computed from the ecliptic longitudes and the Ascendant angle.

The main challenge in chart wheel layout is planet clustering. When two or more planets are close together in the zodiac, their glyphs overlap. Real chart software handles this with a "displacement" algorithm that adjusts the angle of crowded glyphs while keeping a line connecting them to their actual position. Implementing this correctly took several iterations. The naive approach was to offset clustered planets by a fixed amount, which worked for pairs but failed for clusters of three or more. The final algorithm sorts planets in a cluster by longitude, then distributes them evenly within the cluster space while preserving the order.

The data panel

Alongside the wheel, Lunary shows a structured data panel with:

A table of all planetary positions (sign, degree, minute, retrograde status)
A table of house cusps
An aspect grid (a triangular matrix where each cell shows the aspect between two planets)
A section for dignity and debility (planets in their rulership, exaltation, fall, or detriment)

The dignity section took research to implement correctly. Every planet has rulership over certain signs (Mercury rules Gemini and Virgo, Venus rules Taurus and Libra, etc.), exaltation in one sign (the Sun is exalted in Aries, the Moon in Taurus, etc.), fall in the sign opposite its exaltation, and detriment in the sign opposite its rulership. These are classical astrological concepts that Lunary surfaces automatically.

The AI interpretation layer

The AI interpretation is where the most interesting engineering happened. The problem with using a language model for birth chart interpretation is straightforward: models have been trained on a lot of astrological content and will happily produce natal chart readings that sound plausible but aren't grounded in the user's actual positions.

A model given "interpret this Scorpio rising" will produce a reading about Scorpio rising in general, drawing on all the Scorpio rising content it was trained on. That's not what we want. We want a reading that references the specific degree of the Ascendant, the Ascendant ruler (Mars or Pluto for Scorpio), where that ruler is placed, and how that placement interacts with other chart factors.

The solution was to not ask the model to interpret the chart from scratch. Instead, we describe the chart to the model in astronomical terms:

Natal chart data:
- Sun: 14°32' Gemini, 3rd house, applying trine to Saturn (orb: 2°15')
- Moon: 28°47' Pisces, 12th house, separating conjunction with Neptune (orb: 3°22')
- Mercury: 2°19' Cancer, 3rd house, retrograde, applying square to Mars (orb: 4°07')
[... all planets]

House cusps:
- 1st (Ascendant): 3°41' Scorpio
- 10th (Midheaven): 14°22' Leo
[... all cusps]

Active aspects:
[... list with orbs]

Task: Write a narrative birth chart interpretation based on the above positions...

This framing forces the model to reason about the specific data provided rather than recall general astrological content. The chart is described as a set of facts and the model is asked to synthesise those facts into a narrative.

The improvement in output quality from this approach was significant. Interpretations that use this structured prompt consistently reference the actual positions, mention specific aspects with their orbs, and integrate the house placements correctly. Generic interpretations that don't mention the specific data are much rarer.

What the user sees

The finished birth chart experience walks through:

A visual wheel with all planets and house divisions
A "chart summary" that highlights the three most significant placements (usually Ascendant, Sun, Moon) in natural language
A full planetary positions table
An AI narrative covering the major themes of the chart
The aspect grid with tappable aspects that link to grimoire articles about those specific aspect combinations
A dignity and debility section

The tappable aspects are probably the feature I'm most proud of. You see that your Sun squares Saturn, you tap it, and you get the grimoire article specifically about Sun square Saturn in a natal chart. That connection between the live chart data and the educational content is exactly what I wanted to build when I started.

The iteration process

The first version of the chart reader was much simpler: positions table, no visual, basic AI summary. The visual wheel came in a later iteration after I established that users found the raw data table confusing without the visual context.

The AI interpretation went through the most iterations. The first version used a basic system prompt asking the model to "interpret this birth chart" with the chart positions appended. The output was superficially plausible but not grounded in the data. The second version described the chart in structured astronomical terms, which improved grounding significantly. The current version also includes a passage from the grimoire for each major placement, which grounds the model's interpretive vocabulary in Lunary's own educational content.

Each iteration was motivated by actual user feedback. The things that seemed obvious from a developer perspective (of course the positions table is useful) were not always obvious to users, and the things I thought were secondary (the aspect grid) turned out to be some of the most used features.

I'm Sammii, founder of Lunary and indie developer building tools I actually want to use. I write about shipping products solo, the technical decisions behind them, and figuring it all out in public.

The maths behind how long a planet stays in your sign

Sammii — Sat, 21 Mar 2026 09:00:00 +0000

Most astrology content rounds the numbers. Saturn spends "about 2.5 years" in each sign. Jupiter spends "about a year." These are averages. They are also wrong for any specific transit you actually care about.

Saturn spent 2.7 years in Pisces (March 2023 to February 2026). It will spend 2.1 years in Taurus (April 2028 to June 2030). That is a six-month difference. For a planet whose transits define entire chapters of your life, six months is not a rounding error.

When I built transit duration tracking into Lunary, the real numbers surprised me. They also changed how I read charts.

Orbits are not circles

The reason planets spend different amounts of time in different signs is orbital eccentricity. Planetary orbits are ellipses, not circles. A planet moves faster when it is closer to the Sun (perihelion) and slower when it is further away (aphelion). This is Kepler's second law: a planet sweeps out equal areas in equal times.

For Saturn, the difference is measurable. Its orbital eccentricity is 0.0565, which means its distance from the Sun varies by about 11% between perihelion and aphelion. When Saturn is closer to the Sun, it moves through signs faster. When it is further away, it lingers.

The zodiac is fixed against the stars. But the planet's speed through that fixed backdrop changes continuously. The result: Saturn in Pisces lasts 974 days. Saturn in Taurus lasts 778 days. Nearly 200 days difference, same planet.

The actual numbers from Lunary's ephemeris

Here is what Lunary's transit engine computes for Saturn, using real ephemeris data from astronomy-engine (VSOP87):

Sign	Total days	Years	Segments
Aquarius	911	2.5	2
Pisces	974	2.7	2
Aries	888	2.4	2
Taurus	778	2.1	1
Gemini	773	2.1	1
Cancer	859	2.4	2
Leo	840	2.3	3
Virgo	908	2.5	2

The "segments" column matters. When Saturn retrogrades, it can briefly re-enter the previous sign before moving forward again. Saturn in Leo has three segments: it enters, retrogrades back, re-enters, retrogrades back again, then finally commits. The total cumulative time is 840 days across those three passes. If you only counted the first entry, you would think Saturn left Leo after a few months.

How the calculation works

Lunary uses two different strategies depending on how fast the planet moves.

Fast planets (Moon through Mars) use a simple formula: degrees remaining in the sign divided by the planet's daily motion. The Moon moves about 13.2 degrees per day. If it is at 22 degrees of Aries, it has 8 degrees remaining, which gives roughly 14.5 hours. Mercury averages 4.1 degrees per day but varies enormously, from barely moving during a retrograde station to covering 2 degrees in a single day.

// Fast planets: degrees to boundary ÷ daily motion
const degreeInSign = currentLongitude % 30;
const degreesRemaining = 30 - degreeInSign;
const remainingDays = degreesRemaining / dailyMotion;

The key detail: Lunary uses the actual observed daily motion from astronomy-engine, not the average. For the Moon, actual speed varies between 12.2 and 14.8 degrees per day, a 20% range. Using the average would put the Moon's sign change time off by hours.

Slow planets (Jupiter through Pluto) use pre-computed ephemeris data. A script scans forward through time at one-day resolution, recording every moment each planet changes sign. The results are stored as date segments. At runtime, Lunary looks up which segment the current date falls in and calculates remaining time from there.

// Slow planets: lookup from pre-computed sign segments
const segments = SLOW_PLANET_SIGN_CHANGES[planet][currentSign];
const activeSegment = segments.find(
  seg => now >= seg.start && now <= seg.end
);
const remainingDays = (activeSegment.end - now) / msPerDay;

The pre-computation handles retrograde re-entries correctly. Saturn entering Aries, retrograding back into Pisces for four months, then re-entering Aries is stored as two separate Aries segments. The total duration sums across all segments, so users see "2.4 years total in Aries" rather than being confused when Saturn briefly disappears back into Pisces.

Retrograde makes everything harder

Retrograde is when a planet appears to move backwards through the zodiac from Earth's perspective. It is an optical illusion caused by relative orbital speeds, like overtaking a car on the motorway and watching it appear to drift backwards.

For fast planets during retrograde, the simple degrees-remaining formula breaks entirely. If Mercury is retrograde at 15 degrees of Gemini, it is moving backwards, towards 14, 13, 12 degrees. Dividing remaining degrees by daily motion would give a nonsensical answer because the planet is heading the wrong way.

Lunary handles this by scanning forward with astronomy-engine to find the actual station direct date: the moment the planet stops moving backwards and resumes forward motion.

// Scan forward to find when retrograde ends
for (let i = 1; i <= 120; i++) {
  const futureDate = new Date(date.getTime() + i * msPerDay);
  const motion = dailyMotion(futureDate);
  if (motion > 0) {
    // Retrograde ended — refine to half-day precision
    // Linear interpolation between the two days
    endDate = interpolate(prevDate, futureDate, prevMotion, motion);
    break;
  }
}

This gives accurate retrograde durations. Mercury retrograde lasts about three weeks, not the four days that the naive formula would calculate.

Why this changed how I read charts

Before building transit duration tracking, I read transits as a list. Saturn is in Pisces. Jupiter is in Gemini. Mars is in Leo. Each item was equally present, equally weighted.

Adding duration context changes the reading fundamentally. "Saturn has been in Pisces for 22 months and has 10 months remaining" is a completely different statement from "Saturn is in Pisces." The first tells you where you are in a story. The second just names the chapter.

The badge display in Lunary shows remaining time: "10m left" for Saturn, "3d left" for Mars, "14h left" for the Moon. Seeing these together reveals the layering. The Moon changes the emotional texture every 2.3 days. Mars shifts the energy every six weeks. Saturn provides the structural backdrop for 2-3 years.

The cache system reflects this too. Saturn's position is cached for seven days because it barely moves. The Moon's position is cached for 15 minutes. Near sign boundaries, all cache TTLs drop by 75% so the transition is captured accurately. The infrastructure mirrors the astrology: fast planets need frequent attention, slow planets reward patience.

Pluto is the extreme case

Pluto's orbital eccentricity is 0.2488, far more eccentric than any other planet. Its transit durations are wildly uneven. Pluto spent about 15 years in Capricorn. It will spend roughly 20 years in Aquarius. In some signs it lingers for over 30 years. In others, barely 12.

An entire generation shares a Pluto sign. The variation in duration means some generations carry that shared transformation for twice as long as others. The "Pluto in Capricorn" generation (roughly 2008-2024) had a shorter collective experience than the "Pluto in Aquarius" generation that follows.

This is not trivia. If you believe outer planet transits shape collective experience, then the duration is the intensity. A 12-year Pluto transit and a 30-year Pluto transit are not the same kind of event, even if the sign is the same.

The numbers are the astrology

I have found that the more precisely I engage with the actual orbital mechanics, the more astrology makes sense, not less. Rounding Saturn to "2.5 years" obscures the fact that Saturn in Pisces is a qualitatively different experience from Saturn in Taurus, not just because of the signs, but because one lasts six months longer. Six months more pressure. Six months more consolidation. Six months more of whatever Saturn in that sign is working on in your chart.

The ancient astrologers did not have VSOP87 or astronomy-engine. But they watched the sky every night for centuries. They knew these durations intimately. The maths we compute in milliseconds, they observed over lifetimes. The precision is modern. The knowledge is ancient.

This is a Grimoire Twist: astrology education with a Lunary engineering angle.

Every culture agrees

Sammii — Thu, 19 Mar 2026 09:00:00 +0000

Saturday is Saturn's day. Sunday belongs to the Sun. Monday is the Moon's day. We say these words every week without thinking about them. But the names are not arbitrary. They are a cosmological system hiding in plain view, embedded so deeply into daily life that we forgot it was ever a teaching.

The Hermetic tradition, some of the oldest philosophical writing we have, describes seven planetary bodies that govern the physical world. Their government over this world is called Fate and Destiny. The Divine Pymander, one of the earliest Hermetic texts, puts it plainly: these seven governors "in their circles contain the Sensible World."

Seven planets. Seven days. Seven spheres the soul must pass through.

In the previous two parts of this series, I wrote about the question that started all of this: do we really die? And about the pattern I found across traditions, independently arriving at the same philosophical claim. The body is temporary. Consciousness is not.

This piece goes deeper into the mechanism. Not just what the ancients believed, but what they described happening. Because the Hermetic creation narrative is not vague. It is precise, structured, and it maps onto something I did not expect when I first read it in a university library at 21: the exact thing that astrology calculates.

Mind before matter

There are two models of creation. The contemporary one, which most of us absorbed without questioning, says matter came first. Stars formed, planets coalesced, chemistry became biology, biology became neurology, and at some point consciousness flickered into existence as a byproduct of sufficient complexity.

The ancient model inverts this entirely. Mind came first. Thoughts from a greater entity were manifested into physical reality. The Hermetica describes a universe created by Atum, the Cosmic Mind, not through physical force but through thought. The first thing that existed was an intention. Everything else followed from it.

Jonathan Black, in The Secret History of the World, describes the sequence: "The earliest episodes in history are to be understood in terms of the ordered creation of the solar system. One after the other Saturn, the Sun, Venus, the Moon and Jupiter joined in the work of weaving together the basic conditions that made possible the evolution of life on earth."

The planetary bodies are not decoration. They are the architecture.

The seven spheres

The Hermetic texts describe seven planetary spheres arranged concentrically around Earth. Each sphere is governed by one of the classical planets: Moon, Mercury, Venus, Sun, Mars, Jupiter, Saturn. Together, they form a structure through which consciousness must travel to enter the physical world.

The teaching works in both directions.

When a soul enters physical existence, it descends through each sphere in turn, acquiring qualities from each planet as it passes. The Moon gives instinct and the capacity for growth. Mercury gives speech and reason. Venus gives desire. The Sun gives vitality and will. Mars gives courage and aggression. Jupiter gives ambition and the capacity for leadership. Saturn gives structure, limitation, and material form.

By the time the soul reaches Earth, it carries the imprint of every sphere it passed through. It has been shaped by the journey.

At death, the process reverses. The disembodied spirit ascends back through each sphere, shedding the qualities it acquired. Black describes this passage: "From the lunar sphere the disembodied spirit flies upwards to the realm of Mercury. From there to Venus and then on to the sun." At each stop, the soul returns what it borrowed. What remains at the end is what was there before the journey began: consciousness, stripped of its planetary clothing.

I wrote this in the margin of my MA notebook: "The order of the gods, which brought about order to this world, is the reverse order which the spirit will embark on to then enter into the spiritual dimension."

The astrology connection

Here is what stopped me in the library.

If the seven planetary spheres each contribute specific qualities to the soul on its descent into physical life, then the configuration of those planets at the moment of birth is a record of what the soul acquired. The natal chart is not a prediction. It is a receipt.

The Hermetic texts are explicit about this. The Divine Pymander calls the governance of the seven spheres "Fate or Destiny." This is not metaphor. It is a philosophical claim about the structure of consciousness itself: that who you are, your temperament, your drives, your capacity for love or ambition or discipline, was shaped by the planetary configuration at the moment your consciousness entered a body.

This is what astrology calculates. Not "what will happen to you on Tuesday," but the specific qualities your consciousness carries from its journey through the spheres. When a natal chart shows Venus in a particular position, the Hermetic reading is that your soul acquired a specific quality of desire as it passed through that sphere. When Saturn dominates, you carry more of the structure and limitation that the outermost sphere imparts.

I did not expect this. I went into the library researching consciousness and light. I came out understanding why I would later build an astrology platform.

Everyone tells the same story

What made the research overwhelming was not any single tradition. It was the convergence.

The Polynesian creation myth describes the world emerging from the union of Ao (light) and Po (darkness). The Maori tradition begins with forces of earth and sky joined. The Chinese creation myth describes the universe as an egg containing chaos, which broke into light sky and dense earth. The Norse tradition starts with Ginnungagap, a vast emptiness, from which emerged Muspelheim (fire) and Niflheim (ice). The Greek tradition has Gaea emerging from Chaos.

Every single one of these follows the same pattern: everything came from one thing, and at the beginning there was nothing.

The Hermetica calls this the movement from unity to duality. The Cosmic Mind, which is everything, creates a physical dimension that appears separate from itself. Light and dark. Spirit and matter. The dualistic nature of reality is not a cultural coincidence. It is the philosophical foundation that every tradition independently describes.

The Greek mythology fits the Hermetic framework precisely. Zeus (Jupiter) overthrew his father Cronus (Saturn). Saturn had swallowed five of his children. The lineage runs Uranus, Saturn, Jupiter: the outermost spheres in descending order. This is not entertainment. It is cosmological instruction encoded in narrative. The time the environment changed to allow life to develop into advanced forms is remembered as the time Jupiter overthrew Saturn.

The price of individuality

There is a paradox at the centre of the Hermetic teaching that I have not stopped thinking about since I first read it.

The Cosmic Mind, Atum, contains everything. It is everything. But because it is everything, it cannot look upon itself. It cannot know itself the way we can know it. The Divine Pymander puts it this way: "God is intelligible, not to himself, but to us."

We can do something that the source of all consciousness cannot. We can create, think, and observe in ways that the Cosmic Mind cannot, because we have individuality. We have separation. We have a point of view.

But individuality came at a cost. The denser our physical state became through evolution, the more we lost our connection to the Cosmic Mind, and to each other. Separation gave us creativity, science, art, the capacity to build and understand. It also gave us grief, sorrow, loneliness, ego.

I wrote in my MA: "In a sense, we are greater than Atum, or god, or the immortal. We can do things, create things and think things that Atum cannot itself, but creates through us with our minds and bodies. We can know Atum in a way it cannot know itself, but this individuality brought with it grief, sorrow and many other negative possibilities which our life, emotions and senses also bring."

This is the trade. Consciousness pays for self-awareness with disconnection. We gained everything by losing everything.

Sleeping Beauty has seven fairies for a reason

The Hermetic teaching did not stay in ancient texts. It embedded itself in stories we tell children.

Sleeping Beauty has seven fairies. Black identifies them as the seven gods of the planetary spheres. The seventh fairy, who represents Saturn, the spirit of materialism, curses the child with death, which is commuted to a long period of sleep. Life in the material realm is the sleep. The physical body is the enchantment.

Wordsworth understood this. His 1807 ode, the one I painted onto the walls of my light installation in invisible UV-reactive ink, says it directly:

Our birth is but a sleep and a forgetting:
The Soul that rises with us, our life's Star,
Hath had elsewhere its setting,
And cometh from afar:
Not in entire forgetfulness

The soul as a star, rising with us in life and setting with us in death. It comes from afar, from the Cosmic Mind, through the seven spheres. And although this life is a sleep for the soul, it does not entirely forget where it came from.

Every tradition, every myth, every fairy tale that survived long enough to reach us carries this structure. The seven spheres. The descent. The forgetting. The qualities acquired along the way.

What this means for what I built

A few years after finishing the MA, I built Lunary. I did not build it because I thought horoscopes were fun. I built it because the ancient cosmology had a logic I trusted.

The planetary bodies are the seven spheres. The natal chart is the map of the soul's descent. The transits, the current positions of the planets as they move through the sky, are the ongoing conversation between your acquired qualities and the spheres that gave them to you.

I am not saying this is literally true in the way that gravity is true. I am saying that the philosophical framework is coherent, that it has been maintained across millennia and cultures with remarkable consistency, and that writing it off as superstition requires ignoring some of the most careful thinkers in human history.

The next piece in this series looks at what Hermes Trismegistus specifically taught, the figure at the centre of all of this, a synthesis of Thoth and Hermes, Egyptian and Greek wisdom combined.

This is part 3 of A Journey Through Light.

A component library that builds itself every day

Sammii — Tue, 17 Mar 2026 09:00:00 +0000

What if a component library didn't wait for you to have a free weekend? What if it woke up every morning, found something interesting on the internet, and built a new interactive component before you'd finished your coffee?

That's Prism. It's my design engineering component library, and it builds itself every day.

The aesthetic

Every component in Prism shares a visual language I'd describe as "quiet confidence". The background is near-black (#050505). Colours are luminous pastels that shift and respond to your cursor position. Nothing is loud. Nothing demands attention. But everything moves.

Spring physics drive every animation. Not CSS transitions, not cubic beziers; actual spring equations running in requestAnimationFrame. The result is motion that feels physical. A 2-3 pixel overshoot on a hover. A 2-3 degree tilt that settles naturally.

The cursor is the colour source. Move it to the top-left and you get cool blues. Bottom-right brings warm pinks. Every component inherits this, so the whole library feels like one coherent thing.

Deep dive: MagneticButton

MagneticButton was the first component I built by hand. Hover near it and the button drifts toward your cursor, pulled by a spring force. The text inside shifts independently, creating a subtle parallax. A soft glow appears beneath it, tinted by the cursor-reactive colour system.

The implementation is pure React and requestAnimationFrame. No animation libraries. What makes it interesting isn't any single effect. It's how small each effect is. The displacement is maybe 8 pixels. The tilt is barely perceptible. But stack them together and the button feels alive.

The autonomous pipeline

Prism has a four-stage daily pipeline that runs without me:

Scout fires up a headless browser and trawls X for trending UI interaction patterns. It collects references and descriptions of novel hover effects, scroll-triggered animations, and creative uses of WebGL.

Curator takes the scout's findings and picks today's build. It considers what's already in the library, what would complement existing components, and what's technically feasible. It writes a detailed build brief.

Builder takes the brief and writes the component. Real TypeScript, real Framer Motion or raw requestAnimationFrame. It creates the component file, a demo page, and registers it in the gallery. Then it runs the build to make sure everything compiles.

Publisher records a 12-second video of the component in action using Playwright with an organic cursor simulation, then posts it to X, Bluesky, and Mastodon via Spellcast.

Why build it this way?

I wanted to see what happens when you automate the creative process and let it compound. One component a day is 365 a year. Even if half are mediocre, that's still a substantial library of interactive, cursor-reactive components that all share the same visual DNA.

The pipeline also forces consistency. Every component goes through the same curator. Every component uses the same colour system. Every component gets tested, recorded, and published the same way.

For now, it wakes up every morning and builds something new. That's enough.

Our birth is but a sleep

Sammii — Mon, 09 Mar 2026 23:51:22 +0000

Our birth is but a sleep

There are words written on the walls of a room I built in 2017. You cannot see them.

Walk through the room under red light, then orange, yellow, green, blue, violet. The full visible spectrum, one colour at a time. The walls stay blank. Just white fabric. Nothing there.

Then you reach ultraviolet.

And the words appear.

Our birth is but a sleep and a forgetting.

William Wordsworth wrote that in 1807. I painted it onto stretched fabric in invisible UV-reactive paint because I thought it was the most important sentence I had ever read. I still do.

I was 21 and writing an MA dissertation. The question I was supposed to be answering was something academic: about light as artistic medium, about the visible spectrum as subject matter. But the question I was actually asking, the one underneath all the research, was simpler and more frightening:

Do we really die?

Not in a morbid way. In the way you ask a question that nobody around you will take seriously, so you spend nine months in the university library instead, reading everything you can find.

What I found surprised me.

Not because the answer was obvious. But because every tradition I looked at: Egyptian, Greek, Norse, Hindu, Buddhist, Hermetic. All asking exactly the same question. All arriving, through completely different routes, at something like the same answer.

The body is temporary. Consciousness is not.

That is not a religious claim. It is a very old philosophical one. And the more I read, the Hermetic Corpus, the Egyptian Book of the Dead, the Upanishads, the Norse cosmology, the Greek mystery schools, the more I understood that what we call mythology is often something else entirely. It is philosophy dressed in story. Instruction dressed in metaphor. Knowledge that could not be written plainly, so was written beautifully instead.

The Hermetic texts, some of the oldest philosophical writing we have, describe a universe created by Mind. Not matter, not energy: Mind. The first thing that existed was a thought. Everything else followed from it.

Consciousness, in this tradition, is not something the brain generates. It is something the brain temporarily houses.

I spent nine months with all of this. I read texts that were two thousand years old and felt like they had been written for me. I made paintings. I built a light installation. I painted Wordsworth's words onto the walls in invisible ink and watched them appear.

The research changed me. More than I understood at the time.

A few years later I built Lunary, an astrology platform. Not because I thought horoscopes were entertainment, but because the ancient cosmology had a logic I trusted: the planetary bodies are not decoration. They are the seven spheres. The soul's map, made into an app.

Now I think about AI and consciousness. Whether minds can exist in machines. Whether consciousness is substrate-independent. The same question, again, in a different form.

I have not stopped asking it since I was 21.

I have wanted to write about this research for years. It has lived in notebooks and dissertation files and documents only I can see. It is the most formative work I have ever done and almost nobody knows about it.

That changes now.

This is the first piece in a series called A Journey Through Light. It covers everything: the Hermetic Corpus, the soul's journey through the seven planetary spheres, the Net of Indra, what Turrell and Boltanski and Wordsworth were all circling around, the UV text on the wall, and where all of it leads.

Some of it is ancient. Some of it is personal. All of it is research I trust completely.

Start here. Or start anywhere. The words were always there.

I Built MCP Servers for My Own Products — Here's the Workflow

Sammii — Mon, 09 Mar 2026 19:20:53 +0000

I Built MCP Servers for My Own Products — Here's the Workflow

I used to manage my products through dashboards. Check analytics here, schedule posts there, pull metrics from another tab. Constant context-switching.

Now I do all of it by talking to Claude.

Not through some hacked-together integration: through MCP servers I built for my own products. Model Context Protocol is the standard Anthropic published for giving AI assistants structured access to external tools. I built servers for both Spellcast and Lunary. Here's how, and why it changed everything.

What MCP actually is (in one paragraph)

MCP is a protocol that lets you define a set of "tools" — functions with typed inputs and outputs — that Claude can call during a conversation. Instead of copy-pasting data into a chat window, Claude calls your API directly and works with the live result.

The architecture: your MCP server exposes tools over stdio (or HTTP). Claude Code discovers them and can call them when relevant. You write the server once; it works in any MCP-compatible client.

The Spellcast MCP

Spellcast is my social scheduling platform. The MCP server exposes the full API as typed tools:

server.addTool({
  name: 'list_posts',
  description: 'List scheduled, published, draft, or failed posts with optional filters',
  parameters: z.object({
    account_set_id: z.string().optional(),
    status: z.enum(['draft', 'scheduled', 'published', 'failed']).optional(),
    limit: z.number().default(50),
  }),
  execute: async ({ account_set_id, status, limit }) => {
    const posts = await db.query.posts.findMany({
      where: buildWhereClause({ account_set_id, status }),
      limit,
    });
    return posts;
  },
});

What I can do from a Claude conversation: list_posts, create_post, update_post, publish_article, get_analytics, generate_content, update_brand_voice, and more.

The practical workflow: I describe what I want, and Claude calls the tools. "Optimise the hooks on my scheduled tweets" becomes Claude reading every post, identifying weak openers, and rewriting them in batches.

The Lunary MCP

Lunary is my astrology platform. The MCP exposes product analytics and content tools:

server.addTool({
  name: 'get_dashboard',
  description: 'Get key product metrics: MAU, MRR, retention, feature usage',
  parameters: z.object({}),
  execute: async () => {
    const metrics = await getProductMetrics();
    return metrics;
  },
});

Tools: get_dashboard, get_dau_wau_mau, get_feature_usage, get_cohort_retention, search_grimoire, predict_churn.

What the workflow actually looks like

Me: "Check Lunary metrics and tell me what's changed since last week."

Claude calls get_dashboard, get_dau_wau_mau, get_cohort_retention. Returns a summary. Surfaces what moved.

Me: "Schedule a thread about the SEO growth for the sammii account."

Claude calls list_account_sets, get_brand_voice, generate_content to write five thread variations, waits for my pick, calls create_post to schedule it.

Me: "Those tweets from February with weak hooks — fix them."

Claude calls list_posts, reads each one, identifies weak openers, rewrites them, calls update_post in batches.

No dashboards. No tab-switching. Just conversation with full product access.

Building your own

npm install @modelcontextprotocol/sdk zod

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';

const server = new McpServer({ name: 'my-product', version: '1.0.0' });

server.tool(
  'get_stats',
  'Get product statistics',
  {},
  async () => {
    const stats = await fetchMyProductStats();
    return { content: [{ type: 'text', text: JSON.stringify(stats) }] };
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);

Wire it into Claude Code's settings:

{
  "mcpServers": {
    "my-product": {
      "command": "node",
      "args": ["/path/to/my-mcp/dist/index.js"]
    }
  }
}

Your product's API is now accessible from any Claude conversation.

Why it matters for solo founders

The power isn't just convenience. Claude can operate across your entire product context in a single conversation — read your analytics, read your content queue, read your brand voice, and produce work that's coherent across all of them without you manually bridging the gap.

I estimate MCP saves me 5-8 hours a week in dashboard time and manual data-pulling. More importantly, it removes the friction that stops small tasks from getting done. If checking metrics requires three tabs and a copy-paste, you do it less. If it's one sentence, you do it constantly — and catch things early.

I built a hive mind for my AI agents (and they coordinate better than most teams)

Sammii — Fri, 06 Mar 2026 12:57:42 +0000

I built a hive mind for my AI agents (and they coordinate better than most teams)

I run 4-5 Claude Code agents simultaneously. One is refactoring my astrology platform's transit engine. Another is publishing articles across four blog platforms. A third is generating TikTok videos with ML-scored engagement predictions. A fourth is autonomously building UI components, recording them, and posting to X.

They all share the same brand voice, the same knowledge base, the same metrics, and the same understanding of what the others are doing right now.

This is the system I built to make that work.

What the hive mind actually is

It's not one thing. It's a network of interconnected systems that give every AI agent access to:

Shared memory across all projects (what's being worked on, what was decided, what's broken)
140+ tools via MCP servers (schedule posts, query analytics, publish articles, manage photos)
A local brand API that injects domain knowledge into every generation call
Cross-account boost rules that automatically amplify content between accounts
Autonomous pipelines that research, build, record, and publish without human input

Here's the full architecture:

Claude Code agents (4-5 concurrent sessions)
    │
    ├── Shared Memory Layer (16 markdown files)
    │   ├── active-work.md      ← live coordination
    │   ├── projects/*.md       ← per-project state
    │   ├── gotchas.md          ← known bugs
    │   ├── decisions.md        ← architecture choices
    │   └── live-metrics.md     ← auto-updated daily
    │
    ├── MCP Servers (5 registered)
    │   ├── Spellcast MCP       ← 140 tools: posts, articles, analytics, AI content, boosts
    │   ├── Lunary MCP          ← 100+ tools: metrics, grimoire, OG images, video scripts
    │   ├── Photos MCP          ← 22 tools: album access, usage tracking, Spellcast pipeline
    │   ├── Blog MCP            ← 6 tools: personal blog CRUD + publish
    │   └── Git MCP             ← standard git operations
    │
    ├── Brand API (localhost:9002)
    │   ├── Ollama (llama3.1:8b with brand system prompt)
    │   ├── 40+ grimoire JSON files (crystals, tarot, spells, zodiac)
    │   ├── 10 brand knowledge markdown files
    │   └── Smart context injection (only loads relevant data per query)
    │
    ├── Open WebUI (localhost:8080)
    │   ├── 4 knowledge bases (Sammii Brain, Grimoire, Content Strategy, Tech Architecture)
    │   └── 5 Python tools (brand knowledge, grimoire search, content engine, metrics, Spellcast)
    │
    └── Autonomous Pipelines
        ├── Content Creator     ← video/carousel generation + ML scoring + Spellcast scheduling
        ├── Prism Pipeline      ← scout → curator → builder → recorder → publisher (daily)
        └── Daily Metrics Cron  ← pulls DAU/MAU/MRR at 07:00, writes to live-metrics.md

Every piece connects to the others. Let me walk through each layer.

Layer 1: shared memory (how agents coordinate)

The core problem: when I start a new Claude session, it has no idea what my other agents are doing. Two agents might both try to modify the same config file. One might re-solve a bug another already fixed.

The fix is a directory of markdown files at ~/.claude/projects/.../memory/ that every agent reads on startup and updates continuously as it works.

The critical file is active-work.md:

## In Progress

### [lunary] - Refactoring transit engine
- **Started**: 2026-03-06 10:00
- **Doing**: Rewriting severity calculation
- **Files touched**: src/lib/transits.ts, src/lib/severity.ts
- **Status**: working

### [spellcast] - Article publishing pipeline  
- **Started**: 2026-03-06 10:30
- **Doing**: Adding LinkedIn companion post generation
- **Files touched**: apps/api/src/routes/articles.ts
- **Status**: working

### [prism] - Design engineering component library
- **Started**: 2026-03-06
- **Doing**: Building MagneticButton component
- **Files touched**: prism/ (entire project)
- **Status**: working

Every agent checks this before starting work. Every agent updates it as status changes. Every agent removes its entry when done. It's a coordination protocol built entirely on file reads and writes.

The key insight: continuous updates, not batch updates at session end. If an agent crashes, its entry stays visible. If an agent finishes something, others see it immediately.

I'll cover the full memory system in Part 2 of this series.

Layer 2: MCP servers (the tool network)

MCP (Model Context Protocol) lets Claude call external tools during a session. I have five servers registered, giving every agent access to the same capabilities.

Spellcast MCP: 140 tools for content operations

Spellcast is my social media scheduling platform. Its MCP server exposes everything:

// spellcast-mcp/src/index.ts
const server = new McpServer({ name: "spellcast", version: "1.0.0" });

registerPostTools(server);        // 30 tools: create, schedule, bulk operations
registerArticleTools(server);     // 6 tools: publish to Dev.to, Hashnode, Medium
registerAnalyticsTools(server);   // 9 tools: engagement trends, best times, velocity
registerContentTools(server);     // 15 tools: AI generation, variations, scoring
registerEngagementTools(server);  // 15 tools: replies, discovery, competitor tracking
registerBoostTools(server);       // 6 tools: cross-account amplification
registerAutopilotTools(server);   // 7 tools: autonomous post generation
registerBrandVoiceTools(server);  // 5 tools: per-account voice profiles
registerAbTestTools(server);      // 5 tools: content A/B testing
// ... plus campaigns, dumps, RSS, categories, system

This means any Claude agent, in any project, can schedule posts, publish articles, analyse engagement, generate AI content, and manage boost rules. The agent working on Lunary can pull fresh metrics and create a Build in Public tweet without switching context.

Lunary MCP: 100+ tools for product analytics

The Lunary MCP connects directly to my admin API:

// lunary-mcp/src/client.ts
async function lunary(path: string, options = {}): Promise {
  const res = await fetch(`${BASE_URL}/api/admin${path}`, {
    headers: { Authorization: `Bearer ${ADMIN_KEY}` },
    // ...
  });
}

It exposes analytics (DAU/WAU/MAU, revenue, cohort retention, feature adoption), grimoire search (semantic vector search across 2,000+ articles), OG image generation with auto-scheduling to Spellcast, video script generation, and the Astral Guide AI chat.

The social tools are particularly interesting. They bridge Lunary and Spellcast:

// lunary-mcp/src/tools/social.ts
async function uploadToSpellcast(imageBuffer: Buffer, filename: string) {
  const formData = new FormData();
  formData.append('file', new Blob([imageBuffer]), filename);

  const res = await fetch(`${SPELLCAST_API_URL}/api/media/upload`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${SPELLCAST_API_KEY}` },
    body: formData,
  });
}

Lunary generates OG images (horoscope cards, moon phase graphics, cosmic state visualisations), uploads them to Spellcast's CDN, generates AI captions, and auto-schedules them with cadence guards so accounts don't over-post.

Photos MCP: 22 tools bridging macOS Photos to social

This one connects my local Photos.app library to the publishing pipeline:

// photos-mcp/src/tools/pipeline.ts
async function uploadToSpellcast(filePath: string) {
  const fileBuffer = readFileSync(filePath);
  const formData = new FormData();
  formData.append('file', new Blob([fileBuffer], { type: mimeType }), filename);

  const res = await fetch(`${SPELLCAST_API_URL}/api/media/upload`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${SPELLCAST_API_KEY}` },
    body: formData,
  });
}

I can tell Claude "post unused photos from the Concepts album to Instagram" and it will browse my Photos library via osxphotos, find unused images, upload them to Spellcast, generate AI captions, and schedule them with cadence-aware timing. It tracks which photos have been used so nothing gets double-posted.

Layer 3: the brand API (local knowledge injection)

Every AI-generated caption, comment, article, and boost reply needs to sound like me and know my domain. That's what the Brand API does.

It's a Node.js server wrapping Ollama (running llama3.1:8b locally) that intelligently injects relevant knowledge into every LLM call:

// ollama-brand/src/server.ts
const PORT = Number(process.env.PORT ?? 9002);
const OLLAMA_URL = process.env.OLLAMA_URL ?? 'http://localhost:11434';
const MODEL = process.env.MODEL ?? 'sammii-brand';
const MAX_CONTEXT_TOKENS = Number(process.env.MAX_CONTEXT_TOKENS ?? 12000);

The clever part is smart context injection. When a query comes in about crystals, it only loads crystal data. When it's about tarot, it only loads tarot cards. It analyses the query to determine which of 40+ data sources are relevant:

POST /analyze { "query": "What crystals help with protection?" }

Response:
{
  "active": ["crystals", "correspondences", "moonPlacements"],
  "estimatedTokens": 7500
}

The data sources include 30+ crystals with chakra and element mappings, 78 tarot cards (full Major and Minor Arcana), 20+ spells with ingredients and timing, Elder Futhark runes, angel numbers, zodiac signs, planetary placements, and synastry aspects. Plus 10 brand knowledge files covering writing style, metrics, platform strategy, and project details.

Spellcast uses this as the first choice for all content generation, falling back to DeepInfra if the local API is unavailable:

// spellcast/apps/api/src/lib/deepinfra.ts
async function tryBrandApi(messages: ChatMessage[]): Promise {
  const health = await fetch(`${BRAND_API_URL}/health`, {
    signal: AbortSignal.timeout(1000),
  });
  if (!health.ok) return null;

  const res = await fetch(`${BRAND_API_URL}/v1/chat/completions`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ model: 'sammii-brand', messages, temperature: 0.7 }),
  });
  // ... parse response
}

Free, local, brand-aware, and grimoire-grounded. The fallback to DeepInfra (meta-llama/Llama-4-Scout-17B-16E-Instruct) only kicks in when the local model is unavailable.

Layer 4: cross-account boost rules

When my personal account (@sammiihk) posts, my brand account (@LunaryApp) automatically likes and comments within 3-15 minutes. And vice versa. The comments aren't generic "great post!" rubbish; they're generated with the brand voice of the commenting account:

// spellcast/apps/api/src/lib/boost-queue.ts
async function generateBoostComment(rule, post, boosterAccountId) {
  // Load brand voice for the booster account
  const voice = await getBrandVoiceProfile(userId, boosterAccountSetId);

  const systemPrompt = `You are commenting as ${boosterAccount.name}.
    ${voiceProfileToPrompt(voice)}
    Write a genuine 1-2 sentence comment that references specific content.
    Never write generic comments like "Love this!" or "Great post!"`;

  return generateText([
    { role: 'system', content: systemPrompt },
    { role: 'user', content: `Comment on: "${post.content}"` },
  ]);
}

The boost cron runs every 2 minutes, finds pending actions, resolves the platform-specific post ID, and executes through Postiz's engagement API. Each action has a random delay within the configured window so it doesn't look automated.

Layer 5: autonomous pipelines

Content Creator: AI video pipeline with ML scoring

The Content Creator generates TikTok videos and Instagram carousels from persona blueprints:

// content-creator/src/lib/pipeline/content-planner.ts
async function createGenerationPlans(personaId, config) {
  // 1. Load persona blueprint -> extract content_pillars
  // 2. Count existing items this week
  // 3. Calculate needed = max(0, postsPerWeek - existingCount)
  // 4. Rotate through pillars (unused first, then least recently used)
  // 5. Mix in trending topics (probability = config.trendInfluence)
  // 6. Return GenerationPlan[] with pillar, contentType, theme, trendTags
}

Each generated video gets scored by an ML model before approval:

// content-creator/src/lib/ml.ts
modelWeights = {
  hookStrength: 0.20,    // Strongest signal
  motionLevel: 0.18,
  avgBrightness: 0.15,
  avgContrast: 0.12,
  colorVariance: 0.10,
  textCoverage: 0.08,
  duration: 0.07,
  contentLength: 0.05,
  toneScore: 0.05
}

The pipeline runs twice a week (Thursday and Sunday at 2AM), generates 3-4 items per persona, and auto-schedules approved content to Spellcast with cadence-aware timing.

Prism: fully autonomous component pipeline

Prism is my newest pipeline. It builds UI components daily with zero input:

# prism/pipeline/orchestrator.sh auto
# Runs: scout → curator → builder → recorder → publisher

# Scout (Claude Haiku + Chrome MCP)
# Browses X for trending UI interactions and component patterns

# Curator (Claude Sonnet)  
# Picks today's component, writes detailed build brief

# Builder (Claude Sonnet)
# Builds the component, demo, registry entry, verifies build passes

# Recorder (Playwright)
# Records 12-second 1080x1080 video with organic cursor movement

# Publisher (Claude Haiku)
# Uploads video + creates/scores/schedules tweet via Spellcast MCP

Each agent passes data to the next through state files in pipeline/state/queue/. The scout writes findings, the curator reads them and writes a brief, the builder reads the brief and writes code, the recorder captures it, and the publisher posts it.

Daily metrics cron

A shell script runs at 07:00 every morning, pulls fresh data from Lunary's admin API, and writes it to the shared memory layer:

# ~/.claude/scripts/daily-metrics-snapshot.sh
# Endpoints queried:
#   /api/admin/analytics/dashboard?time_range=30d    (DAU, WAU, MAU)
#   /api/admin/analytics/revenue?time_range=30d      (MRR, Pro subs)
#   /api/admin/analytics/dau-wau-mau?time_range=7d   (engagement)
#
# Output: memory/live-metrics.md
# Preserves SEO section from previous /seo Chrome scrape

This means when I ask any Claude agent "how's Lunary doing?", it reads live-metrics.md and gives me real numbers, not hardcoded guesses from the instructions file.

How it all connects

Here's a real workflow that touches most of the system:

I tell a Claude agent "publish my latest article about transit calculations"
Agent reads active-work.md to check nothing conflicts
Agent calls Spellcast MCP create_and_publish_article with Dev.to + Hashnode targets
Spellcast's API auto-generates an X thread (via Brand API for voice-consistent content)
Spellcast auto-generates a LinkedIn companion post (scheduled for next Tue/Wed/Thu 17:30)
Blog MCP publishes to the personal blog
When the X thread goes live, boost rules trigger: @LunaryApp auto-likes and comments within 3-15 minutes
Agent updates active-work.md and projects/spellcast.md with what it just did
Next morning, the metrics cron updates live-metrics.md with any traffic spike
Tomorrow's Build in Public post references real numbers from that file

One command. Eight platforms. Boost engagement. Metrics tracked. All coordinated through shared memory so the next agent knows exactly what happened.

The numbers

5 MCP servers registered, always available to every agent
260+ tools across Spellcast (140), Lunary (100+), Photos (22), Blog (6)
16 shared memory files for cross-agent coordination
40+ data sources loaded by the Brand API based on query relevance
10 projects connected through the same infrastructure
2 autonomous pipelines (Content Creator + Prism) generating and publishing daily

The total cost of running this locally: electricity for Ollama. The Brand API is free. The memory layer is free. MCP servers are free. Spellcast and the Content Creator run on my own infrastructure. The only paid API calls are DeepInfra fallbacks and Remotion rendering.

What's next in this series

This article is the overview. In the next parts, I'll deep-dive into each layer with full code walkthroughs:

Part 2: The context layer - how shared markdown files give AI agents session continuity and multi-agent coordination
Part 3: Automated content at scale - the Content Creator pipeline, persona system, ML scoring, and Spellcast scheduling
Part 4: Building a local brand API - Ollama with smart context injection and grimoire knowledge
Part 5: The autonomous pipeline - Prism's daily scout, curator, builder, publisher cycle

I built a self-managing memory system for Claude Code (and it changed how I work)

Sammii — Fri, 06 Mar 2026 12:32:12 +0000

I built a self-managing memory system for Claude Code (and it changed how I work)

Every time I started a new Claude Code session, I had the same problem: the agent had no idea what I'd been working on. It didn't know which branches were active, what decisions I'd made yesterday, or which bugs I'd already solved. I was constantly re-explaining context.

My "memory" was a single flat file (MEMORY.md) with a 200-line cap. It was a dump of random facts, project notes, and workarounds crammed together with no structure. Claude would load it, skip half of it, and miss critical details buried on line 147.

So I built something better.

The problem with flat memory

Claude Code has a built-in memory system. It reads a MEMORY.md file from a project-specific directory on session start. That's useful, but it has limits:

200-line cap: anything beyond that gets truncated
No structure: facts about six different projects, infrastructure details, and content strategy rules all jammed into one file
No session continuity: no record of what happened last session or what's in progress
No multi-agent coordination: if you run multiple Claude agents in parallel (which I do constantly), they can't see what the others are doing

I run 4-5 Claude agents simultaneously across different projects. One might be refactoring Lunary's transit engine while another is setting up infrastructure and a third is auditing the content pipeline. They were all working blind, occasionally stepping on each other's files.

The context layer

Instead of one flat file, I built a structured directory of markdown files that Claude reads and writes to continuously:

~/.claude/projects/.../memory/
  MEMORY.md              # Index (routing table, <100 lines)
  active-work.md         # Live multi-agent coordination
  live-metrics.md        # Auto-updated product metrics
  projects/
    lunary.md            # Per-project state
    spellcast.md
    content-creator.md
    ...
  worklog.md             # Rolling session history (last 30)
  decisions.md           # Architecture decisions with rationale
  infra.md               # Servers, ports, LaunchAgents, credentials
  gotchas.md             # Known bugs and workarounds
  social.md              # Social accounts, publishing config
  content-strategy.md    # Growth strategy, content rules
  writing-rules.md       # Style guide

MEMORY.md becomes a routing index

Instead of cramming everything into 200 lines, MEMORY.md is now a short table of contents. It points Claude to the right file for the current task:

Working on Lunary? Read projects/lunary.md
Writing social content? Read social.md + content-strategy.md + writing-rules.md
Debugging something? Check gotchas.md first

This means everything gets read because it's targeted. Claude doesn't skip your social media account IDs when it's debugging a database migration, and it doesn't miss your gotchas file when it's writing a blog post.

active-work.md: the multi-agent coordination file

This is the part that actually changed my workflow. active-work.md is a live file that every agent reads on startup and updates continuously:

## In Progress

### [lunary] - Refactoring transit engine
- **Started**: 2026-03-06 10:00
- **Doing**: Rewriting severity calculation
- **Files touched**: src/lib/transits.ts, src/lib/severity.ts
- **Status**: working

### [spellcast] - Article publishing pipeline
- **Started**: 2026-03-06 10:30
- **Doing**: Adding LinkedIn companion post generation
- **Files touched**: apps/api/src/routes/articles.ts
- **Status**: working

When I start a new agent, it reads this file and immediately knows what's happening across the whole workspace. It knows which files to avoid, what's blocked, and where other agents are stuck.

The key rule: update continuously, not at session end. Agents write to active-work.md when they start a task, update it when their status changes, and remove their entry when they finish. If an agent crashes mid-session, the entry stays, so the next agent knows there might be uncommitted changes.

Project files track live state

Each projects/.md follows a consistent structure:

Status: active, paused, or shipped
Current work: what's being worked on right now
Recent changes: last 10 meaningful changes with dates
Active branches: any open feature branches
Blockers: anything stuck
Key facts: stack, ports, gotchas specific to this project

These get updated as work happens, not at session end. When I switch from one agent to another, the second agent can read the project file and see exactly what the first one just did.

Decisions log captures the "why"

One of the most useful files. decisions.md records architecture and tech choices with rationale:

## 2026-03-06 - Windmill over custom cron
- Chose Windmill for job orchestration over raw LaunchAgents
- Reason: need retries, error visibility, scheduling UI
- Running locally because Chrome-dependent jobs need Mac

Three weeks from now, when I've forgotten why I chose Windmill over a simple cron job, the answer is right there. Every new agent reads it and understands the constraints without me explaining them again.

Gotchas prevent re-solving solved problems

gotchas.md is the file I wish I'd had from day one. It captures things that break repeatedly:

The Remotion source-map directory that pnpm creates empty (and the copy command that fixes it)
The better-auth version that must stay pinned because of a zod conflict
The Prisma JSON field that double-encodes if you stringify before passing to the update

Every time Claude hits one of these, instead of spending 20 minutes debugging, it checks gotchas first and finds the fix immediately.

Wiring it up across projects

The context layer lives in a shared directory, but Claude agents launched in subdirectories won't automatically find it. Each project needs two pointers:

Project CLAUDE.md gets a "Context Layer: READ FIRST" block at the top pointing to the shared memory directory
Project-specific MEMORY.md (in Claude's project memory directory) tells the agent to read the shared files

This means an agent launched in ~/development/lunary/ will:

Read lunary/CLAUDE.md and see "read the context layer"
Read its project-specific MEMORY.md and see "read active-work.md and projects/lunary.md"
Check what other agents are doing
Start work with full context

The protocol

The instructions in CLAUDE.md define a simple protocol:

Session start:

Read the index (MEMORY.md)
Read active-work.md (what's happening right now)
Read the relevant project file
Check gotchas.md if debugging

During work:

Update active-work.md when you start or finish tasks
Update project files immediately when meaningful changes are made
Add gotchas the moment you discover them
Add decisions when they're made

Session end:

Remove your active-work.md entry
Append a summary to worklog.md

The critical insight: continuous updates, not batch updates at session end. If an agent only writes at the end, a crash loses everything. And more importantly, other agents running in parallel can't see what's happening until it's too late.

What changed

Before this, starting a new Claude session felt like onboarding a new contractor every time. Now it feels like resuming a conversation. The agent knows what I was doing yesterday, what decisions I've made, what's broken, and what my other agents are working on right now.

The multi-agent coordination alone was worth it. I regularly run agents in parallel across Lunary, Spellcast, and my content pipeline. Before active-work.md, they'd occasionally both try to modify the same config file or duplicate work. Now they check what's in progress and route around it.

The whole system is just markdown files in a known location. No database, no external tools, no dependencies. Claude reads and writes markdown natively, so there's zero friction. It took about an hour to set up and has saved me from re-explaining context in every single session since.

Try it yourself

If you use Claude Code across multiple projects, the minimum viable version is:

Create a memory/ directory in your Claude project config
Put a MEMORY.md index that points to topic files
Create an active-work.md for multi-agent coordination
Add "read the context layer" to each project's CLAUDE.md
Tell Claude to update these files continuously, not just at session end

The files are just markdown. You can read them yourself, edit them, or use them as documentation. They're version-controllable if you want history. And because Claude writes them in the same format it reads them, the system maintains itself.

The best part: the context layer I built today will be the first thing tomorrow's Claude session reads. It already knows what it is, how it works, and why I built it.

One component, two layouts: the dual view pattern in React

Sammii — Sun, 01 Mar 2026 14:09:09 +0000

One component, two layouts: the dual view pattern in React

My portfolio has two completely different layouts. A grid of cards that open into modals. A full-screen vertical carousel with snap scrolling. They look nothing alike and behave nothing alike.

They share one component and one data file.

That pattern is worth writing about.

The shared data layer

Everything starts with projects.js: a flat array of objects, one per project. Four fields each: id, title, techStack, info. Both views import it directly. Neither knows the other exists.

export const projects = [
  {
    id: "lunary",
    title: "Lunary",
    techStack: "Next.js, Prisma, PostgreSQL",
    info: "A real-time astrology platform with birth charts, transit tracking, and synastry analysis.",
  },
  // ...
];

The id doubles as the GitHub repo slug, the image filename key, and the React list key. One field, three uses. That's a different article — the point here is that a single import drives both views.

ProjectItem: one component, two faces

The component takes an isGrid boolean prop. That one prop controls everything about how it renders.

interface ProjectItemProps {
  project: Project;
  isGrid: boolean;
}

export function ProjectItem({ project, isGrid }: ProjectItemProps) {
  if (isGrid) {
    return (



          {project.title}
          {project.info}
          {project.techStack}
          [Code]({`https://github.com/sammii-hk/${project.id}`})


    );
  }

  return (




            ## {project.title}

            [Code]({`https://github.com/sammii-hk/${project.id}`})


          {project.info}

          {project.techStack}



  );
}

Grid mode: compact card, description truncated on mobile, smaller code button, image above content. Carousel mode: full-width 12-column layout, title and code link on the same row, full description, no truncation.

Same data. Same component. Two completely different outputs.

Grid view: cards and modals

ProjectGrid renders a CSS grid and makes each card clickable, opening a ProjectModal for the full details.

export function ProjectGrid() {
  const [selected, setSelected] = useState(null);

  return (
    <>

        {projects.map((project) => (
           setSelected(project)}>


        ))}

      {selected && (
         setSelected(null)} />
      )}

  );
}

The grid is the browsing surface. The modal is the detail view. The card itself stays compact — its job is to catch your eye, not to tell you everything.

Carousel view: full-screen snap

ProjectView wraps the same component in a vertical scroll-snap carousel. No modal needed here — each slide IS the full view.

export function ProjectView() {
  const { scrollRef, activePageIndex, goTo, snapPointIndexes } =
    useSnapCarousel({ axis: "y" });

  return (

      {projects.map((project, i) => (



      ))}

  );
}

The carousel mode has room to breathe. Full-width image, full description, no clipping. The density trade-off is intentional: the grid lets you scan, the carousel lets you read.

ViewToggle: persisted preference

The toggle between views uses localStorage so it sticks between sessions.

export function ViewToggle({ view, onChange }: ViewToggleProps) {
  return (

       onChange("grid")}
      >


       onChange("list")}
      >
        -       

  );
}

In the parent:

const [view, setView] = useState<"grid" | "list">(() => {
  if (typeof window === "undefined") return "grid";
  return (localStorage.getItem("portfolioView") as "grid" | "list") ?? "grid";
});

const handleViewChange = (next: "grid" | "list") => {
  setView(next);
  localStorage.setItem("portfolioView", next);
};

The SSR guard (typeof window !== 'undefined') prevents a hydration mismatch on first render. The tablist role and aria-selected give screen readers the right semantics.

When this pattern works

This works well when:

The same data needs different densities (list vs grid vs card)
The same data serves different interaction models (browse vs deep-dive)
You want mobile and desktop to feel fundamentally different without duplicating state
The two layouts are genuinely complementary rather than redundant

The portfolio use case is a good fit because the data is identical in both views — the difference is entirely presentational. Grid is for scanning. Carousel is for reading. Same projects, different intentions.

When to split into separate components instead

The pattern breaks down when:

The prop branching gets deeply nested. If isGrid starts controlling more than layout — data fetching, event handling, child components — you have two components wearing one coat. Split them.
Performance matters. Both branches of ProjectItem render on every mount even if only one is shown. For large lists or heavy components, lazy-loading separate implementations is worth the duplication.
The data shapes diverge. If the grid needs a summary and the carousel needs the full object, the shared component will grow an awkward prop surface. Two components sharing a type is cleaner than one component doing too much.

The rule of thumb: one component, two layouts works when the branching is shallow and the data is identical. The moment you find yourself passing isGrid three levels deep, reach for composition instead.

Building a vertical snap carousel with touch-drag pagination

Sammii — Thu, 26 Feb 2026 17:49:06 +0000

Building a vertical snap carousel with touch-drag pagination

I needed a vertical carousel for my portfolio that felt native: snaps cleanly between items, has pagination you can drag on mobile, and doesn't require a 50kb library to pull off.

Here's how I built it with CSS scroll-snap, a minimal React hook, and a bit of custom touch handling that makes the pagination sidebar actually pleasant to use.

The CSS foundation

The whole thing starts with scroll-snap, which is more powerful than most developers realise.

.scroll {
  overflow-y: scroll;
  scroll-snap-type: y mandatory;
  height: 100%;
  scrollbar-width: none;
}

.scroll::-webkit-scrollbar {
  display: none;
}

.item {
  flex-shrink: 0;
  width: 100%;
  height: 100%;
}

.itemSnapPoint {
  scroll-snap-align: start;
}

scroll-snap-type: y mandatory tells the browser: when the user stops scrolling, always snap to the nearest snap point. scroll-snap-align: start on each item means the top of the item aligns with the top of the scroll container.

No JavaScript scroll handling. No scroll position calculations. The browser does all of it.

The hook

Rather than reinvent the wheel, I used react-snap-carousel: a minimal hook that gives you the state you need without imposing any UI.

import { useSnapCarousel } from 'react-snap-carousel';

const { scrollRef, pages, activePageIndex, goTo, snapPointIndexes } = useSnapCarousel({ axis: 'y' });

scrollRef — attach to your scroll container
pages — array of page index groups
activePageIndex — which page is currently snapped
goTo(index) — programmatic navigation
snapPointIndexes — which indices are snap targets

The carousel itself is straightforward:


  {projects.map((project, i) => (



  ))}

The pagination animation: dots to numbers

The pagination sidebar is where the UI gets interesting. Each button shows a dot at rest and the page number when active. Instead of swapping elements, both live in the DOM simultaneously and transition with CSS.

 goTo(i)}
  ref={(el) => (buttonRefs.current[i] = el)}
>

  {i + 1}

.paginationButtonDot {
  width: 8px;
  height: 8px;
  border-radius: 50%;
  background: currentColor;
  transition: opacity 0.3s ease, transform 0.3s ease;
}

.paginationButtonNumber {
  position: absolute;
  font-size: 14px;
  opacity: 0;
  transform: scale(0);
  transition: opacity 0.3s ease, transform 0.3s ease;
}

.paginationButtonActive .paginationButtonDot {
  opacity: 0;
  transform: scale(0);
}

.paginationButtonActive .paginationButtonNumber {
  opacity: 1;
  transform: scale(1);
}

The dot shrinks away as the number grows in. Both transitions happen simultaneously. No layout shift, no flicker.

Touch-drag pagination: the interesting part

The bit I'm most pleased with is the touch-drag behaviour on the pagination sidebar. On mobile you can put your finger on the dots and drag up or down to scrub through the carousel, rather than tapping individual dots.

The key function is getButtonIndexFromTouch:

const getButtonIndexFromTouch = (clientY) => {
  for (let i = 0; i < buttonRefs.current.length; i++) {
    const btn = buttonRefs.current[i];
    if (!btn) continue;
    const { top, bottom } = btn.getBoundingClientRect();
    const padding = 4;
    if (clientY >= top - padding && clientY <= bottom + padding) {
      return i;
    }
  }
  return null;
};

It loops through all the button refs, calls getBoundingClientRect() on each, and returns the index of the button whose hit area contains the touch position. The 4px padding gives a bit of forgiveness so you don't have to land exactly on the dot.

The touch handlers:

const handleTouchStart = (e) => {
  const controls = controlsRef.current;
  if (!controls) return;
  const { top, bottom, left, right } = controls.getBoundingClientRect();
  const { clientX, clientY } = e.touches[0];
  if (clientX >= left && clientX <= right && clientY >= top && clientY <= bottom) {
    setIsDragging(true);
  }
};

const handleTouchMove = (e) => {
  if (!isDragging) return;
  const index = getButtonIndexFromTouch(e.touches[0].clientY);
  if (index !== null && index !== lastIndexRef.current) {
    lastIndexRef.current = index;
    goTo(index);
  }
};

const handleTouchEnd = () => setIsDragging(false);

lastIndexRef prevents redundant goTo calls as the touch moves across a single button's area. The start handler checks whether the initial touch is within the controls container before activating drag mode, so the main content stays scrollable.

Responsive adjustments

On mobile the controls shrink down so they don't eat into the content area:

@media (max-width: 768px) {
  .controls {
    right: 4px;
    gap: 4px;
  }

  .paginationButton {
    width: 24px;
    height: 24px;
  }

  .paginationButtonDot {
    width: 5px;
    height: 5px;
  }

  .paginationButtonNumber {
    font-size: 10px;
  }
}

The scroll container uses calc(100vh - 160px) as its max height to account for nav and footer, so nothing overflows on smaller screens.

When CSS scroll-snap is enough

If you don't need the touch-drag pagination or programmatic goTo, you might not need a hook at all. Pure CSS scroll-snap with anchor links for navigation works fine for simple cases.

react-snap-carousel earns its place when you need the active page index exposed to React: to highlight the current dot, drive animations on the active slide, or tie other UI state to the scroll position. It's under 2kb minified with no dependencies beyond React. For that scope of problem, it's the right tool.

Building Accessibility That Actually Works, Not Checkbox Compliance

Sammii — Thu, 26 Feb 2026 09:00:01 +0000

Building Accessibility That Actually Works, Not Checkbox Compliance

Most developer portfolios tick the accessibility checkbox with alt tags and call it done. I built mine with proper focus management, keyboard navigation, screen reader support, and motion preferences. Not because a linter told me to, but because accessibility is engineering quality.

Here's what that actually looks like in code.

Focus trapping in modals

When a modal opens, the entire page behind it should become inert. Most implementations skip this:

useEffect(() => {
  if (!isOpen) return;

  const previouslyFocused = document.activeElement as HTMLElement;
  closeButtonRef.current?.focus();
  document.body.style.overflow = 'hidden';

  const handleKeyDown = (e: KeyboardEvent) => {
    if (e.key === 'Escape') { onClose(); return; }
    if (e.key !== 'Tab') return;

    const focusable = modalRef.current?.querySelectorAll(
      'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
    );
    if (!focusable?.length) return;

    const first = focusable[0] as HTMLElement;
    const last = focusable[focusable.length - 1] as HTMLElement;

    if (e.shiftKey && document.activeElement === first) {
      e.preventDefault(); last.focus();
    } else if (!e.shiftKey && document.activeElement === last) {
      e.preventDefault(); first.focus();
    }
  };

  document.addEventListener('keydown', handleKeyDown);
  return () => {
    document.removeEventListener('keydown', handleKeyDown);
    document.body.style.overflow = '';
    previouslyFocused?.focus();
  };
}, [isOpen, onClose]);

What this does:

Stores the trigger element -- so focus can return when the modal closes.
Moves focus to the close button -- keyboard users know they're inside the modal.
Traps Tab/Shift+Tab -- focus cycles within the modal only.
Escape closes -- standard expectation.
Restores focus on close -- without this, keyboard users are stranded.
Locks background scroll -- overflow: hidden prevents the page moving behind the modal.

Screen reader announcement

useEffect(() => {
  if (!isOpen) return;
  const announcement = document.createElement('div');
  announcement.setAttribute('role', 'status');
  announcement.setAttribute('aria-live', 'polite');
  announcement.className = 'sr-only';
  announcement.textContent = `${title} project details dialog opened`;
  document.body.appendChild(announcement);
  return () => announcement.remove();
}, [isOpen, title]);

A live region announces the modal title. The sr-only class hides it visually. Cleanup removes it so announcements don't stack.

Keyboard navigation: the tablist pattern

The view toggle follows WAI-ARIA tablist:


  {options.map((option, index) => (
     handleKeyDown(e, index)}
    >{option.label}
  ))}

const handleKeyDown = (e: React.KeyboardEvent, index: number) => {
  let newIndex = index;
  switch (e.key) {
    case 'ArrowRight': case 'ArrowDown':
      newIndex = (index + 1) % options.length; break;
    case 'ArrowLeft': case 'ArrowUp':
      newIndex = (index - 1 + options.length) % options.length; break;
    case 'Home': newIndex = 0; break;
    case 'End': newIndex = options.length - 1; break;
    default: return;
  }
  e.preventDefault();
  onChange(options[newIndex].value);
};

Only the active tab is in the tab order (tabIndex={0}). Arrow keys move between tabs. Home/End jump to first/last. This matches browser-native tab interfaces.

The grid: cards as list items



    {projects.map(project => (
       {
          if (e.key === 'Enter' || e.key === ' ') {
            e.preventDefault(); openModal(project);
          }
        }}
      >{/* card content */}
    ))}

aria-haspopup="dialog" signals a modal will open. Both Enter and Space trigger it -- matching native button behaviour.

Reduced motion: the nuclear option

@media (prefers-reduced-motion: reduce) {
  * {
    transition-duration: 0.01ms !important;
    animation-duration: 0.01ms !important;
  }
}

This kills every animation globally. Setting 0.01ms instead of 0 ensures transitionend events still fire -- so JavaScript callbacks don't break.

focus-visible vs focus

.focus-ring:focus { outline: none; }
.focus-ring:focus-visible {
  outline: 2px solid var(--accent-color);
  outline-offset: 2px;
}

:focus-visible only fires for keyboard navigation. Mouse users don't see outlines. Keyboard users get clear indicators. Both groups get what makes sense for their input method.

Skip links

.skip-link { position: absolute; top: -40px; left: 0; transition: top 0.2s; }
.skip-link:focus { top: 0; }

Hidden by default, appears on Tab. Lets keyboard users jump past navigation. Light/dark mode aware.

Why this matters

If your modal doesn't trap focus, it's a bug. If your toggle doesn't respond to arrow keys, it's broken. If your animations ignore motion preferences, you're overriding a system-level accessibility setting.

Accessibility isn't a feature you add at the end. It's the same category as "buttons should be clickable" and "links should navigate". It's engineering quality.

The code samples here aren't theoretical. They're running in production. And they took about the same effort as building the visual design -- because when you build accessibility in from the start, it's just part of the component architecture.

I'm Sammii, founder of Lunary -- an astrology app that teaches you to read your own birth chart. When I'm not calculating planetary transits, I'm building focus traps and obsessing over keyboard navigation. Follow the build on Dev.to and Hashnode.

Cursor-Reactive Gradients: Making CSS Respond to Mouse Position

Sammii — Wed, 25 Feb 2026 18:34:48 +0000

Cursor-Reactive Gradients: Making CSS Respond to Mouse Position

The logo on my portfolio site changes colour as you move your mouse. Not with a library. Not with a pre-built animation. With about 15 lines of maths that convert cursor position into RGB values and generate a three-point radial gradient in real time.

And when you scroll, the same gradient system responds using sine and cosine wave functions.

Here's how the whole thing works.

The core function: gradientCreator

The entire gradient system lives in one function that takes two numbers and returns a CSS background:

export const gradientCreator = (xPc: number, yPc: number) => {
  const colourCreator = (number: number) => {
    const colour = Math.floor((255 / 100) * number);
    return colour < 255 ? Math.floor((255 / 100) * number) : 255;
  };

  const colour1 = colourCreator(xPc);
  const colour2 = colourCreator(yPc);
  const colour3 = 255 - colourCreator(xPc);

  return `radial-gradient(at 50% 0, rgb(${colour1}, ${colour3}, ${colour2}), transparent 50%),
    radial-gradient(at 6.7% 75%, rgb(${colour3}, ${colour2}, ${colour1}), transparent 50%),
    radial-gradient(at 93.3% 75%, rgb(${colour2}, ${colour1}, ${colour3}), transparent 50%),
    lavender`;
};

Two inputs: xPc (cursor X as a percentage of the viewport) and yPc (cursor Y as a percentage).

colourCreator maps 0-100% to 0-255 RGB range. Simple linear interpolation: Math.floor((255 / 100) * number).

Three colours are derived from two inputs:

colour1 = colourCreator(xPc)
colour2 = colourCreator(yPc)
colour3 = 255 - colourCreator(xPc) -- the inverse of colour1

The channel rotation trick

Here's the part that makes it actually work. The three radial gradient points use the same three values but in different order:

Gradient point	Position	RGB order
Top centre	50% 0	(c1, c3, c2)
Bottom left	6.7% 75%	(c3, c2, c1)
Bottom right	93.3% 75%	(c2, c1, c3)

By rotating which channel gets which value at each point, moving in any direction produces a smooth colour shift. You get a full spectrum of transitions from just two input numbers.

The positions form an equilateral triangle on the viewport, which distributes the colour mixing evenly.

The fallback colour is lavender -- so if all three gradients are transparent at any point, you still get something pleasant.

CSS mask-image: gradient through text

The gradient doesn't paint a box. It paints through the shape of text:

.logo {
  -webkit-mask-image: url('/sammii.png');
  mask-image: url('/sammii.png');
  -webkit-mask-repeat: no-repeat;
  mask-repeat: no-repeat;
  -webkit-mask-size: contain;
  mask-size: contain;
}

The PNG is a text shape -- the word "sammii". The gradient is the element's background, but mask-image clips it to only show through the mask shape.

The result: the text itself becomes the gradient canvas. Move your cursor and the letters shift through colours.

Scroll-driven: sine waves replacing cursor input

In the portfolio container, when the user scrolls, the same gradientCreator function responds -- but instead of cursor position, it gets values driven by trigonometric wave functions:

const scrollPercent = (scrollTop / (scrollHeight - clientHeight)) * 100;

const wave1 = Math.sin((scrollPercent / 100) * Math.PI * 6) * 50 + 50;
const wave2 = Math.cos((scrollPercent / 100) * Math.PI * 4) * 30;

const yValue = Math.max(0, Math.min(100, wave1 + wave2));
const xValue = Math.sin((scrollPercent / 100) * Math.PI * 2) * 25 + 50;

Breaking this down:

wave1: a sine wave that oscillates 6 complete cycles over the full scroll distance, with an amplitude of 50 centred at 50 -- so it swings between 0 and 100
wave2: a cosine wave at a different frequency (4 cycles), with a smaller amplitude of 30 -- this adds variation so the colour change isn't predictable
The Y value is the sum of both waves, clamped to 0-100
The X value gets its own separate sine wave at yet another frequency (2 cycles)

The different frequencies mean the X and Y inputs never repeat the same pattern at the same scroll position.

Smoothing with lerp

Raw values from scroll events are choppy. The animation uses linear interpolation to smooth everything:

const lerp = (current: number, target: number, factor: number) => 
  current + (target - current) * factor;

currentX.current = lerp(currentX.current, targetX.current, 0.2);
currentY.current = lerp(currentY.current, targetY.current, 0.2);

Each frame, the current value moves 20% of the remaining distance toward the target. This creates an ease-out effect -- fast initial response that gradually settles.

The animation runs on requestAnimationFrame, so it's synced to the display refresh rate.

Pointer vs scroll: conflict resolution

Both pointer movement and scroll drive the same gradient function. Without coordination, they'd fight:

const isScrollingRef = useRef(false);
const lastScrollTimeRef = useRef(0);

// In scroll handler:
isScrollingRef.current = true;
lastScrollTimeRef.current = Date.now();

// In pointer handler:
if (isScrollingRef.current && Date.now() - lastScrollTimeRef.current < 500) {
  return;
}
isScrollingRef.current = false;

Scroll takes priority while active. Once scrolling stops for 500ms, mouse movement resumes control.

The whole thing in context

Fifteen lines of colour maths. A CSS mask. Some trigonometry. A lerp function. That's the entire system.

No animation library. No canvas. No WebGL. Just the browser's native CSS gradient engine doing what it's good at -- painting pixels fast -- driven by a bit of arithmetic that maps human input to colour space.

The best part: because gradientCreator is a pure function (two numbers in, CSS string out), you could drive it with anything. Microphone volume. Accelerometer data. API response times. The abstraction doesn't care where the numbers come from.

I'm Sammii, founder of Lunary -- an astrology app that teaches you to read your own birth chart. When I'm not calculating planetary transits, I'm building gradient systems and obsessing over keyboard navigation. Follow the build on Dev.to and Hashnode.