# Uninstall & clean slate

What tj uninstall removes, what it leaves behind, and the full manual wipe for a true fresh start.

---

`tj uninstall` tears down everything `tj init` set up, then hands you back a one-line hint for removing the Python package. To reset the config and daemon while keeping the package installed, use `tj reset` instead. This page covers what it touches, what it deliberately leaves alone, and how to wipe every last trace by hand when you want a genuine clean slate.

## What `tj uninstall` does

```bash
tj uninstall          # interactive confirmation
tj uninstall --yes    # skip the prompt
```

Running it removes:

- The background daemon (the launchd plist on macOS, the systemd user unit on Linux), stopping `tj serve` first.
- The MCP registration in Claude Code (`claude mcp remove tj --scope user`).
- `~/.tj/`, your telemetry database. **`~/.tj/telemetry.duckdb` holds every span tj has recorded.** Once it's gone the history is gone.
- `~/.config/tj/`, the global config and the onboarded-projects index.
- A local `.tj/` directory, if one exists in the current folder.
- The OTLP env vars tj wrote into `~/.claude/settings.json`, plus the resume-brief hook.
- `OTEL_RESOURCE_ATTRIBUTES` from `.claude/settings.json` in each onboarded project.
- The `# tj harness observability` export block in `~/.zshrc`.

## What it does NOT do

`tj uninstall` intentionally stops short of a few things:

- **The package.** It prints a hint but never runs the uninstall for you. Remove it yourself with `pipx uninstall tokenjam` (or `pip uninstall tokenjam` inside a venv).
- **Codex wiring.** The `[otel]` block tj wrote to `~/.codex/config.toml` is left in place.
- **Sibling data directories.** `~/.config/tokenjam/`, `~/.local/share/tj/`, and `~/.cache/tokenjam/` are not swept.
- **Your Claude Code history.** `~/.claude/projects/` is never touched. That's your real session data, not tj's.

For most people `tj uninstall --yes` followed by `pipx uninstall tokenjam` is enough. Read on only if you want to erase every directory tj might have written.

## Full clean slate

This is the belt-and-suspenders wipe. It removes the daemon, the package, the MCP registration, and every directory tj is known to write.

### 1. Stop and uninstall

```bash
tj stop && tj uninstall --yes
pipx uninstall tokenjam
claude mcp remove tj --scope user
```

`tj stop` halts the daemon (and sweeps any stray foreground `tj serve`) so nothing holds the DuckDB write lock while you delete files. `claude mcp remove` is a safety net. `tj uninstall` already deregisters the MCP server, but running it again is harmless if the entry is gone.

### 2. Remove data directories

```bash
rm -rf ~/.tj              # telemetry DB; ~/.tj/telemetry.duckdb is the easy one to miss
rm -rf ~/.config/tj       # global config + onboarded-projects index
rm -rf ~/.config/tokenjam # export snippets and other tokenjam-named config
rm -rf ~/.local/share/tj  # server state file
rm -rf ~/.cache/tokenjam  # generated reports
```

`~/.tj/telemetry.duckdb` is the one people forget. If you reinstall later and see old sessions you thought you'd deleted, this file survived a previous wipe.

### 3. Check Codex config

If you ever ran `tj init --codex`, open `~/.codex/config.toml` and remove any tj-managed blocks:

- `[otel]`, the telemetry export block tj added.
- `[mcp_servers.tj]`, a legacy MCP registration older versions may have written.

### 4. Remove the daemon unit by hand (if it lingers)

`tj uninstall` handles this, but if you're wiping after a failed install the file may still be there:

```bash
# macOS
rm -f ~/Library/LaunchAgents/com.tokenjam.serve.plist

# Linux
rm -f ~/.config/systemd/user/tokenjam.service
```

## You don't lose your data

Deleting `~/.tj/` removes the telemetry database, not your Claude Code sessions. Those live in `~/.claude/projects/` and tj only ever reads them. After a clean slate you can rebuild your entire cost history with:

```bash
tj init --claude-code
```

Onboarding re-backfills from `~/.claude/projects/`, so the sessions come back. The wipe is safe to run whenever you want a fresh start.