Metadata-Version: 2.4
Name: cc-janitor
Version: 0.3.1
Summary: Tidy up your Claude Code environment — sessions, permissions, context, hooks, schedule.
Project-URL: Homepage, https://github.com/CreatmanCEO/cc-janitor
Project-URL: Issues, https://github.com/CreatmanCEO/cc-janitor/issues
Author-email: Creatman <creatmanick@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: anthropic,claude-code,cli,developer-tools,tui
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console :: Curses
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: croniter>=2
Requires-Dist: platformdirs>=4
Requires-Dist: python-frontmatter>=1.1
Requires-Dist: python-rapidjson>=1.20
Requires-Dist: textual>=0.80
Requires-Dist: tiktoken>=0.7
Requires-Dist: tomlkit>=0.13
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: hypothesis>=6; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest-textual-snapshot>=1; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: watcher
Requires-Dist: psutil>=5.9; extra == 'watcher'
Description-Content-Type: text/markdown

# cc-janitor

Tidy up your Claude Code environment — sessions, permissions, context, hooks.

The first unified TUI/CLI that combines session cleanup, permission pruning,
CLAUDE.md/memory inspection, hook debugging (Phase 2), and scheduled
maintenance (Phase 2) — all the chores no one else automates, in one tool.

**Languages:** English / Русский (toggle with F2 in TUI, `--lang ru` in CLI)

## Stack

- **Language:** Python 3.11+
- **TUI:** [Textual](https://textual.textualize.io/) (terminal UI framework)
- **CLI:** [Typer](https://typer.tiangolo.com/)
- **Token estimation:** OpenAI `tiktoken` (cl100k_base, ~5% off for Claude)
- **Tests:** pytest + pytest-asyncio + pytest-textual-snapshot
- **Distribution:** PyPI via `uv tool` / `pipx`

## Features (Phase 1 MVP)

### Sessions
- List, search, preview Claude Code sessions in `~/.claude/projects/`
- Soft-delete to recoverable trash; restore from trash via `cc-janitor trash restore`
- Inspect compact-summaries and your own indexer markdown summaries

### Permissions
- Discover all rules across global / project, settings.json / .local.json, and `~/.claude.json` approvedTools
- Mark stale rules (no match in last 90 days) by scanning your transcripts
- Dedupe (subsumed/exact) and prune (stale) — with backups before write

### Context inspector
- Walk CLAUDE.md hierarchy, list memory files, list enabled skills
- Compute byte/token cost per file + recurring-per-request total
- Show estimated $ at Opus input rate

## Install

> ⚠️ **v0.1.x is not yet on PyPI.** Install from source until then:

```bash
# Recommended — uv tool from source
uv tool install git+https://github.com/CreatmanCEO/cc-janitor

# Or pipx from source
pipx install git+https://github.com/CreatmanCEO/cc-janitor

# From a local clone for development
git clone https://github.com/CreatmanCEO/cc-janitor && cd cc-janitor
uv sync --all-extras
uv run cc-janitor
```

PyPI publishing arrives once Trusted Publisher is configured on pypi.org. Track via [issue #1](https://github.com/CreatmanCEO/cc-janitor/issues) once filed.

## Quick start

```bash
# Launch TUI
cc-janitor

# CLI: list sessions
cc-janitor session list

# Audit your permission rules
cc-janitor perms audit

# Inspect what your context costs you per request
cc-janitor context cost

# Mutating commands require explicit confirmation:
CC_JANITOR_USER_CONFIRMED=1 cc-janitor session prune --older-than 90d
```

## Safety model

cc-janitor never silently destroys data:

- **`CC_JANITOR_USER_CONFIRMED=1` gate:** every mutating command refuses to run unless this env var is set. Read-only commands (list, show, audit, cost) are always free to call.
- **Soft-delete:** sessions deleted move to `~/.cc-janitor/.trash/<timestamp>/` for 30 days. Restore via `cc-janitor trash restore <id>`.
- **Backups before write:** every settings.json edit creates a timestamped backup in `~/.cc-janitor/backups/<sha-of-path>/`.
- **Audit log:** every mutating action appends a JSONL record to `~/.cc-janitor/audit.log` (rotates at 10 MB).

> **Windows users:** `cc-janitor install-hooks` writes a POSIX shell snippet (`test -f`, `&&`). On native Windows without Git Bash / WSL the hook will fail silently. Cross-platform PowerShell support lands in 0.2.0 (Phase 2). Use Git Bash or WSL in the meantime.

## Using from inside Claude Code

cc-janitor is designed to be invoked by both you (TUI / CLI) and Claude Code itself (CLI), but only on your explicit request. See [docs/CC_USAGE.md](docs/CC_USAGE.md) for the reference Claude Code reads when deciding whether a subcommand is safe to call.

## Roadmap

- [x] **Phase 1** (this release): sessions / permissions / context inspector / CLI / TUI / safety primitives
- [ ] **Phase 2**: memory editor, reinject hook, hook debugger with simulation, scheduler (cron / Task Scheduler)
- [ ] **Phase 3**: monorepo nested .claude/ discovery, auto-reinject watcher, stats dashboard, export/import config

## Contributing

Issues and PRs welcome. See [docs/architecture.md](docs/architecture.md) for the codebase tour.

## License

MIT — see [LICENSE](LICENSE).
