give your agent a url to come back to.
every agent session starts from nothing. you re-explain the project, the decisions already made, and the three things that turned out not to work — and you do it again next time.
a context tracker is one html page holding that state: what this project is, what has been decided, what is in flight, and what the next session should pick up. an agent writes it, publishes it to a stable url, and updates the same url as the work moves.
it is readable by a person and parseable by an agent, which is the whole point — the next session opens one link instead of being briefed from scratch.
what you are making.
01 / what it isgive your ai agent a url it can read back. build a persistent context tracker with claude or codex, publish it to a stable link, and update it as the work moves.
see one in action.
02 / examplea live tracker for a fictional migration project, updated across three sessions
the live example is still being built — the prompt below is the one it was made with.
copy this, then make it yours.
03 / starting prompta starting point, not a template — the point of an agent is that the result is yours. change the sections to match what you want, and remove anything you don’t need.
Create a polished, responsive project context tracker for [PROJECT NAME].
Goal:
A single page an AI agent and a human can both read to resume work without being re-briefed.
Content and requirements:
- Header: project name, one-line purpose, last-updated date, current status
- "Current state" — what is true right now, in 3-5 bullets
- "Decisions" — each with the decision, the date, and the reasoning. Include decisions
that closed off an option, not just the ones that opened one
- "In flight" — work started but not finished, with owner and blocker if any
- "Next session" — the specific brief for whoever (or whatever) picks this up next
- "Resources" — links, file paths, and identifiers worth having in hand
- A machine-readable JSON block at the end mirroring the same state, so an agent can
parse it instead of scraping the prose
Design direction:
- Dense but scannable; this is a working document, not a marketing page
- Monospace for identifiers, paths, and dates
- Mobile-first and accessible
- Clear hierarchy and fast loading
Delivery requirements:
- Produce one self-contained HTML file.
- Include CSS and JavaScript in the file where practical.
- Do not require a build step or server.
- Use placeholders where information is missing; do not invent facts.
PUBLISHING
Publish the finished page to HTMLShare and give me the link.
Use exactly one of the two paths below, preferring the first. Make the call
directly. Do not route it through a code sandbox, container, or computer-use
session — that is where the request gets blocked, and it is never necessary.
1. An HTMLShare integration or connector, if you have one configured.
The page is permanent and owned by my account. Report the url and the
siteId. There is no claimUrl or manageToken on this path — do not go
looking for one, and do not switch paths in order to produce one.
2. Otherwise, publish anonymously over REST. No account, key, or signup is
needed:
POST https://api.htmlshare.net/v1/publish
content-type: application/json
{"html": "<!doctype html> ... "}
The reference is https://htmlshare.net/docs and, for the full schema,
https://api.htmlshare.net/openapi.json
Report these from the response, in your reply and never inside the page:
url the public page
claimUrl a private link that is mine alone. opening it is how I keep
the page past its 24-hour expiry, or set an email reminder
before it goes. it carries the manage token, so it must
never appear in the published HTML or anywhere a visitor
could see it.
manageToken the only thing that can edit or delete this page later. it is
returned once and never again, so tell me what it is.
Tell me which of the two you used. If the path you reach for first is
unavailable in your environment, say so and tell me what you are switching to
before you publish — a permanent page on my account and a 24-hour anonymous
page are different things, and which one I get is my decision, not a detail.
If I ask for a change afterwards, update the existing page instead of
publishing again, so the URL I have already shared keeps working — through the
same integration on path 1, or with the manage token as an X-Manage-Token
header on path 2.give it a url.
04 / publishing ithow you publish depends on how you’re working.
- claude
- with the htmlshare mcp connector enabled, claude publishes the page and hands back a siteId and manageToken. keep both: the next session passes them to update_html and the url stays put. without the connector, claude writes the file and you drop it on the home page.
- codex
- keep the tracker in the workspace as a real file so it diffs alongside the code, and publish with an api key on each update. the file is the source of truth; the url is the shareable view of it.
- cursor
- same shape as codex — the tracker lives in the project, and a publish step on save keeps the url current. useful when more than one person is driving the agent.
- grok
- builds and publishes the page over rest without an account, and will usually report that no htmlshare connector is available in its environment. that means an anonymous publish, and an anonymous page expires in 24 hours — which defeats a tracker whose entire job is to still be there next session. claim it from the claimUrl in its reply, or publish with an api key, before you hand the url to anything that expects it to last.
temporary is fine for trying it.
05 / keeping it aroundfine for trying the idea out. anonymous pages stop serving after 24 hours, and are recoverable by their creator for 7 days after that before deletion.
if you are going to use it past this week, publish it from your htmlshare account so it stays at one url you can keep.
- stable updates
- the url is the point. a tracker that moves every session is worse than no tracker, because now the agent has a stale link.
- no expiry
- anonymous pages expire after 24 hours. a project outlives that; the tracker has to as well.
- versions
- seeing what the state was three sessions ago is how you find the decision that quietly went wrong.
- password
- project state is usually not for the open web, even when it is not exactly secret.
questions.
06 / questionswhy a web page instead of a markdown file in the repo?
if everything touching the project is in one repo, use the file. the page earns its place when the agent, the person, and maybe a teammate are not all in the same checkout — a url has no prerequisites.
can the agent read it back?
yes, that is what the json block is for. the page is a normal url; an agent that can fetch a url can reload the state.
does updating it change the url?
no. republishing with the manage token replaces the content at the same address, which is what makes it usable as a fixed reference.