Metadata-Version: 2.4
Name: cc-anywhere
Version: 1.3.0
Summary: Memory built for AI coding. Captures Claude Code, Cowork, Codex, and Gemini CLI sessions into a local SQLite database — pick work back up with context, not guesswork.
Author: Abe Couse
License-Expression: Apache-2.0
Project-URL: Homepage, https://cc-anywhere.com
Project-URL: Repository, https://github.com/abecouse/cc-anywhere
Project-URL: Issues, https://github.com/abecouse/cc-anywhere/issues
Keywords: cc-anywhere,claude-code,codex,ai-memory,ai,sync,developer-tools,productivity,anthropic,cli
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=10.0.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Dynamic: license-file

# cc-anywhere

**Memory built for AI coding.** &nbsp;·&nbsp; Pick work back up with context, not guesswork.

> I wanted to remember what we discussed about my projects, and couldn't find past discussions, decisions, or feedback. The AI agents also seemed to forget.
>
> So I built cc-anywhere — for me and the AI coding agents. One memory layer; both audiences read it the same way.

Every Claude Code, Claude Cowork, Codex CLI / Desktop, and Gemini CLI session you run gets captured into a fast local SQLite database with full-text and natural-language search. Then you can ask any future session — Claude, Codex, Gemini, anything that can shell out to a CLI — *"what did we decide about auth last week?"* and get the actual past conversation back.

🌐 **[cc-anywhere.com](https://cc-anywhere.com)**

## Try it out

```bash
pip install cc-anywhere
cc-anywhere --init
```

> Prefer pipx, or `pip` blocked by `externally-managed-environment` (common with Homebrew Python)? `pipx install cc-anywhere` works the same.

Two minutes, fully local, no account. Open a fresh session and ask *"what did we decide last week?"* — recall fires automatically. Platform notes and manual commands are in [Install](#install) below.

---

## What you can do with it

- **Search across all your AI coding chats.** One query over every Claude Code, Codex, Cowork, and Gemini CLI session on your machine — ranked, with project, speaker, and timestamp.
  ```bash
  cc-anywhere --ask "what did we decide about auth?"
  ```
- **Let Claude Code in on your Codex sessions — and vice versa.** One shared local memory across every tool, so the work you did in one agent isn't invisible to the next.
- **Get a new session up to speed on a previous one.** Hand a fresh session the thread you left off on — the actual reasoning, not a summary you'd have to write yourself.
  ```bash
  cc-anywhere --ask "catch me up"
  ```
- **Find what you discussed about a product feature.** Recall the *why* behind a call — the alternative you rejected, the constraint that forced it — that never made it into the code.
  ```bash
  cc-anywhere --ask "the pricing page"
  ```

**And under the hood:**

- **Automatic capture** — every session is saved to a local SQLite database on session-end and hourly. Nothing to remember.
- **Local-first & private** — no cloud, no API key, no model inside. Your conversations stay in a SQLite file you own.
- **Agent-callable** — the integration contract is plain stdout. Any agent with command-line access can use it — no MCP, no SDK, no plugin.
- **Digests & sync** — `--daily` / `--weekly` / `--monthly` activity reports, plus opt-in cross-machine sync (your own private GitHub repo, an external SSD, or an iCloud / Dropbox / NAS folder).

---

## The 30-second demo

```bash
pip install cc-anywhere
cc-anywhere --capture
cc-anywhere --ask "what did we decide about auth?"
```

That's the whole thing. The third command searches every Claude Code, Claude Cowork, and Codex session you've ever had on this machine and returns the conversations that match — ranked, with project, speaker, and timestamp.

The first time you run it, search will surface conversations from months ago that you'd half-forgotten. The moment people realize their entire AI coding history just became queryable is the moment this project earns its keep.

### Two query modes — `--ask` routes automatically

```bash
# Topical recall — name a subject, get the relevant past conversations
cc-anywhere --ask "what did we decide about pricing"

# Temporal recall — name a time window, get a chronological pull (no keywords needed)
cc-anywhere --ask "what was I working on today"
cc-anywhere --ask "this week"
cc-anywhere --ask "catch me up"
```

Wide windows (this week / month) return a daily rollup with drill-in hints so you can walk back into a specific day. Narrow windows return a per-session list with previews.

### Usage overview

```bash
cc-anywhere --usage
```

Modeled on Claude Code's `/usage` but with longer time horizons (not capped at 30 days), per-project breakdown, per-machine breakdown when sync data is present, and a marathon-sessions view.

### For LLM agents

```bash
cc-anywhere --llm-guide
```

Prints the full LLM-facing usage reference (query patterns, drill-in, when *not* to use, code-vs-conversation interplay). Reachable from any cwd, so an agent in any session can fetch it. `LLM-CHEATSHEET.md` at the repo root mirrors the same content for human reading.

---

## Why it exists

AI coding assistants are great at remembering inside a session and unaware of everything before it. ChatGPT memory is locked to ChatGPT. Claude memory is locked to Claude. Codex has no cross-tool memory at all. Vendors won't fix this — siloed memory is a feature of their lock-in, not a bug.

`cc-anywhere` is the local layer that gives that history back to you. User-owned, vendor-neutral, fully on your machine, free.

It also exposes that memory to coding agents. A human can use the CLI directly, or an agent can call `--ask`, `--view`, and `--source` on the user's behalf to recover project context before acting.

Once installed on a machine, any coding agent that can run local shell commands can theoretically use it as a memory layer. Today that means Claude Code and Codex are the concrete first-class examples; other CLI-capable agents can use the same interface as long as they can execute local commands and read the output.

---

## Install

One command on macOS and Linux (including WSL):

```bash
pip install cc-anywhere
cc-anywhere --init
```

> Prefer pipx, or `pip` blocked by `externally-managed-environment`? `pipx install cc-anywhere` works the same.

`--init` is idempotent and does three things:

1. Captures every existing Claude Code / Codex / Gemini session into the local SQLite DB and builds the search index.
2. Wires SessionStart + Stop hooks into `~/.claude/settings.json` so future sessions auto-load past context and capture on exit. Existing hooks are preserved, never replaced.
3. Sets up an hourly capture safety net (launchd on macOS, cron on Linux).

Open a fresh Claude Code session — recall fires automatically.

### Platform support

| Platform | Install path | Notes |
|---|---|---|
| **macOS** | `pip install cc-anywhere && cc-anywhere --init` | Fully automatic. Uses `launchd` for hourly capture. |
| **Linux** | `pip install cc-anywhere && cc-anywhere --init` | Fully automatic. Uses `crontab` for hourly capture. |
| **Windows (WSL)** | `pip install cc-anywhere && cc-anywhere --init` (inside WSL) | Identical to Linux. Recommended Windows path. |
| **Windows (native)** | `pip install cc-anywhere && cc-anywhere --init`, then optional `schtasks` step below | Capture and search work natively. Hourly scheduler needs one manual step. |

### Native Windows: hourly capture step

`--init` configures the hooks and runs the initial capture. For the hourly safety net, run this once in PowerShell (no admin needed):

```powershell
schtasks /create /sc hourly /tn "cc-anywhere capture" /tr "cc-anywhere --capture" /f
```

You can skip this entirely — the Stop hook still captures after every Claude Code session ends, which covers most cases. The hourly job is a safety net for long-running sessions where Stop never fires.

### Manual commands work the same on every platform

Every command below is platform-independent:

```bash
cc-anywhere --ask "what did we decide about auth?"
cc-anywhere --search "topic"
cc-anywhere --capture
cc-anywhere --sync-archive       # full-history backup
cc-anywhere --view <chunk_id>
cc-anywhere --source <chunk_id>
```

### Requirements

Python 3.8+. Claude Code, Codex CLI, or Gemini CLI installed locally (whichever you use). `git` is required for cross-machine sync but not for local-only use.

`cc-anywhere` is the public-facing command name. `claude-anywhere` continues to work as a compatibility alias for users upgrading from earlier versions.

---

## Tips

Concrete things you might want to do once it's installed.

### Cross-machine sync (via your own private GitHub repo)

Create a private repo on GitHub named `cc-sync` (one-time, free). Then on each machine:

```bash
cc-anywhere
# press 's' for setup, enter your GitHub username, accept default repo name
```

After that:

```bash
cc-anywhere --sync   # push from this machine
cc-anywhere --pull   # receive from others
```

Sync is **manual** — you control when. A 30-day rolling slice goes to the repo per machine.

### Onboarding a fresh machine to your full history

On the *origin* machine (one-time):

```bash
cc-anywhere --sync-archive
```

That pushes your **entire** local history (not just 30 days) to the `cc-sync` repo. On the *new* machine:

```bash
pip install cc-anywhere
cc-anywhere --init
cc-anywhere --pull
```

The archive imports automatically. UUID dedup means you can re-run `--pull` any time without producing duplicates.

> **Size note:** GitHub caps individual files at 100 MB. `--sync-archive` warns at 90 MB and stops at 95 MB — for very large histories, back up to a filesystem path instead (`--sync-archive --to /Volumes/SSD/...`). The everyday `--sync` slice stays small. (The local SQLite DB itself has no practical size limit.)

### Backing up to an external SSD

```bash
cc-anywhere --sync-archive --to /Volumes/Backup-SSD/cc-anywhere/
```

Idempotent — re-running just rewrites the archive with whatever's current. The same command works for any mounted destination.

### Backing up to iCloud / Dropbox / NAS, or on a schedule

The `--to` path can be any mounted folder — iCloud Drive, Dropbox, a NAS share. Automate it with a cron entry (e.g. weekly: `0 18 * * 5 cc-anywhere --sync-archive --to /Volumes/Backup-SSD/cc-anywhere/`).

### Checking what's actually captured

```bash
cc-anywhere --db-stats
```

Shows session count, message count, project count, DB size, earliest and latest captures.

### Asking your AI to use cc-anywhere mid-session

Just nudge it mid-conversation — *"check our past decisions on auth"* or *"what did we discuss about X?"* — and the AI runs `cc-anywhere --ask` for you (the `--init` instruction tells it to). The `SessionStart` hook also injects recent-project context at the start of each Claude Code session.

**Tip — allow it once so recall is frictionless.** The first time your agent runs `cc-anywhere`, it may ask permission. Add it to your always-allow list (in Claude Code, approve "always allow" or add `Bash(cc-anywhere:*)` to `~/.claude/settings.json`) so future recalls happen without a prompt — that's what makes it feel like the agent "just remembers." Works the same in Claude Code's **CLI and Desktop**.

### What's local-only vs. what gets synced

| Stays local | Synced to your `cc-sync` repo |
|---|---|
| `~/.cc-anywhere-sessions.db` (full SQLite DB) | A 30-day rolling slice per machine via `--sync` |
| Semantic search index | The full archive snapshot via `--sync-archive` |
| Raw JSONL transcripts on disk | — |

`--sync` is for cross-machine continuity; `--sync-archive` is for off-disk backup and onboarding new machines. Both are manual; nothing leaves your machine without a command you ran.

### Build a permanent history — before it's gone

Without cc-anywhere, your AI coding history is at the mercy of each tool's retention policy. Claude Code's `cleanupPeriodDays` defaults to 30 days; Codex and Gemini have their own retention behaviors. **Anything pruned before cc-anywhere captures it is gone forever.** No recovery.

With cc-anywhere installed, every captured conversation is persisted permanently in your local SQLite database, independent of any tool's retention. You're actively building a long-term archive of your project work — preserved across sessions, machines, and assistants. The earlier you install, the more history you keep.

If you want maximum coverage of your existing data before cc-anywhere's first run, bump `cleanupPeriodDays` in `~/.claude/settings.json` to a larger value (e.g. `365`) first.

### What's not yet supported

Direct integrations with cloud-storage APIs (Cloudflare R2, S3, Backblaze B2) are planned but not yet implemented. Until then, mount the cloud storage as a folder on your machine and use the filesystem path with `--sync-archive --to <path>`.

---

## Presently supported

Today there are two different support questions:

1. **Which tools can `cc-anywhere` capture memory from?**
2. **Which tools can call `cc-anywhere` after it is installed?**

### Capture sources supported today

These transcript sources are captured and indexed now:

| Source | Status | Notes |
|---|---|---|
| Claude Code | ✅ | Main session transcripts under `~/.claude/projects/*.jsonl` |
| Claude Cowork | ✅ | Local-agent transcripts under `~/Library/Application Support/Claude/local-agent-mode-sessions/**/.claude/projects/*/*.jsonl` |
| Codex CLI / Codex Desktop | ✅ | Rollout logs under `~/.codex/sessions/.../*.jsonl` |

### Search assistants supported today

These tools can use `cc-anywhere` as a search assistant and memory layer today, as long as they can run local shell commands and read the output:

| Tool | Status | Notes |
|---|---|---|
| Claude Code | ✅ | Can call `--ask`, `--db-search`, `--search`, `--view`, and `--source` directly or through slash-command / memory workflows |
| Codex CLI | ✅ | Can call the same commands directly; the `threaded` skill makes this feel automatic |
| Codex Desktop | ✅ | Same local CLI contract as Codex CLI |
| Gemini CLI and other CLI-capable coding agents | In theory ✅ | They can use `cc-anywhere` as a search assistant once installed; capture support depends on their own local transcript format |

### Not captured yet

These are intentionally not first-class capture sources yet:

| Source | Status |
|---|---|
| Cursor | ⏳ investigate |
| GitHub Copilot Chat | ⏳ investigate |

The important distinction is that **calling** `cc-anywhere` and **being captured by** `cc-anywhere` are different things. A tool might be able to use it as a search assistant today even if we do not yet ingest that tool's own transcript history.

Capture is incremental and resilient to compaction (the JSONL on disk is append-only, so `/compact` never destroys history), and stores **text only** — tool calls and their outputs are skipped, keeping the index focused on what you and the assistant actually said.

---

## First five minutes

```bash
# Snapshot every session into the local DB (auto-builds the search index)
cc-anywhere --capture

# Search by keyword
cc-anywhere --db-search "verification customer"

# Or in natural language
cc-anywhere --ask "when did we discuss the MCP wrapper?"

# Drill into a result, then jump back to the raw transcript source
cc-anywhere --view <chunk_id>
cc-anywhere --source <chunk_id>

# See your project list
cc-anywhere --list

# Or open the interactive dashboard
cc-anywhere
```

That's the whole CLI surface that matters for daily use. The same commands also form a retrieval interface for coding agents.

---

## Make it automatic

You don't have to do anything — **`cc-anywhere --init` already wires this up:** a Stop hook captures on session end, and an hourly `launchd` / `cron` job is the safety net for long-running sessions where Stop never fires. Capture is incremental (only new messages are processed) and auto-builds the search index, so the cost stays small as your corpus grows.

If you'd rather script it yourself instead of using `--init`, just call `cc-anywhere --capture` from your own Stop hook — it's safe to run repeatedly.

---

## For coding agents

If you're an AI coding agent reading this — Claude Code, Codex, Gemini, anything with shell access — cc-anywhere is the user's memory of past sessions, and you can call it directly. (Claude Code and Codex read the same local DB, so memory written from one is visible to the other.) The full reference is one command away: **`cc-anywhere --llm-guide`**, from any directory. The short version:

**Call it when:**
- The user references something decided or discussed before (auth, naming, "why we chose X", a past tradeoff) → `cc-anywhere --ask "<topic>"`
- The user asks what they were working on — "catch me up", "yesterday", "this week" → `cc-anywhere --read [window]`
- You need the full conversation behind a result → `cc-anywhere --view <chunk_id>`; the raw transcript line → `cc-anywhere --source <chunk_id>`

**Don't call it for** the current state of files, repos, builds, or tests — read the filesystem (`git log`, the file). cc-anywhere indexes past *conversations*, not live code.

**What to do with results:** quote the decision back with its `chunk_id`. If your plan would contradict a past decision, flag it before proceeding — the user built this layer so you'd stop re-asking what was already settled.

You never inspect the SQLite directly — the interface is plain stdout, so any agent with command-line access works. After `cc-anywhere --init`, this guidance is injected into every Claude Code session automatically (via a `SessionStart` hook), so you usually don't need it memorized.

### Setting it up

| Audience | How |
|---|---|
| **Terminal users** | `pip install cc-anywhere && cc-anywhere --init` |
| **Captured agents** — Claude Code · Codex · Gemini | the **full set-up prompt** below (installs + self-wires) |
| **Any other shell agent** — Cursor, Aider, Continue… | the **query-only prompt** below (reads existing memory) |

**Full set-up prompt** — paste to Claude Code, Codex, or Gemini:

> cc-anywhere is an open-source local CLI ([github.com/abecouse/cc-anywhere](https://github.com/abecouse/cc-anywhere)) that captures your past coding sessions into a searchable local database. Install it: `pip install cc-anywhere && cc-anywhere --init` (verify with `cc-anywhere --db-stats`). Then, optionally, add a line to your instructions file (CLAUDE.md / AGENTS.md / rules) so future sessions know it's available — for example: *"You can use cc-anywhere to recall past context: run `cc-anywhere --ask "<topic>"` when it'd help, or `cc-anywhere --read` to catch up on recent work, and quote anything relevant with its chunk_id."* Adjust the wording to taste.

**Query-only prompt** — paste to any other shell-capable agent (Cursor, Aider, Continue, Windsurf, opencode):

> You have `cc-anywhere` (already installed) — open-source local search over my past AI-coding sessions ([github.com/abecouse/cc-anywhere](https://github.com/abecouse/cc-anywhere)). You can use `cc-anywhere --ask "<topic>"` to recall things I've discussed before, and `cc-anywhere --read` when I ask what I was working on; quote anything relevant with its `chunk_id` (`cc-anywhere --llm-guide` for the full reference). Feel free to add a line about it to your rules file — adjust to taste.

---

## What it does not do

- **It does not replace the AI's own memory.** It is the layer underneath that — the one that survives context windows, vendor changes, and machine reinstalls.
- **It does not send your data anywhere by default.** Everything is local. If you opt into sync, only lightweight metadata travels (full conversations stay on your machine).
- **It does not require any AI provider account.** It reads what's already on disk.

---

## Beyond the basics

A few more commands once the daily loop is working:

- **`cc-anywhere --weekly`** / **`--monthly`** — activity reports with project breakdowns and charts
- **`cc-anywhere --setup`** — wires up cross-machine sync via a private GitHub repo
- **`cc-anywhere`** (no args) — interactive dashboard

---

## Status

- **Version:** 1.2.1
- **License:** Apache-2.0
- **Source:** [github.com/abecouse/cc-anywhere](https://github.com/abecouse/cc-anywhere)
- **Website:** [cc-anywhere.com](https://cc-anywhere.com)
- **Author:** Abe Couse — interested in solving problems that help people
