Metadata-Version: 2.4
Name: sclaude
Version: 0.4.0
Summary: Opinionated Claude Code wrapper: dangerous perms + non-destructive guardrails + auto Haiku handoffs instead of compacting.
Project-URL: Homepage, https://github.com/cartage-ai/sclaude
Project-URL: Repository, https://github.com/cartage-ai/sclaude
Author: Cartage
License: MIT
Requires-Python: >=3.10
Requires-Dist: pexpect>=4.9
Description-Content-Type: text/markdown

# sclaude

Opinionated [Claude Code](https://docs.anthropic.com/claude/docs/claude-code)
wrapper for long-running sessions. A Cartage OSS contribution.

**What it does:**

- Launches `claude` with `--dangerously-skip-permissions` so you never see a
  permission prompt.
- Appends a strict **non-destructive guardrails** system prompt so Claude
  self-imposes the safety checks the permission gate would have enforced.
- Runs a **context-window sidecar**. At ~70% context, it asks Haiku to write a
  handoff doc and **auto-swaps** the session: kills the running `claude`,
  respawns it fresh, and types `/resume <doc>` for you. **No mid-flow
  compacting, no lost state.**
- Bundles a Claude Code **status line** showing context %, 5-hour and 7-day
  usage buckets, and a pace meter.
- Spawns git **worktrees** with `sclaude <name>` — one command, branch + tree
  + wrapped claude.

## Install

```bash
pipx install sclaude
```

Requires Claude Code installed and authed (`claude login`) — sclaude uses your
existing OAuth session, no API key needed.

## Quick start

```bash
# launch claude in current cwd (no worktree)
sclaude run

# spawn a worktree at <repo>/.worktrees/my-feature and launch claude in it
sclaude my-feature
sclaude worktree my-feature           # explicit form

# remove worktrees whose branches are merged / clean
sclaude prune                          # dry run
sclaude prune --apply                  # actually remove
```

Any argument that isn't a known subcommand is treated as a worktree name. So
`sclaude AE-1234` ≡ `sclaude worktree AE-1234`.

## Worktree paths

Default: `<repo>/.worktrees/<name>`. Override with `--path`:

```bash
sclaude my-feature --path ~/scratch/my-feature
```

Branch defaults to the worktree name and forks off the detected default branch
(`origin/main` → `origin/master` → `main` → `master`). Override with
`--branch` / `--base`.

## Context threshold

Default fires at 70% of the 200k context window. Override:

```bash
sclaude --threshold 0.65
```

To disable the PTY auto-swap and fall back to a banner-only handoff:

```bash
sclaude --no-auto-handoff
```

## Status line

On first launch, sclaude composes a settings JSON that points Claude Code's
`statusLine` at the bundled `statusline.sh` (cached at
`~/.cache/sclaude/statusline.sh`). Your existing `~/.claude/settings.json` is
preserved — only the `statusLine` key is added.

The bar shows: context fill % • pace (7d burn-rate vs sustainable) • 5h and 7d
usage buckets when either crosses 50%.

## Guardrails

See [`src/sclaude/guardrails.md`](src/sclaude/guardrails.md). Summary: no
force-push, no destructive git/SQL, no editing CI/secrets, always work in a
worktree, commit per chunk, confirm before irreversible ops.

## Architecture

```
sclaude <name>
├── git worktree add <repo>/.worktrees/<name>
├── spawn watcher.py (subprocess, polls ~/.claude/projects/<cwd>/*.jsonl)
└── pexpect-driven PTY around `claude --dangerously-skip-permissions
                                       --append-system-prompt <guardrails>
                                       --settings <bundled-statusline.json>`
```

When the watcher detects context ≥ threshold, it calls
`claude -p --model haiku` to write a handoff doc under `~/.claude/handoffs/`.
The PTY runner spots the new file, terminates the current `claude`, respawns
it, and pre-types `/resume <doc>` as the first user input.

## Acknowledgements

Built at [Cartage](https://cartage.ai) for our own non-technical AO users
running multi-day Claude Code sessions. Released as a standalone OSS package
in the hope it's useful to anyone else who hates compaction.
