agent-persona 0.1.0__tar.gz

agent_persona-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*.pyo
+.venv/
+venv/
+.env
+*.egg-info/
+dist/
+build/
+.coverage
+htmlcov/
+.pytest_cache/
+.DS_Store
+*.tmp
+*.bak

agent_persona-0.1.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: agent-persona
+Version: 0.1.0
+Summary: Local-first personalization layer for Claude CLI — learns how you work and injects that context into every session
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: filelock>=3.12
+Requires-Dist: questionary>=2.0
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<img src="assets/logo.svg" width="100" alt="agent-persona logo" />
+
+# agent-persona
+
+*Personalise your Claude CLI to your persona — learned from how you actually work.*
+
+[![PyPI](https://img.shields.io/pypi/v/agent-persona?color=blue&label=pypi)](https://pypi.org/project/agent-persona/)
+[![Python](https://img.shields.io/badge/python-3.11+-blue)](#)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](#)
+[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey)](#)
+
+</div>
+
+---
+
+Claude is powerful out of the box. But it doesn't know *you*. It doesn't know your preferred stack, your coding style, or that you always want root-cause analysis before a fix. Every session, you're a stranger.
+
+**agent-persona changes that.** It reads your Claude session logs, the files you edit, and your shell history — builds a global profile of your persona on this machine — and silently injects that context into every Claude session from then on. Claude stops being a generic assistant and starts behaving like one that knows how you work.
+
+No configuration. No manual writing. It learns from what you do.
+
+---
+
+## Install
+
+```bash
+pipx install agent-persona
+agent-persona install
+```
+
+From the next session on, it's building your persona.
+
+---
+
+## How your persona is built
+
+agent-persona watches four things:
+
+| Source | What it captures |
+|---|---|
+| **Claude session logs** | Parsed from `~/.claude/` after each session ends |
+| **Files you edit** | Every `Write` / `Edit` in Claude CLI is logged asynchronously |
+| **Shell history** | Read from `~/.zsh_history` or `~/.bash_history` at analysis time |
+| **Your own words** | Phrases like `"I prefer..."`, `"always use..."`, `"never do..."` extracted from your side of every conversation |
+
+From those sources, it builds a profile across five dimensions:
+
+- **Languages** — which languages you actually use, weighted by frequency across sessions
+- **Frameworks** — inferred from imports, file extensions, and install commands
+- **Tools** — CLI tools, build systems, databases that appear repeatedly in your workflow
+- **Preferences** — explicit things you've told Claude, confidence-scored and time-decayed so stale preferences fade out
+- **Coding style** — indent preference from your actual files; test frequency from how often you write tests
+
+Everything is stored in `~/.agent-persona/profile.json` — plain JSON, readable, portable, yours.
+
+---
+
+## How it gets into Claude
+
+Three hooks wire into `~/.claude/settings.json`:
+
+**`SessionStart`** — injects your compiled persona as hidden context before you type a word. Claude already knows how you work.
+
+**`Stop` (×2)** — when a session ends:
+- A command hook runs the full rule-based pipeline, updates `profile.json`, regenerates `context.md`
+- A prompt hook gives the already-running Claude instance a free richer pass — no extra API calls, no extra cost
+
+**`PostToolUse`** — every file edit is logged asynchronously in the background. Never blocks your session.
+
+---
+
+## Your profile, globally
+
+The profile lives at `~/.agent-persona/` — not inside any project. It spans every Claude session on this machine, regardless of what you're working on.
+
+```
+~/.agent-persona/
+├── profile.json              # your persona — single source of truth
+├── state.json                # tracks which sessions have been processed
+├── history/
+│   └── files_edited.jsonl    # rolling 90-day log of edited files
+└── generated/
+    └── context.md            # compiled persona injected at session start
+```
+
+`profile.json` is plain JSON — readable, portable, auditable:
+
+```json
+{
+  "version": 1,
+  "stack": {
+    "languages":  { "python": 45, "typescript": 30 },
+    "frameworks": { "fastapi": 20, "pytest": 18 },
+    "tools":      { "docker": 15, "git": 50 }
+  },
+  "preferences": [
+    { "text": "root-cause analysis before fixes", "confidence": 0.9,  "source": "rule" },
+    { "text": "always include tradeoffs",          "confidence": 0.95, "source": "llm"  }
+  ],
+  "coding_style": { "indent": "spaces", "indent_size": 4, "test_frequency": "high" },
+  "sessions_processed": 47
+}
+```
+
+---
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `agent-persona install` | Register hooks, create `~/.agent-persona/` |
+| `agent-persona uninstall` | Remove hooks, leave profile intact |
+| `agent-persona customize` | Interactively set what Claude should know about you and how to respond |
+| `agent-persona status` | Show your current persona: stack, preferences, sessions processed |
+| `agent-persona analyze` | Re-run analysis on demand |
+| `agent-persona apply [--dry-run]` | Write persona into `~/.claude/CLAUDE.md` as a static fallback |
+| `agent-persona export [path]` | Export your profile to take to another machine |
+| `agent-persona import [path]` | Merge an exported profile into this machine's profile |
+| `agent-persona reset --confirm` | Wipe profile and start fresh |
+| `agent-persona doctor` | Check install health |
+
+---
+
+## Taking your persona to a new machine
+
+```bash
+# old machine
+agent-persona export ~/persona.json
+
+# new machine
+agent-persona install
+agent-persona import ~/persona.json
+```
+
+The profiles merge — nothing is lost from either machine.
+
+---
+
+## Design decisions
+
+**No LLM API calls from Python.** All rule-based analysis runs in pure Python — fast, deterministic, free. The richer LLM extraction piggybacks on the Claude session that's already ending via a `type: "prompt"` Stop hook. Zero extra cost.
+
+**Preferences decay.** Each preference carries a `last_seen` timestamp. Old ones fade: `score × 0.9 ^ (days_since_seen / 30)`. What you get stays relevant to how you work *now*.
+
+**Crash-safe writes.** Every write is atomic (`write to .tmp → rename`). A crashed Stop hook is caught up automatically on the next clean session.
+
+**Non-destructive CLAUDE.md injection.** The `apply` command writes between `AGENT-PERSONA:START` and `AGENT-PERSONA:END` markers. Everything outside is untouched.
+
+**Sensitive data never stored.** API keys, tokens, and passwords are stripped before anything reaches `profile.json`. Only file metadata is logged — never file contents.
+
+---
+
+## What it doesn't do
+
+- No cloud — your persona never leaves this machine unless you export it
+- No per-project profiles in v1 — one global persona across all work
+- No Fish shell history yet
+
+---
+
+## Requirements
+
+- Python 3.11+
+- [Claude CLI](https://claude.ai/code) installed and authenticated
+- macOS, Linux, or Windows
+
+---
+
+## License
+
+MIT

agent_persona-0.1.0/README.md

@@ -0,0 +1,173 @@
+<div align="center">
+
+<img src="assets/logo.svg" width="100" alt="agent-persona logo" />
+
+# agent-persona
+
+*Personalise your Claude CLI to your persona — learned from how you actually work.*
+
+[![PyPI](https://img.shields.io/pypi/v/agent-persona?color=blue&label=pypi)](https://pypi.org/project/agent-persona/)
+[![Python](https://img.shields.io/badge/python-3.11+-blue)](#)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](#)
+[![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey)](#)
+
+</div>
+
+---
+
+Claude is powerful out of the box. But it doesn't know *you*. It doesn't know your preferred stack, your coding style, or that you always want root-cause analysis before a fix. Every session, you're a stranger.
+
+**agent-persona changes that.** It reads your Claude session logs, the files you edit, and your shell history — builds a global profile of your persona on this machine — and silently injects that context into every Claude session from then on. Claude stops being a generic assistant and starts behaving like one that knows how you work.
+
+No configuration. No manual writing. It learns from what you do.
+
+---
+
+## Install
+
+```bash
+pipx install agent-persona
+agent-persona install
+```
+
+From the next session on, it's building your persona.
+
+---
+
+## How your persona is built
+
+agent-persona watches four things:
+
+| Source | What it captures |
+|---|---|
+| **Claude session logs** | Parsed from `~/.claude/` after each session ends |
+| **Files you edit** | Every `Write` / `Edit` in Claude CLI is logged asynchronously |
+| **Shell history** | Read from `~/.zsh_history` or `~/.bash_history` at analysis time |
+| **Your own words** | Phrases like `"I prefer..."`, `"always use..."`, `"never do..."` extracted from your side of every conversation |
+
+From those sources, it builds a profile across five dimensions:
+
+- **Languages** — which languages you actually use, weighted by frequency across sessions
+- **Frameworks** — inferred from imports, file extensions, and install commands
+- **Tools** — CLI tools, build systems, databases that appear repeatedly in your workflow
+- **Preferences** — explicit things you've told Claude, confidence-scored and time-decayed so stale preferences fade out
+- **Coding style** — indent preference from your actual files; test frequency from how often you write tests
+
+Everything is stored in `~/.agent-persona/profile.json` — plain JSON, readable, portable, yours.
+
+---
+
+## How it gets into Claude
+
+Three hooks wire into `~/.claude/settings.json`:
+
+**`SessionStart`** — injects your compiled persona as hidden context before you type a word. Claude already knows how you work.
+
+**`Stop` (×2)** — when a session ends:
+- A command hook runs the full rule-based pipeline, updates `profile.json`, regenerates `context.md`
+- A prompt hook gives the already-running Claude instance a free richer pass — no extra API calls, no extra cost
+
+**`PostToolUse`** — every file edit is logged asynchronously in the background. Never blocks your session.
+
+---
+
+## Your profile, globally
+
+The profile lives at `~/.agent-persona/` — not inside any project. It spans every Claude session on this machine, regardless of what you're working on.
+
+```
+~/.agent-persona/
+├── profile.json              # your persona — single source of truth
+├── state.json                # tracks which sessions have been processed
+├── history/
+│   └── files_edited.jsonl    # rolling 90-day log of edited files
+└── generated/
+    └── context.md            # compiled persona injected at session start
+```
+
+`profile.json` is plain JSON — readable, portable, auditable:
+
+```json
+{
+  "version": 1,
+  "stack": {
+    "languages":  { "python": 45, "typescript": 30 },
+    "frameworks": { "fastapi": 20, "pytest": 18 },
+    "tools":      { "docker": 15, "git": 50 }
+  },
+  "preferences": [
+    { "text": "root-cause analysis before fixes", "confidence": 0.9,  "source": "rule" },
+    { "text": "always include tradeoffs",          "confidence": 0.95, "source": "llm"  }
+  ],
+  "coding_style": { "indent": "spaces", "indent_size": 4, "test_frequency": "high" },
+  "sessions_processed": 47
+}
+```
+
+---
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `agent-persona install` | Register hooks, create `~/.agent-persona/` |
+| `agent-persona uninstall` | Remove hooks, leave profile intact |
+| `agent-persona customize` | Interactively set what Claude should know about you and how to respond |
+| `agent-persona status` | Show your current persona: stack, preferences, sessions processed |
+| `agent-persona analyze` | Re-run analysis on demand |
+| `agent-persona apply [--dry-run]` | Write persona into `~/.claude/CLAUDE.md` as a static fallback |
+| `agent-persona export [path]` | Export your profile to take to another machine |
+| `agent-persona import [path]` | Merge an exported profile into this machine's profile |
+| `agent-persona reset --confirm` | Wipe profile and start fresh |
+| `agent-persona doctor` | Check install health |
+
+---
+
+## Taking your persona to a new machine
+
+```bash
+# old machine
+agent-persona export ~/persona.json
+
+# new machine
+agent-persona install
+agent-persona import ~/persona.json
+```
+
+The profiles merge — nothing is lost from either machine.
+
+---
+
+## Design decisions
+
+**No LLM API calls from Python.** All rule-based analysis runs in pure Python — fast, deterministic, free. The richer LLM extraction piggybacks on the Claude session that's already ending via a `type: "prompt"` Stop hook. Zero extra cost.
+
+**Preferences decay.** Each preference carries a `last_seen` timestamp. Old ones fade: `score × 0.9 ^ (days_since_seen / 30)`. What you get stays relevant to how you work *now*.
+
+**Crash-safe writes.** Every write is atomic (`write to .tmp → rename`). A crashed Stop hook is caught up automatically on the next clean session.
+
+**Non-destructive CLAUDE.md injection.** The `apply` command writes between `AGENT-PERSONA:START` and `AGENT-PERSONA:END` markers. Everything outside is untouched.
+
+**Sensitive data never stored.** API keys, tokens, and passwords are stripped before anything reaches `profile.json`. Only file metadata is logged — never file contents.
+
+---
+
+## What it doesn't do
+
+- No cloud — your persona never leaves this machine unless you export it
+- No per-project profiles in v1 — one global persona across all work
+- No Fish shell history yet
+
+---
+
+## Requirements
+
+- Python 3.11+
+- [Claude CLI](https://claude.ai/code) installed and authenticated
+- macOS, Linux, or Windows
+
+---
+
+## License
+
+MIT

agent_persona-0.1.0/assets/logo.svg

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 120 120" width="120" height="120">
+  <circle cx="60" cy="60" r="54" fill="none" stroke="#E6EDF3" stroke-width="3"/>
+  <circle cx="60" cy="46" r="18" fill="#E6EDF3"/>
+  <ellipse cx="60" cy="88" rx="26" ry="20" fill="#E6EDF3"/>
+  <circle cx="60" cy="46" r="6"  fill="none" stroke="#0D1117" stroke-width="1.8"/>
+  <circle cx="60" cy="46" r="10" fill="none" stroke="#0D1117" stroke-width="1.4"/>
+  <circle cx="60" cy="46" r="14" fill="none" stroke="#0D1117" stroke-width="1"/>
+  <circle cx="94" cy="26" r="4" fill="#58A6FF"/>
+</svg>

agent_persona-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agent-persona"
+version = "0.1.0"
+description = "Local-first personalization layer for Claude CLI — learns how you work and injects that context into every session"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+dependencies = [
+    "click>=8.1",
+    "rich>=13.0",
+    "filelock>=3.12",
+    "questionary>=2.0",
+]
+
+[project.scripts]
+agent-persona = "agent_persona.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agent_persona"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.coverage.run]
+source = ["agent_persona"]
+omit = ["tests/*"]
+
+[tool.coverage.report]
+fail_under = 80
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+]

agent_persona-0.1.0/src/agent_persona/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

agent_persona-0.1.0/src/agent_persona/analyzers/preference_extractor.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from agent_persona.collectors.explicit_feedback import extract_preferences
+from agent_persona.models import Preference
+
+_MAX_PREFERENCES = 20
+
+
+def extract_all_preferences(
+    user_messages: list[str],
+    now: str,
+) -> tuple[Preference, ...]:
+    raw = extract_preferences(user_messages, now)
+    seen: dict[str, Preference] = {}
+    for pref in raw:
+        key = pref.text.lower().strip()
+        if key not in seen:
+            seen[key] = pref
+
+    deduped = list(seen.values())
+    deduped.sort(key=lambda p: p.confidence, reverse=True)
+    return tuple(deduped[:_MAX_PREFERENCES])

agent_persona-0.1.0/src/agent_persona/analyzers/stack_detector.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+LANGUAGE_SIGNALS: dict[str, set[str]] = {
+    "python": {".py", "pip", "uv ", "poetry", "pytest", "python3", "python "},
+    "typescript": {".ts", ".tsx", "tsc ", "ts-node"},
+    "javascript": {".js", ".mjs", "node ", "nodemon"},
+    "go": {".go", "go build", "go test", "go run"},
+    "rust": {".rs", "cargo build", "cargo test"},
+    "java": {".java", "mvn ", "gradle "},
+    "ruby": {".rb", "bundle exec", "rails "},
+    "bash": {".sh", "#!/bin/bash", "#!/bin/zsh"},
+}
+
+FRAMEWORK_SIGNALS: dict[str, set[str]] = {
+    "react": {"useState", "useEffect", ".jsx", ".tsx", "import React", "react-dom"},
+    "fastapi": {"fastapi", "from fastapi", "uvicorn"},
+    "django": {"django", "manage.py", "django.db"},
+    "express": {"express()", "app.get(", "app.post("},
+    "nextjs": {"next/router", "getServerSideProps", "next.config"},
+    "vue": {".vue", "createApp(", "defineComponent"},
+}
+
+TOOL_SIGNALS: dict[str, set[str]] = {
+    "docker": {"dockerfile", "docker-compose", "docker build", "docker run"},
+    "git": {"git commit", "git push", "git pull", "git merge"},
+    "npm": {"npm install", "npm run", "npm ci"},
+    "yarn": {"yarn add", "yarn install", "yarn run"},
+    "pnpm": {"pnpm add", "pnpm install"},
+    "mysql": {".sql", "mysql ", "create table", "select * from"},
+    "mongo": {"mongodb", "mongoose", "db.collection"},
+    "postgres": {"psql ", "pg_dump", "postgresql"},
+    "redis": {"redis-cli", "redis.Redis("},
+    "aws": {"aws s3", "aws ec2", "boto3", "aws lambda"},
+}
+
+
+def detect_stack(
+    tool_signals: list[str],
+    commands: list[str],
+    extensions: dict[str, int],
+) -> dict[str, dict[str, int]]:
+    all_text = tool_signals + commands
+    ext_text = [f".{ext}" for ext, count in extensions.items() for _ in range(count)]
+    combined = all_text + ext_text
+
+    languages = _score_category(LANGUAGE_SIGNALS, combined)
+    frameworks = _score_category(FRAMEWORK_SIGNALS, combined)
+    tools = _score_category(TOOL_SIGNALS, combined)
+
+    return {"languages": languages, "frameworks": frameworks, "tools": tools}
+
+
+def _score_category(
+    signal_map: dict[str, set[str]],
+    corpus: list[str],
+) -> dict[str, int]:
+    scores: dict[str, int] = {}
+    corpus_lower = [item.lower() for item in corpus]
+
+    for name, signals in signal_map.items():
+        total = 0
+        for signal in signals:
+            sig_lower = signal.lower()
+            matches = sum(1 for item in corpus_lower if sig_lower in item)
+            total += min(matches, 5)
+        if total > 0:
+            scores[name] = total
+
+    return scores

agent_persona-0.1.0/src/agent_persona/analyzers/style_detector.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from agent_persona.models import CodingStyle
+
+
+def detect_style(file_signals: dict) -> CodingStyle:
+    indent = file_signals.get("indent", "unknown")
+    indent_size = file_signals.get("indent_size", 4)
+    test_file_count = file_signals.get("test_file_count", 0)
+    total_file_count = file_signals.get("total_file_count", 0)
+
+    ratio = test_file_count / max(total_file_count, 1)
+    if ratio > 0.25:
+        test_frequency = "high"
+    elif ratio > 0.10:
+        test_frequency = "medium"
+    elif ratio > 0:
+        test_frequency = "low"
+    else:
+        test_frequency = "unknown"
+
+    return CodingStyle(
+        indent=indent,
+        indent_size=indent_size,
+        test_frequency=test_frequency,
+    )