Metadata-Version: 2.4
Name: mind-cli
Version: 0.1.0
Summary: AI project context recovery CLI for Claude Code, Codex, and Cursor
Project-URL: Homepage, https://github.com/matheusbuniotto/mind-cli
Project-URL: Repository, https://github.com/matheusbuniotto/mind-cli
Project-URL: Issues, https://github.com/matheusbuniotto/mind-cli/issues
Project-URL: Documentation, https://github.com/matheusbuniotto/mind-cli#readme
Project-URL: Changelog, https://github.com/matheusbuniotto/mind-cli/releases
Author-email: Matheus Buniotto <matheus.buniotto@gmail.com>
License: MIT
License-File: LICENSE
Keywords: ai,claude-code,cli,codex,context-recovery,cursor,developer-tools,llm,productivity,session-recap
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Version Control
Classifier: Topic :: Text Processing
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: anthropic>=0.40
Requires-Dist: openai>=1.30
Requires-Dist: python-dateutil>=2.9
Requires-Dist: python-dotenv>=1.0
Requires-Dist: pyyaml>=6
Requires-Dist: questionary>=2.0
Requires-Dist: rich>=13
Requires-Dist: typer>=0.12
Description-Content-Type: text/markdown

# mind

`mind` is a frictionless AI project context recovery CLI for Claude Code, Codex, and Cursor.

[![CI](https://img.shields.io/github/actions/workflow/status/matheusbuniotto/mind-cli/ci.yml?branch=main)](https://github.com/matheusbuniotto/mind-cli/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/matheusbuniotto/mind-cli)](https://github.com/matheusbuniotto/mind-cli/releases)

It solves a specific problem: when you switch away from a project for days or weeks, you lose the project’s mental state - what was built, what was decided, what is blocked, and what should happen next. `mind` reconstructs that state in about two minutes with zero manual note-taking.

It is terminal-first, uses a Rich TUI, and is installed as a local tool with `uv tool install`.

## Why People Use It

- restore project context from real session transcripts, not just markdown notes
- recap Claude Code, Codex, and Cursor work in one place
- inspect provenance before any model call
- keep private session data local while still getting a high-signal project brief
- reduce the time it takes to return to a paused AI-assisted project

## What it does

`mind` collects context from:

- Claude Code sessions
- Codex sessions
- Cursor workspace chat history
- recent git history
- uncommitted changes
- open GitHub issues
- project docs like `README.md`, `CLAUDE.md`, `AGENTS.md`
- `.spec/log.md`
- Claude memory files under `~/.claude/projects/.../memory`

It then builds a restore brief that is meant to answer:

1. What is this project trying to do?
2. What is already done?
3. What was in progress when work paused?
4. What should I do next?

## Current status

This repo is the active `mind` CLI.

Implemented today:

- `mind sync <project>` extracts Claude Code and Codex session cards, builds an AI digest, and caches by file hash
- `mind restore <project>` shows the digest plus a deterministic git snapshot
- default sync scope: 2 recent sessions + all compaction summaries + last 5 commits + top 3 GitHub issues
- deterministic git snapshot includes:
  - last 5 commits with hash, message, author, and relative date
  - 10 most recently edited files across recent commits, with line additions/deletions
  - uncommitted change count (use `git status` for the full list)
- config lives at `~/.mind/config.yml`
- API keys come from shell env and/or `~/.mind/.env` (+ optional `<project>/.env`), controlled by `api_key_source`
- provider base URL is configurable for OpenAI-compatible backends

## Install

### One command

```bash
curl -LsSf https://raw.githubusercontent.com/matheusbuniotto/mind-cli/main/install.sh | sh
```

The installer adds `uv` if needed, installs `mind-cli` with `uv tool install`, then prints the next command to run.

### Package managers

```bash
# recommended
uv tool install mind-cli

# alternatives
uvx mind-cli --help
pip install mind-cli
```

```bash
# from source (dev / latest)
git clone https://github.com/matheusbuniotto/mind-cli
uv tool install ./mind-cli
```

```bash
mind init          # first time: config wizard + skill + hooks
# after upgrading mind:
mind install -y    # refresh skill + hooks only
```

### Agent integrations (skill + hook)

`mind` ships a **mind-recap** skill and a **session-start hook** that runs `mind check` (no LLM — only git/session staleness).

| Command | When |
|---------|------|
| `mind init` | First run — config wizard + install skill/hooks |
| `mind install -y` | After `uv tool install` upgrade — refresh skill/hooks only |

```bash
mind install -y               # refresh skill + hook (auto-detect agents)
mind install --skill          # skill only
mind install --hook           # hook only
mind init --no-agents         # config only, skip skill/hooks
```

## Releases

Tagged releases are built and validated in CI, published to PyPI through GitHub trusted publishing, and mirrored to GitHub Releases.
That keeps the install path to one command while still giving the community an auditable place to grab versioned artifacts.

See [`RELEASING.md`](RELEASING.md) for the first-release checklist and the exact commands to cut a public version.

| Agent | Skill path | Hook |
|-------|------------|------|
| Claude Code | `~/.claude/skills/mind-recap/` | `SessionStart` → `~/.claude/hooks/mind-check.sh` |
| Cursor | `~/.cursor/skills/mind-recap/` | `sessionStart` → `~/.cursor/hooks/mind-check.sh` |
| Codex | `~/.codex/skills/` + `~/.agents/skills/` | `SessionStart` → `~/.codex/hooks/mind-check.sh` |

**Without the `mind` CLI** — install the skill from [matheusbuniotto/skills-library](https://github.com/matheusbuniotto/skills-library):

```bash
npx skills add matheusbuniotto/skills-library --skill mind-recap -a claude-code -a cursor -a codex -g -y
```

When the user asks for a recap, the skill runs `mind restore` and asks before `mind sync`.
Hooks nudge on session start when the digest is missing, old, or git/sessions drifted (run `/hooks` in Codex to trust new hooks).

## Usage

### Restore context

```bash
mind restore
mind restore /path/to/project
mind restore --force
mind restore -f
mind restore --inspect
```

`restore` is the main command. If a cached digest exists, it is shown immediately. If not, `mind` performs a sync first.

`--inspect` lists the local files `mind` would read for a digest and shows whether a cached digest exists, **without** calling a model or syncing.

### Sync sessions

```bash
mind sync
mind sync /path/to/project
mind sync --all
mind sync -n 5
mind sync --inspect
```

By default, sync summarizes the 2 most recent sessions, plus all Claude compaction summaries, then regenerates the digest.

`--all` processes every discovered session instead of only the recent subset.

`--inspect` prints the same local file inventory `sync` would use, **without** writing SQLite rows or calling a model.

### Check context freshness (no API)

```bash
mind check
mind check --quiet    # for scripts / hooks
mind check --json
```

### Share a social brief

```bash
mind share --social
mind share --social --no-clip
```

`mind share --social` creates a compact markdown update designed for Slack, Discord, GitHub, or social posts.
It keeps only the high-signal status, next steps, blockers, and a short change summary since the last sync.

### First-run diagnostics

```bash
mind doctor
mind doctor --demo
```

`mind doctor` checks for a configured API key, `git` / `gh`, Claude Code / Codex / Cursor session directories, and your `~/.mind` layout, then prints a single suggested next step.

`--demo` prints a bundled sample restore brief so you can see the output shape before any real project data exists on disk.
## How the project is organized

The main code paths are small and easy to follow:

- `mind/main.py` — thin Typer app wiring
- `mind/commands/` — command handlers split by workflow area
- `mind/cli_helpers.py` — shared CLI root-detection and API-key helpers
- `mind/doctor.py` — first-run environment diagnostics
- `mind/read_sources.py` — local source enumeration for `--inspect` and provenance
- `mind/redact.py` — secret redaction before model calls
- `mind/sync.py` — session discovery, card creation, digest assembly
- `mind/summarizer.py` — AI calls for session cards and restore digests
- `mind/store.py` — SQLite storage for session cards, digests, and notes
- `mind/display.py` — Rich output for restore views and progress
- `mind/adapters/base.py` — shared session adapter contract
- `mind/adapters/registry.py` — built-in adapter registration
- `mind/adapters/claude_code.py` — Claude Code JSONL session parsing
- `mind/adapters/codex.py` — Codex JSONL session parsing
- `mind/adapters/cursor.py` — Cursor workspace storage parsing
- `mind/adapters/project_files.py` — static docs, git snapshot, and GH issue extraction
- `mind/config.py` — config file and environment loading

See `ADAPTERS.md` for the extension contract and the steps to add a new session source.

If you want to contribute, start with [`CONTRIBUTING.md`](CONTRIBUTING.md). It covers local setup, tests, linting, adapter extensions, and a short list of good first issues.

## Configuration

`mind` writes its config to:

```text
~/.mind/config.yml
```

Important rules:

- API keys are never stored in `config.yml`.
- Keys can come from **shell environment variables** and/or **dotenv files**:
  - `~/.mind/.env` (global)
  - `<project>/.env` (merged when `mind` resolves a project path)
- Set `api_key_source` in `~/.mind/config.yml`:
  - `env_first` (default) — shell wins, then dotenv files
  - `dotenv_first` — dotenv files win, then shell
- supported env vars / dotenv keys:
  - `ANTHROPIC_API_KEY`
  - `OPENAI_API_KEY`
  - `MIND_BASE_URL`
  - `MIND_MODEL`

Example:

```bash
export ANTHROPIC_API_KEY=sk-ant-...
# or, for an OpenAI-compatible provider
export OPENAI_API_KEY=sk-or-...
export MIND_BASE_URL=https://openrouter.ai/api/v1
export MIND_MODEL=claude-haiku-4-5-20251001
```

## Data model

`mind` stores local state in SQLite under `~/.mind/mind.db`.

Tables:

- `session_cards` — summarized session artifacts keyed by source and file hash
- `project_digests` — restore briefs for each project cwd
- `project_notes` — manual notes attached to a project

This makes repeated restores cheap: if the underlying session file has not changed, the card can be reused.

## Restore output

`mind restore` combines two layers:

1. **AI digest** — a structured brief built from sessions, docs, notes, and static context
2. **Deterministic git snapshot** — recent commits, recently edited files, dirty-tree count, and GH issues

That split matters because the AI layer restores intent, while the deterministic layer restores facts.

Each restore also prints a short **Sources & trust boundary** section that explains which artifacts came from SQLite, which project files are re-read on sync, and what is recomputed live from `git` / `gh`.
It also calls out the freshness boundary explicitly: the AI digest is cached from the last sync, while the live Git snapshot is recomputed on every restore.
The restore view now also adds a compact **Since last sync** diff and a **Restore Highlights** panel so blockers and next actions are visible before you scroll.

## Trust, privacy, and provenance

**What stays on disk locally**

- Session cards and digests in `~/.mind/mind.db` (see **Data model**).
- Optional API key material in `~/.mind/.env` and/or a project-level `.env` (never in `config.yml`).
- Your agent tools’ own session files under `~/.claude/projects`, `~/.codex/sessions`, and Cursor workspace storage.
- `mind` never writes back into those agent session files.

**What leaves your machine**

- Only the **summarization** and **digest** prompts sent to your configured provider (Anthropic by default, or an OpenAI-compatible `base_url`).
- Before those calls, `mind` applies **best-effort redaction** for common secret patterns (API keys, GitHub tokens, `Bearer` headers, AWS access key ids, PEM private-key headers, etc.). This is not a guarantee against all leaks — treat transcripts like sensitive source code.

**How to verify before you run anything costly**

- `mind sync --inspect` / `mind restore --inspect` — enumerate inputs with no model calls.
- `mind doctor` — confirm tooling and session directories exist.

## Manual notes

```bash
mind note "remember to revisit this API"
mind note
mind note --clean
mind notes
```

`mind note "..."` appends a timestamped project note.
`mind note` opens an interactive menu so you can add a note, view existing notes, or delete selected notes.
`mind note --clean` deletes all notes for the project after confirmation.
`mind notes` prints the current note list.

## Development notes

- Python requirement: `>=3.11`
- CLI entry point: `mind = "mind.main:app"`
- depends on `typer`, `rich`, `anthropic`, `openai`, `pyyaml`, `questionary`

## Practical workflow

1. Work on a project in Claude Code, Codex, or Cursor.
2. Run `mind sync <project>` when you want to capture the current state.
3. Later, run `mind restore <project>` to recover the mental model quickly.

## Project intent

The goal is not to create a generic note-taking system.

The goal is to make project re-entry cheap enough that context loss stops being a real cost.
