hammonda100/ghost-familiar

Twin is a program that runs quietly on your own computer and tries to build a personality profile of you based on how you already work, then shows that profile back to you as a kind of ambient companion in your browser. Everything happens locally: there is no cloud service involved, no Docker setup required, and it installs as a plain Python package. It can automatically use a locally running AI model through Ollama, or fall back to OpenAI or Anthropic if you provide an API key. After installing it with pip and running a start command, twin opens a small web page on your machine and walks you through a short setup wizard. You point it at a folder of notes, such as an Obsidian vault, choose which AI model to use, and decide whether to allow optional screen observation, which is turned off unless you explicitly enable it. Once set up, the program analyzes your notes, your browser history, your git commit activity, and any AI chat exports you have saved, using all of that to build what it calls a personality model. That model scores you across six trait pairs, things like calm versus restless or methodical versus exploratory, based on patterns in your notes, browsing, and code. The result feeds two things: a chat feature that answers questions using your own notes and recent activity as context, and a live visual animation on screen, chosen from eight different styles, that shifts based on how active you currently are. All of this data is stored locally in a hidden folder on your machine, using a small SQLite database for structured events and a vector database for semantic search over your notes. The project's own documentation describes the design as privacy focused by default, since the more invasive screen observation feature requires an explicit opt in and nothing leaves your device. The codebase is organized into clear pieces: a command line interface, the core web server, database and vector storage code, the first run analysis logic, connectors for reading external sources like your browser or notes, and the personality scoring and visual rendering logic.