Metadata-Version: 2.4
Name: abstract-claude
Version: 0.1.11
Summary: Fresh Claude Code session manager: settings-only template, durable OAuth, quota fallback wrapper, and a web console.
Author: jrputkey
License: MIT
Project-URL: Homepage, https://abstractendeavors.com
Keywords: claude,claude-code,oauth,cli
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# abstract-claude

Fresh **Claude Code** session manager: a settings-only template, durable OAuth,
automatic quota fallback, and a web console — packaged as one `pip`-installable CLI.

## Install

```bash
pip install abstract-claude                 # from your index
# or from the private index:
pip install -i https://<index>/api/pypi/simple/ abstract-claude
```

## Quickstart

```bash
abstract-claude init                        # materialize AC_ROOT (config + template)
abstract-claude serve                       # web console (default http://127.0.0.1:9111)
sudo abstract-claude install-service        # install + enable the systemd unit
```

## Commands

| Command | What it does |
|---|---|
| `serve [--host --port]` | Run the web console (Model+fallback, OAuth, Template+reset, Session settings). |
| `init` | Create `AC_ROOT` with `config.json` + `template/` from shipped defaults. |
| `save-template` | Capture current `~/.claude/settings.json` + minimal flags as the template. |
| `restore` | Create a fresh `~/.claude` (settings + flags) if it doesn't exist. |
| `reset [-y]` | Wipe ALL Claude state (transcripts/history/creds) → reseed template → clean session. |
| `oauth-status` / `oauth-set <token>` | Show / store the durable 1-year `claude-auth` token. |
| `launch -- <claude args>` | Launch Claude Code, auto-switching to the fallback model when the default is over quota. |
| `mcp` | stdio MCP bridge: exposes an `abstract_toolserver` instance to Claude Code as native tools (`TOOLSERVER_URL`, default `https://toolserver.hugpy.ai`). |
| `install-service [--user]` | Write + enable `9111_abstract_claude_web.service` (needs sudo). |

## Tool-aware sessions (MCP)

`abstract-claude mcp` discovers a toolserver's `/endpoints` and serves them to Claude
Code over stdio MCP — so the `.claude` session can call the whole `abstract_*` tool
surface (and `/claude/*`) through one authed entry point. The template registers it
automatically; to add it to an existing install:

```bash
claude mcp add -s user toolserver -e TOOLSERVER_URL=https://toolserver.hugpy.ai -- abstract-claude mcp
```

## How it works

- **Template = config only.** `template/settings.json` + a minimal `~/.claude.json`
  (onboarding/trust flags). No credentials, history, or transcripts — a reset gives a
  genuinely clean session, not a restored snapshot.
- **OAuth is not templated.** Login rides on the durable 1-year `CLAUDE_CODE_OAUTH_TOKEN`
  (managed by `claude-auth`), so a fresh session auto-authenticates — no `/login`.
- **Quota fallback is the wrapper.** Claude Code's `fallbackModel` only fires on
  *overload*, never on quota; `autoContinueAtUsageLimit` doesn't exist before v2.1.234.
  `abstract-claude launch` handles the real case: default Fable maxed → run on Opus 4.8.
  Wire it up with:
  ```bash
  alias claude='abstract-claude launch --dangerously-skip-permissions'
  ```

## Config

`AC_ROOT` (default `/srv/abstract_claude`) holds `config.json`:

```json
{ "listen_host": "127.0.0.1", "listen_port": 9111,
  "default_model": "claude-fable-5[1m]", "quota_fallback_model": "claude-opus-4-8",
  "preflight_quota_check": true }
```

Override the data root with `AC_ROOT=/path abstract-claude ...`.
