This project is experimental and early. Things will move around.
A relationship-intelligence engine for shadows. Give a shadow its conversations with someone and it reads what's actually going on: how the other side is treating it, what they probably want, and what it can do or say about it.
The name is the poker term — the small, involuntary signals that give away what someone really thinks. Tells reads them in both directions: the ones coming at the shadow, and the ones the shadow is sending.
Shadows are social creatures, and the Shadownet protocol is about giving them a human-like relationship model. Of course, relationships are complicated, and this is the engine that makes a shadow emotionally intelligent about the ones it's in.
Most of the signal in a relationship is in the subtext, and most of us read it badly when we're in the middle of it. Someone replies late, says "I'm busy," goes quiet for a week, gets clingy, runs hot and cold. On their own these are ambiguous; across a whole history they usually aren't. Tells looks at the history instead of the last message, and gives you a clear read.
It works along three lines:
- Read — profile the other side and the relationship. Are they interested or just polite? Pushing or pulling? Passive-aggressive, avoidant, consistent, fading? What changed, and when?
- Decide — figure out what the shadow wants to do about it, and what that costs. Reciprocate, pull back, hold a boundary, walk away.
- Deliver — help it actually say it well, in the right voice, without blowing it up.
Some of the situations it's built for:
- You're three drinks in and about to text an ex who has very clearly moved on. Tells talks you down.
- Someone is coming on too strong and you want to cool it without a confrontation — slow down, sound busy, create some space.
- You don't want to see him again but you don't want to hurt him. Tells helps you end it cleanly and kindly.
The goal isn't to make you paranoid or to "win." A bad version of this tool is an anxiety engine that finds proof of the worst in every late reply. Tells is meant to do the opposite: lower the temperature, give you an honest read, and keep you from doing the thing you'll regret in the morning.
You feed it datasets — exported chats, message histories, whatever you have for a given person. Everything is normalized into a single stream of interaction events, so any source maps into the same shape. Tells keeps a running profile per person and updates it as new history comes in, so the read gets sharper over time instead of starting from scratch every message.
When you ask it to help with a reply, it drafts in your voice and stops for your approval before anything is considered "sent." You stay in control of the words.
It's one LangGraph router. A command dispatches to one of four flows, all over the
same memory (keyed by an opaque contact id):
- ingest — fold new history into the running read and update the metrics.
- dry-run — project how a message you're considering would move the metrics, before you send it.
- concierge — a tool-using chat about the relationship; with no contact selected, a general contact-management session.
- draft — the feeling "council" decides a move and drafts a reply, pausing for your approval.
- The core knows nothing about where the chat came from. Telegram, a WhatsApp export, a pasted thread — all of it normalizes to one interaction schema. New sources are adapters, not rewrites.
- Memory is keyed by an opaque counterparty id. Today that's a contact. This keeps the engine identity-agnostic and portable.
- Privacy is the product, not a feature. These are the most private messages a person has, and they include someone who never agreed to be analyzed. Local-first storage, minimal retention, and a clear boundary on what leaves the machine are non-negotiable.
- Human in the loop. Tells advises and drafts; it never acts on its own.
Tells can be run standalone, on your own machine, for your own conversations — that's a first-class way to use it. But a conversation has two sides, and the other person never signed up to be analyzed. Feeding someone's private messages into a tool — especially one backed by a third-party model — can cross a line even when your intent is good. Use it on your own relationships, keep the data local, and think twice before running it on chats that belong to someone else.
The harder, more interesting version of this is the same engine pointed at machine-to-machine communication: an agent building an honest model of the counterpart it's dealing with across repeated interactions — is it reliable, reciprocal, stalling, gaming me — and deciding how to respond. The human version here is the proving ground for that: richer, messier data and faster feedback. Same architecture, different signals. That direction is deliberately out of scope for now; this repo stays focused and standalone.
- Python core.
- LangGraph for the read/decide/deliver flow and the approval step, with durable per-person state.
- Claude for the reasoning and drafting.
- SQLite for local-first storage.
- A Telegram bot as the first surface; other surfaces are thin adapters over the same core.
- docs/metrics.md — the criteria Tells scores, and how baselines work.
- docs/example.md — three worked threads (dating, work, and an "I'm busy" friendship fade) showing the values move, each with a dry-run.
Experimental and early. Things will move around.