claudesphere
GitHub

The claudesphere story

Seven short chapters, from why I built it to the real sphere at the end. Scroll to follow along.

Chapter 1 of 7

Why I built a memory

I work with Claude Code most days. After a while I noticed that all of that work was invisible. Every session ends up as a long log file, and nobody reads a log. I wanted a place I could look at instead.

So I built "Memory of Us". It takes every prompt I have sent, turns each one into a single dot, and arranges the dots on a sphere that slowly turns. At the centre is the first day. At the surface is today. My projects grow outward from the middle like rays.

The name is deliberate. It is not a dashboard about my productivity. It is a picture of a working relationship between me and an AI, drawn from the things I actually said to it.

It also lives on my desktop. A small Mac app puts the sphere behind my icons as a live wallpaper, so the months of work are something I see every day, not something I have to open.

The page also reads like a short letter from Claude to me. Its text says "each dot is one message you sent me", and its findings are written in Claude's voice, for example "linked in my memory". That is part of the idea: the sphere is a memory that both of us share.

Chapter 2 of 7

Transcripts on my own machine

Claude Code writes every session to disk as a transcript: one file per session, one line per event, in a folder inside your home directory. Nothing needs to be exported. The files are already there.

My aggregation script reads those files and nothing else from them. For each session it keeps the lines that are my own typed prompts, and the lines from Claude that say which tools it used and which model answered. Timestamps come from the same lines.

It deliberately ignores a lot. It skips tool results, because those are Claude's tools talking back, not me. It skips lines Claude Code marks as meta, and lines from sub-agents (helpers that Claude launches in the background). It skips slash-command echoes, task notifications, system reminders, and caveat notices. A line that says I interrupted Claude is not counted as a prompt, but it is remembered as a flag on the prompt before it.

One practical detail: Claude Code eventually deletes old transcripts. So each time the script runs, it saves what it found into a local archive and merges new sessions into it. That way the sphere keeps growing instead of forgetting.

A second, smaller source: Claude's own memory notes, the short markdown files it keeps for each project. The script only counts these, and sorts them into themes. It does not read them into the sphere.

Everything happens on my machine. The scripts use only Python's standard library. There is no server and no upload.

Chapter 3 of 7

What the dots remember

Each dot is one prompt, so most statistics are about a prompt, a session, or a project. I never show a number for its own sake. Each one changes something you can see.

Time and position. Every prompt has a timestamp. The day it was sent decides how far from the centre its dot sits: the first day is near the center, today is at the surface. The same day also drives the default colour, a ramp from dark ember through orange to pale gold, so older work glows deep and recent work glows bright.

Project and theme. Each prompt is assigned to a project (see chapter 4 for how). Each project belongs to a theme. Projects become clusters of dots. Themes become regions of the sphere, with a label.

Words. The number of words in a prompt, counted by splitting on spaces. It is shown when you hover or click a dot, and it feeds a few findings, such as the typical length of a prompt and how many are very short.

Actions that followed. For each prompt, the script counts how many tool calls Claude made before my next prompt: reading files, running shell commands, editing files, searching, browsing. This is the size of the dot. A short prompt that sets off a lot of work gives a big dot.

Time of day. The hour a prompt was sent, in local time. A second colour mode paints the sphere by hour, from morning to evening, and one finding shows when my days start and stop.

Pushback, thanks and interruptions. Three flags on a prompt. Pushback is decided by phrasing: the start of the prompt looks like "no", "wrong", "again", "still", "why", "stop", or contains things like "doesn't work", "broken", "you forgot", "I said". Thanks is decided by words like "thanks", "perfect", "great", "love it", "works now". Interruption means Claude Code logged that I stopped it mid-task. In the third colour mode, pushback and interruptions turn ivory and glow, thanks turns gold and glows, and everything else fades back. These are estimates from wording, and the page says so.

Sessions. A session is one Claude Code conversation. Its prompts are joined by faint curves, in order. For each session the script also stores: how many prompts it had, its active minutes, how many tool calls, and how many sub-agents Claude launched. Active minutes are computed by adding up the gaps between consecutive events, but a gap counts only if it is under 15 minutes, and any single gap counts at most 15 minutes. So a lunch break does not count as work.

Sessions that cross projects. When a session moves from one project to another, the curves between the two clusters show it as a thin flow line.

Tools and models. Across all sessions the script totals which tools Claude used (terminal, file edits, file reads, browser actions in Chrome, web lookups, sub-agents) and which models answered (Opus, Sonnet, and others). These become two summary strips in the side panel: a split bar of kinds of action, and a share of replies per model.

Memory notes. The count of Claude's memory notes per theme is compared with the share of my prompts per theme, side by side, so I can see where my time goes versus what Claude remembers. Where two projects are connected in those notes, a faint link joins their clusters, with a spark travelling along it.

Streaks, busiest day, longest session, and "loose ends" (projects with something untested in the notes that have gone quiet for two weeks) are small findings computed from the same fields.

Chapter 4 of 7

From transcripts to a sphere

The pipeline

It is five small steps, run by one shell script.

Collect. The script scans Claude Code's transcript folders for session files and reads them line by line. Broken lines are skipped.

Aggregate. For each session it builds a list of prompts, each with: time, word count, number of tool calls that followed, which project folders Claude touched, a short lowercase piece of the text for matching, and whether I interrupted. It also totals tools, models, sub-agents and output tokens per session. It merges the result into the local archive and writes a session file.

Label and group. This is the human part. A hand-written dictionary lists my projects, gives each a label, and puts each in one of ten themes. A prompt gets its project in this order. First: the project folders that appear in the file paths Claude touched after the prompt. If none, a keyword match on the prompt text. If still none, the project of the previous prompt in the same session. If still none, the project that dominates the session, then the folder it started in, then a default. This ordering means a vague prompt like "continue" still lands where the conversation was.

Build the data file. A second script turns this into one compact data file: a list of projects, a list of sessions with their summaries, and a list of prompts, each with session, project, minute-accurate timestamp, words, actions, a number encoding the three flags, and a short text snippet. It also writes a small file of tool and model totals, and counts the memory notes per theme.

Fill the template. A last script takes the HTML template and pours the data file and the totals into it. The output is a single page.

The design of the sphere

Time runs from the center outward. A prompt's radius is set by its day: the first day sits near the centre, today near the surface, with a small random jitter so dots do not stack.

Each theme gets a direction, spread over the sphere evenly with a spiral. Each project gets a direction near its theme's, and a repulsion loop nudges clusters apart until they do not overlap. A project's width grows with the square root of how many prompts it has. So a project looks like a ray fanning outward, narrow at the start, wide at the end.

Themes are drawn as hollow rings with faint curved lines to the centre. Projects connect to their theme with another curved line. A faint shell of tiny dots marks the outer surface.

Faint session curves join consecutive prompts of a session. Memory links join project clusters. Both are drawn as curves bent away from the centre, so they do not cut through the middle.

It is drawn on a 2D canvas, not a 3D engine. A small projection function handles rotation, zoom and depth: farther dots are dimmer and smaller. Additive blending makes overlapping glows add up like light.

The interactions

Drag to rotate. It keeps a little momentum, and turns slowly on its own when idle (unless the person's system asks for reduced motion). Scroll to zoom.

Hover a dot to read its prompt, its time, project, word count and how many actions followed. Click it to light up its whole session. Click a project cluster to open it into its single dots and see its numbers: share of prompts, actions per prompt, days since last message, pushback rate, first day, usual hour, and a weekly sparkline.

On the right, a tree of themes, projects and prompts. On the left, findings, and a theme filter that dims the rest.

Three colour modes: when, time of day, pushback.

A date strip under the sphere shows prompts per day. Drag across it to pick a range, and everything outside fades. Double click clears it. A Replay button grows the sphere day by day from the centre.

Why one HTML file

I wanted this to be something I can open by double click, move to another machine, or hand to a wallpaper window, without a server or an install. All the data, style and code live in one file. That also makes the privacy story simple: nothing is fetched, nothing is sent. (The one exception in my own version is the web fonts, which fall back to system fonts if offline.)

Chapter 5 of 7

The sphere behind my desktop

The wallpaper is a small native Mac app written in Swift. It has one source file. It is a menu bar app with no Dock icon.

What it does at launch. For every connected screen it creates a borderless window the size of that screen. The window is set to the desktop window level, which is the layer where the desktop picture lives, so it sits behind the icons and every normal window. It is set to appear on all Spaces, stay put, ignore Cmd-Tab, and ignore mouse events. That last one means clicks pass through to the desktop. You cannot rotate the wallpaper with the mouse.

Inside each window is a WebKit web view (the same engine as Safari) with a transparent background. It loads a local file, wallpaper.html, with a fragment "#wall" on the end. That fragment tells the page to switch to wallpaper mode.

In wallpaper mode the page hides the side panels, the strip, the buttons and the tooltip. The sphere fills the window. It turns slowly on its own, tilts gently, and redraws at about 30 frames per second to save power. Every nine seconds it picks a random bright dot on the front and lights its session. Every 22 seconds a caption in the lower left fades to a new line, one of the findings from the side panel. The pixel ratio is capped at 1.5.

The menu bar item. A small symbol "◍" sits in the menu bar. While refreshing it changes to "◌", and if a refresh fails it shows "◍!" with the last error line in the menu. The menu has four actions: refresh data and reload, reload the view only, open the full interactive page in the browser, and quit. A disabled line shows "Data from" and the last refresh time, read from a small text file.

How it refreshes. On launch, and then on a timer every six hours, the app runs refresh.sh through the shell. That script runs the three Python steps (aggregate, build, fill) with the system Python in isolated mode, then writes the time to the text file. When it succeeds, the app closes and recreates its windows, which reloads the page. It also rebuilds the windows if the display setup changes, for example when a monitor is plugged in. There is no other scheduler: no launch agent that I could find, so refresh happens only while the app is running.

The app finds its folder through an environment variable, or by default a folder called memory-sphere under a Research folder in the home directory.

Trade-offs, honestly. It reads only local files and the browser never leaves the machine. But the wallpaper is not interactive. It is fixed to one folder layout. It runs a web view per screen, which costs some CPU and battery, so it is capped at 30 frames per second. The refresh depends on the app being open. Fonts load from the web if possible and fall back to system fonts offline. The app bundle is a small hand-made package with a minimum macOS version of 13.

Chapter 6 of 7

Make your own sphere

You need a Mac (or Linux) with Claude Code already used for a while, and Python 3. There is nothing to install: the code uses only the standard library.

The public version is called claudesphere: https://github.com/valkiii/claudesphere

1. Clone it and go into the folder.

Terminal
git clone https://github.com/valkiii/claudesphere && cd claudesphere

2. See the demo first. It uses synthetic data and does not read your transcripts.

Terminal
python3 -m memory_sphere demo
open demo/index.html

3. Copy the config.

Terminal
cp config.example.yaml config.yaml

If you do not have PyYAML, use config.example.json instead. It has the same content.

4. Edit the project mapping. Under "themes" list the big regions you want (for example web, data, infrastructure, writing). Under "projects", give each project an id, a label, a theme, some folder patterns, and a few keywords. Folder patterns are matched against the folder names Claude touched after a prompt. Keywords are regular expressions matched against the prompt, used only if no folder matched. Set the timezone to yours. A "default_project" catches the rest.

5. Run the pipeline.

Terminal
python3 -m memory_sphere run --config config.yaml

6. Open the page.

Terminal
open memory-sphere.html

The command prints how many prompts and sessions it found. If many prompts fall in your default project, add more folder patterns or keywords and run again. By default the output contains no prompt text (include_text is false), so the hover shows the fields but not the words. The README of the repo explains the option if you want it.

Ask Claude to do it with you

Open Claude Code in the cloned folder and paste this:

Prompt for Claude Code
This repo turns my Claude Code transcripts into a 3D sphere (python3 -m memory_sphere). Read README.md and config.example.yaml first. Then: 1. Create config.yaml for my projects. List the folders under ~/.claude/projects (names only, do not read any prompt text) and propose themes, project ids, labels, folder patterns and keywords. Show me the proposal before writing the file. 2. Keep output.include_text false unless I say otherwise. 3. Run python3 -m memory_sphere run --config config.yaml, open memory-sphere.html, and tell me how many prompts landed in the default project so we can fix the config. 4. Never read or print prompt text, and never commit sessions.json, data.json, config.yaml or the built HTML.

This is a shortened version of the prompt in the repo README, which has a longer one.

Make it a wallpaper

The public repo covers the sphere itself: the pipeline and the single HTML page. It does not include the Swift wallpaper app, the refresh script or the menu bar item. Those live only in my private project. To get a wallpaper you would need to build a small Swift app along the lines of chapter 5: a borderless window at desktop level, a transparent web view loading your memory-sphere.html, mouse events off. You could ask Claude to write it for you from chapter 5. Note that the public page has no special wallpaper mode, so you would need to add one (hide the panels, auto-rotate, cap the frame rate).

Chapter 7 of 7

The sphere, to touch

This is the sphere itself, built from invented data, but at the same size as mine: the same number of dots, projects and themes. Nothing here is a real prompt. Hover a dot to see its fields: when it was sent, which project and theme it belongs to, how many words it had, how many actions followed, and whether it reads as pushback or thanks. Drag to turn it. Scroll to zoom.

If you build your own, it will look different, because your work looks different. That is the point.

Demo with synthetic data

This is the real page from the repo, running on invented data. Inside the frame the mouse wheel zooms the sphere, so use the keys or the page edge to keep scrolling.

Open it full screen

Comments

Sign in with GitHub to leave a comment or react.

← Portfolio