Metadata-Version: 2.4
Name: abstract-claude
Version: 0.1.24
Summary: Fresh Claude Code session manager: settings-only template, durable OAuth, quota fallback wrapper, and a web console.
Author: jrputkey
License: hugpy — Source-Available License
        
        Copyright (c) 2026 putkoff (hugpy.ai). All rights reserved.
        
        Permission is granted, free of charge, to use this software ("hugpy") for
        personal and non-commercial purposes, and for time-limited commercial
        evaluation, subject to the following conditions:
        
        1. Non-commercial use means use by an individual for personal purposes, or
           use by a non-profit or educational institution for its own internal
           purposes. Any use by, for, or on behalf of a for-profit business or in
           connection with revenue-generating activity is commercial use — including
           internal business use, use in producing goods or services, and use on
           paid engagements.
        
        2. Commercial use requires a commercial license from the copyright holder.
           Exception: a business may evaluate the software internally for up to
           thirty (30) days free of charge; continued use after that requires a
           commercial license.
        
        3. Redistribution of this software, in source or binary form, modified or
           unmodified, is not permitted without prior written permission from the
           copyright holder. Downloading the software from an official distribution
           channel (PyPI, npm, hugpy.ai) is not redistribution.
        
        4. Modification for personal use or internal evaluation is permitted;
           distribution of modified versions is not.
        
        5. This notice must be retained in all copies or substantial portions of
           the software.
        
        6. Any use outside these terms automatically terminates this license.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY ARISING
        FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
        IN THE SOFTWARE.
        
        For commercial licensing or redistribution permission: https://hugpy.ai
        
Project-URL: Homepage, https://abstractendeavors.com
Keywords: claude,claude-code,oauth,cli
Classifier: License :: Other/Proprietary License
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 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 in a **brand-new per-session config dir** (`~/.claude-sessions/<stamp>-<pid>`, via `CLAUDE_CONFIG_DIR`), auto-switching to the fallback model when the default is over quota. |
| `sessions [--prune KEEP]` | List per-launch session dirs (LIVE/done); `--prune` removes the oldest finished ones beyond KEEP. |
| `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.
- **Fresh `.claude` per launch.** Every `launch` materializes a new config dir from the
  template (settings + onboarding/trust flags + MCP servers) plus a copy of the freshest
  login, and hands it to Claude Code as `CLAUDE_CONFIG_DIR`. No transcripts, history or
  project trust carry over between sessions; `~/.claude` is only the login holder (the
  refresh-rotated token is synced back to it on each launch). Finished dirs beyond
  `keep_sessions` (default 30) are pruned; live ones never are. Opt out per launch with
  `AC_FRESH=0`, globally with `"fresh_session_per_launch": false` in `config.json`, or
  by pre-setting `CLAUDE_CONFIG_DIR` yourself.
  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 ...`.
