Metadata-Version: 2.4
Name: abstract-claude
Version: 0.1.17
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, 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 ...`.
