How eng.town works

Before anything works, you need a team. Signing in for the first time creates one for you, and an invite link from a teammate's admin puts you on theirs instead. Sort that out first, then run this.

What it does, in order

1. Shows you what it will and will not collect, and waits for Enter. Only allowlisted work repos are eligible; everything else stays on your machine.
2. Asks you to approve this Mac. It prints a link and a code — open the link, confirm the code, and it carries on by itself. This is the step that grants the machine permission to upload, and you can revoke it later from Devices.
3. Asks one question: may eng.town run AI analysis on the sessions you share? Enter for yes, n for no, changeable any time in Settings. If nobody is at the keyboard — a scripted or fleet install — it stays off and asks you next time.
4. Sets everything up: the hourly background job, the Claude Code hook, the /sync-sessions command, eng-town on your PATH, and the eng-town MCP server in ~/.claude.json.
5. Classifies the history already on your machine and tells you how many sessions are eligible. It uploads none of it.
6. Self-checks and prints what, if anything, is wrong.

Two things to do afterwards

1. Open a new terminal (or run exec $SHELL) so your shell picks up the PATH change, and restart Claude Code so it loads the MCP server.
2. Choose what to share. Nothing from your history has gone anywhere yet:

eng-town review

It lists what is waiting, grouped by repo, with select-all per repo. Or use /sync-sessions inside Claude Code. From then on you are asked as each session ends, and you can set a repo to automatic if you would rather not be.

What your agents get

The MCP server registers as eng-town and adds five read-only tools: search your sessions, list recent ones, summarise one, fetch one, and find related work. It reuses the device key from the install, so there is nothing new to log into. Ask your agent “what did I do about the webhook last week?” and it can go and look instead of asking you.

Is it working?

The dot in the top right of this app is your collector. Green means it synced in the last four hours, amber means it has been quiet for a while, red means nothing for two days. On the machine itself:

eng-town status    # what is synced, staged and skipped
eng-town doctor    # config, background job, hook, server — all in one

Doing it by hand instead

The one command is eng-town install with the download in front of it, so every step has a switch. --no-path leaves your shell config alone, --no-mcp skips the ~/.claude.json entry, --skip-hooks and --skip-launchd do what they say. Re-running eng-town install is safe: every step checks before it acts, so it repairs what is missing and leaves the rest alone.

One name, two spellings

The command is eng-town. The older name agent-sync still works and still names the folder on disk (~/.agent-sync) — the background job and the Claude Code hook point at it, so it stays put rather than being renamed underneath a working install.

When it runs

• Every hour, from a launchd job.
• The moment a Claude Code session ends, from a hook — so a session you just finished is usually here before you have switched windows.
• Whenever you ask: eng-town now.

What it reads

How it decides a session belongs here

A session is uploaded only if it is about a repo on the allowlist. The collector works that out the same way git does: it resolves the session's working directory to a checkout, and worktrees, Conductor workspaces and Codex worktrees all resolve back to their parent repo.

Some sessions have no useful working directory — Buzz runs from ~/.buzz, for instance. For those, the collector looks at which files the agent actually edited. Reads alone are never enough; at least one write into an allowlisted repo is required.

Anything it cannot place is left alone and listed by eng-town unresolved, so a mis-classification is visible rather than silent. eng-town explain <session> prints the full reasoning for one transcript.

What is removed before anything leaves your Mac

• Secrets are redacted, replaced in place with [REDACTED:anthropic] and the like. Fourteen pattern families are matched — Anthropic, OpenAI and GitHub tokens, AWS keys, Slack and Google tokens, Stripe keys, JWTs, bearer headers, private key blocks, passwords inside URLs, and SOMETHING_SECRET=… style assignments.
• Long tool output is truncated to about 4 KB — the head and the tail, with a marker saying how much was dropped. Your text and the agent's text are never truncated.
• Images and attachments are dropped at parse time.

It only ever sends what is new

The collector remembers how far it got in each session and sends only the messages after that point. If a run is interrupted it picks up where it stopped; if it sends something twice the server recognises it and writes it once. A long-running session is uploaded as it grows.

Commands worth knowing

Your agents can read this archive

eng-town mcp --install registers eng.town as an MCP server in Claude Code. It adds five read-only tools — search sessions, list recent ones, summarise one, fetch one, and find related work — so an agent can pull context out of what you did last week instead of asking you to explain it again. It reuses the device key you already have; there is nothing new to log into.

What each number means

These definitions are worth reading once, because two people looking at the same chart should agree on what it says.

Sub-agent usage is folded into its parent

When an agent spawns sub-agents, their tokens and cost are added to the session that started them. A session's number is the whole cost of that piece of work, not just the top-level conversation. If any sub-agent used a model with no price, the parent's cost is shown as unpriced rather than as a number that is quietly too low.

What the people table is for

Average prompt length, short-first-prompt rate, cache-hit rate and tool calls per turn are there to answer one question: is this person giving their agents enough context? A very short first prompt and a low cache-hit rate usually means an agent that had to rediscover the problem. There is deliberately no automatic “quality score” — the columns are raw material for a conversation, not a ranking.

How a run works

  Monday 08:00   export your week -> upload -> start the agent -> hang up
                 (a coordinator on Opus 5, reading via Haiku 4.5 workers)

  ~15 min later  the agent writes insights.json and goes idle
                 -> Anthropic calls our webhook
                 -> we download it, validate it against a schema, write the rows

  you refresh    the Insights tab has your week on it

If the webhook never arrives, a sweep on the hourly tick finishes the run properly instead. The result lands later, never not at all.

When it runs

The rule that makes it trustworthy: the model does not supply facts

• Every number is computed here, not written by the agent. Session counts, tokens, cost and dates are derived from the database using the session ids the agent grouped. The model is good at grouping and bad at arithmetic, and we already have the arithmetic.
• Every quote is checked against the session it cites. A finding links to the transcript it came from, so you can always go and read the original.
• Output is validated before anything is stored. The agent's file is parsed and checked against a schema first; a run that fails validation is marked failed and writes nothing at all, rather than storing model output as if it were data.

What it costs, and what stops it running away

• A real run over a full week measures roughly $6 and takes 10 to 15 minutes.
• Each run has a hard $10 cap enforced by the platform. It cannot exceed it.
• After three consecutive failures automatic runs stop until one succeeds — so a structurally broken run costs at most $30 once, not $30 an hour. The Generate button still works, and a successful manual run clears the block.

Using your own Anthropic key

You can supply your own key on the Insights tab, and your runs are then billed to your Anthropic account. The key is write-only by construction: nothing in the stack can return it to any browser — including yours, and including an admin's. You can replace it or clear it, never read it back.

The formula

cost = ( input          x price_in
       + output         x price_out
       + cache_read     x price_cache_read
       + cache_write_5m x price_5m
       + cache_write_1h x price_1h ) / 1,000,000

Cache tokens are priced differently from fresh ones. Against the input price: a cache read costs a tenth, a five-minute cache write 1.25 times, and a one-hour cache write twice. That is why a session with a high cache-hit rate can be enormous in tokens and modest in dollars.

Where the prices come from

A price table you can edit, under Admin. Each row matches a family of model names, so a new point release inherits its family's price automatically. Changing a price changes the numbers everywhere, because the cost was never baked into the session row by the uploader.

An unknown model shows a dash, never a guess

If a session used a model with no price on file, its cost is null — the table shows — and the totals carry a footnote saying how many sessions were unpriced. Tokens are still counted. We would rather show you a visible gap than a total that is silently too low.

The caveat that matters

This is not your bill. Claude Code on a subscription does not charge per token, so the dollar figure will not reconcile against an invoice. It is the right number for comparing — this session against that one, this week against last, one person's usage against another's — and the wrong number for accounting.

The one exception is Insights: those runs go through the Anthropic API and are genuinely billed. The cost shown on a run is what it actually cost.

The database

The raw archive

Alongside the parsed version, the collector keeps a gzipped copy of the original transcript — already redacted, the same as everything else. It goes into a private bucket that no browser can read directly. When you download one, the dashboard first checks in the database that you are allowed to see that session, then mints a link that expires in 60 seconds.

Nothing expires

There is no retention policy and no automatic cleanup. Revoking a device does not remove the sessions it uploaded. The archive is the point of the product — a session from six months ago should still be there.

You can delete your own sessions from the dashboard. Deleting one also records a tombstone, so the collector on your Mac will not helpfully upload it again on the next run.

Three modes, set per repo

When you get asked

• At the end of a Claude Code session, a small dialog shows what it was — the title, the repo, the app, how many messages, and your first few prompts — with Sync, Skip, or Always for this repo.
• Once an hour, if several are waiting, a single list to tick through. Never more than one list open at a time.
• Whenever you want: eng-town review, or the /sync-sessions skill inside Claude Code.

Not answering is not a yes. A dialog you ignore for 60 seconds closes and asks again later.

Marking something private

Type #private or #nosync anywhere in a chat, or drop an .agent-sync-ignore file in a folder, and those sessions are never offered and never uploaded — even inside a work repo. The folder rule also covers any session that reads or edits a file in that folder, wherever it was started. If one was already uploaded, it is retracted from the server.

Your history is not swept up at install

Installing the collector classifies what is on your machine but uploads none of it. It tells you how many sessions are waiting and points you at eng-town review, where you can go repo by repo.

AI analysis is a separate decision

Insights sends your transcripts to the Claude API, which is a different thing from storing them in your own database — so it is asked separately, in plain words, and it is off until you say yes. If nobody is at the keyboard — a scripted install, a fleet push — it stays off and un-asked rather than being decided on your behalf. You can change it any time on the Insights tab. Turning it off stops the next run; insights you already have are kept.

Sharing with the team

Your sessions are yours by default. Teammates cannot see them. If you want one to be readable by everyone — because the way you got the agent there is worth copying — the Share control on the transcript makes that one session visible to the team, and you can turn it off again.

What an admin sees

Admins can see each Mac's mode and how many sessions were skipped. They cannot see what was in them — a skipped session never left the machine, so there is nothing to see.

Signing in

A magic link sent to your work email, or Google when it is enabled on the deployment. Your first sign-in creates a team of your own — unless an admin invited your email first, in which case you land on their team. Invite links come from the Admin → Team page.

Two roles

Three layers, not one

1. A database trigger places every new account into a team the moment it is created — a pending invite, or a fresh team of its own.
2. The dashboard checks on every request — so deactivating someone locks them out on their very next click, without waiting for a session to expire.
3. Row-level security is the last line: every query is filtered by the signed-in email inside Postgres. This is the one that actually protects the data.

Deactivating a member does not delete anything. Their sessions stay; they simply cannot sign in.

Devices

A Mac never signs in with Google. It enrols with a short code that its owner claims in the dashboard, and gets a random 256-bit key in return. The server stores only a hash of that key. The key can upload sessions for its owner and nothing else.

An admin can revoke a device. The next time it calls in it is refused and switches itself off. Sessions it already uploaded are kept.

What an admin deliberately cannot do

• Read a teammate's Anthropic key. Enforced by column privileges in Postgres, not by our code being careful about it.
• Turn on AI analysis for someone else. Consent an admin can grant on your behalf is not consent.
• See a session that was never uploaded. Skipped stays on the machine.

The repo allowlist

Admin → Repos decides what is collectible at all. A session in a repo that is not on that list is never uploaded by anyone's Mac. It is the widest control in the product and the first place to look if something you expected is missing.