Metadata-Version: 2.4
Name: viberr
Version: 0.2.0
Summary: Lightweight local memory for vibe coding: prompts, edits, conflicts, decisions, AI feedback
Project-URL: Homepage, https://github.com/tanush-em/viberr
Project-URL: Repository, https://github.com/tanush-em/viberr
Project-URL: Issues, https://github.com/tanush-em/viberr/issues
Project-URL: Changelog, https://github.com/tanush-em/viberr/blob/master/CHANGELOG.md
Project-URL: Documentation, https://tanush-em.github.io/viberr
Author-email: Tanush <tanush@viberr.dev>
License-Expression: MIT
License-File: LICENSE
Keywords: agent,ai,cursor,developer-tools,llm,local-first,mcp,vibe-coding
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Version Control
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: gitpython>=3.1.43
Provides-Extra: dev
Requires-Dist: build>=1.2.0; extra == 'dev'
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Requires-Dist: twine>=5.0.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.0; extra == 'docs'
Requires-Dist: mkdocs>=1.5; extra == 'docs'
Requires-Dist: pymdown-extensions>=10.0; extra == 'docs'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Description-Content-Type: text/markdown

# Viberr

**Lightweight local memory for vibe coding.** Cursor hooks write prompts, edits, conflicts, decisions, tool calls, and test outcomes to a single readable log. A small CLI helps you browse, search, recap, and feed that memory back to the AI.

No server. No dashboard. No accounts.

## What it solves

- **Prompt amnesia** — every prompt, response preview, and AI tool call — timestamped
- **File-change provenance** — which prompt caused which edit (with diff, language, hunks)
- **AI vs manual** — edits you make yourself are tagged `source: manual`
- **Conflicting AI edits** — overlapping line ranges from different prompts
- **Decision tracking** — extracts "use X", "never Y" and flags contradictions
- **Session recap** — `viberr recap` → markdown summary of everything that happened
- **Full-text search** — `viberr search "JWT"` across prompts, diffs, and commands
- **Feeding memory back** — `viberr context | pbcopy` → paste into next chat; `viberr rules sync` → auto-update Cursor rules

## Requirements

- Python 3.10+
- Git (a git repo is required — `viberr init` will tell you if one is missing)
- **[Cursor](https://cursor.sh)** IDE with hooks enabled (Settings → Features → Hooks)
  - Minimum Cursor version: any build that ships `hooks.json` support (≥ 0.42)

> **Other editors (experimental):** Adapter stubs for Claude Code, Aider, Cline, and Windsurf
> are included. See [docs/adapters.md](docs/adapters.md) for setup.

## Quick start

```bash
# Recommended: global install via pipx
pipx install viberr

# Or per-project:
pip install viberr

cd your-git-repo
viberr init
```

Use Cursor in that workspace. Events append to `.viberr/events.ndjson` automatically.

## Feeding memory back to the AI

The key workflow viberr enables is a **memory loop**:

```bash
# Before your next chat session — paste into Cursor:
viberr context | pbcopy

# Auto-sync decisions to .cursor/rules/:
viberr rules sync

# Generate AGENTS.md from observed conventions:
viberr agents-md > AGENTS.md
```

## Commands

| Command | Description |
|---------|-------------|
| `viberr init [--editor cursor\|claude-code\|aider]` | Git check, `.viberr/`, merge hooks, `.gitignore` |
| `viberr status` | Active session, branch, today's counts, last test result |
| `viberr log [--format pretty\|json]` | Print events (`--type`, `--tail`, `--since 1h`) |
| `viberr show <id>` | Full event JSON |
| `viberr diff <id>` | Pretty-print diff from an edit event |
| `viberr search <query>` | Search events (`--regex`, `--type`, `--file`, `--since`) |
| `viberr recap [--full] [--include-diffs]` | Markdown session summary |
| `viberr conflicts` | List conflict events |
| `viberr decisions` | List decision events |
| `viberr tail [--type edit]` | Follow the log live |
| `viberr export` | Export session (`--format md\|json\|ndjson`) |
| `viberr doctor` | Verify git, hooks, interpreter path, log size |
| `viberr blame <file>:<line>` | Which prompt last touched this line? |
| `viberr file <path>` | Full timeline for a single file |
| `viberr today` | What did you do today? |
| `viberr stats` | Global numbers + Unicode sparklines |
| `viberr open <id>` | Open file from event in `$EDITOR` |
| `viberr context [--since 7d] [--file src/auth.py]` | Paste-ready memory block |
| `viberr rules sync [--watch]` | Sync decisions to `.cursor/rules/viberr.mdc` |
| `viberr agents-md` | Generate `AGENTS.md` from observed conventions |
| `viberr report [--open]` | HTML dashboard in `.viberr/report.html` |
| `viberr learn [--llm ollama]` | Heuristic distillation → `.viberr/memory.md` |
| `viberr config get\|set <key> <value>` | Read/write config values |
| `viberr prune [--before 30d]` | Remove old events (archives first) |
| `viberr uninstall [--remove-data]` | Remove hooks, optionally data |
| `viberr scrub --check <file>` | Dry-run scrubber on a file |
| `viberr privacy-report` | Report on all redactions in the log |
| `viberr pr-summary` | Generate PR body from current work session |
| `viberr install-git-hook` | Install prepare-commit-msg trailer hook |

## What you'll see in `viberr status`

```
Events file:        /your/project/.viberr/events.ndjson (42 KB)
Total events:       142
Active conversation:sess_a1b2c3
Branch:             feature/auth-refactor (dirty)
Latest work session:work_3 (2 conversation(s))
Last AI activity:   2026-05-20 08:30:11 UTC
Today's prompts:    7
Today's decisions:  3
Open conflicts:     1
Last test run:      pytest PASS (12 passed, 0 failed)
```

## How it works

```mermaid
flowchart LR
    Cursor[Cursor IDE] -->|hooks| Hook[viberr.hook]
    Hook --> Log[".viberr/events.ndjson"]
    Hook --> State[".viberr/state.json"]
    Hook --> Parsers["shell parsers\n(tests/lint/git)"]

    Log --> CLI[viberr CLI]
    Log --> Context["viberr context"]
    Log --> Rules[".cursor/rules/viberr.mdc"]
    Log --> Report[".viberr/report.html"]
    Log --> MCP["viberr-mcp"]

    Context --> Cursor
    Rules --> Cursor
    MCP --> Cursor
```

See [docs/schema.md](docs/schema.md) for the full event format and [docs/how-to-use.md](docs/how-to-use.md) for a complete walkthrough of every command.

## Privacy

All data stays on your machine under `.viberr/`. `viberr init` adds `.viberr/` to `.gitignore`.

**Secret scrubbing is on by default.** Common credential patterns (API keys, tokens, passwords)
are redacted with `[REDACTED]` before reaching disk. See [docs/privacy.md](docs/privacy.md) for full details.

Disable in `.viberr/config.json`:

```json
{ "privacy": { "scrub_secrets": false } }
```

Custom scrub patterns and per-path exclusions:

```json
{
  "privacy": {
    "custom_patterns": ["my-corp-token-[A-Z0-9]{16}"],
    "exclude_paths": [".env", "**/secrets/**"]
  }
}
```

## Configuration

```json
{
  "decisions": { "enabled": true, "scan_responses": false },
  "work_session": { "idle_minutes": 30 },
  "privacy": { "scrub_secrets": true, "custom_patterns": [], "exclude_paths": [] },
  "rules": { "auto_sync": false }
}
```

Or use the CLI:

```bash
viberr config set rules.auto_sync true
viberr config set work_session.idle_minutes 45
```

## MCP server (optional)

```bash
pip install "viberr[mcp]"
```

Add to `~/.cursor/mcp.json`:

```json
{ "mcpServers": { "viberr": { "command": "viberr-mcp" } } }
```

Tools: `get_decisions`, `get_recent_edits`, `get_conflicts`, `search`, `recap`, `context`.

## Development

```bash
pip install -e ".[dev]"
pytest -q
ruff check viberr/ tests/
ruff format --check viberr/ tests/
```

## History

Earlier internal prototypes used a FastAPI daemon, SQLite, and a VS Code extension.
v0.1 stripped all of that back to a zero-dependency, hooks-only design.
v0.2 adds the memory feedback loop: `viberr context`, `viberr rules sync`, `viberr agents-md`,
an MCP server, richer event captures (tool calls, test/lint/git parsing), and a full CLI expansion.

## License

MIT
