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

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

Quickstart

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>`	Delete `~/.claude`, rebuild it from the template + login, run Claude Code (no memory of earlier sessions), 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:

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 — no memory. Every launch DELETES ~/.claude and ~/.claude.json and rebuilds them with only the template settings (or the embedder's AC_SETTINGS_JSON), fresh onboarding/trust flags + MCP servers, and the login (freshest credentials + oauthAccount/userID identity). Transcripts, history, todos, project trust and caches from earlier sessions are gone; the launch cwd is trusted. config.json fresh_session_mode: wipe (default), dir (keep ~/.claude, use a new ~/.claude-sessions/<stamp>-<pid> via CLAUDE_CONFIG_DIR; sessions [--prune] lists), or off. AC_FRESH=0 or a pre-set CLAUDE_CONFIG_DIR skips it for one launch. An explicit --model in the pass-through args is honored as-is (no launcher model, no quota preflight). Wire it up with:
```
alias claude='abstract-claude launch --dangerously-skip-permissions'
```

Config

AC_ROOT (default /srv/abstract_claude) holds config.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 ....

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

abstract_claude-0.1.26.tar.gz (44.9 kB view details)

Uploaded Sep 4, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

abstract_claude-0.1.26-py3-none-any.whl (48.2 kB view details)

Uploaded Sep 4, 2026 Python 3

File details

Details for the file abstract_claude-0.1.26.tar.gz.

File metadata

Download URL: abstract_claude-0.1.26.tar.gz
Upload date: Sep 4, 2026
Size: 44.9 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.13.12

File hashes

Hashes for abstract_claude-0.1.26.tar.gz
Algorithm	Hash digest
SHA256	`ab59a5833b12efbdc26a509a5f8e2c42ad4e64a77ab613f358ad8c80e8668ad2`
MD5	`bc7e98c7911ec565fb3d940e74e91956`
BLAKE2b-256	`c0d4df36e562c55844d0acbd45b20781cf557bf0549605de0a70d512b455fa0d`

See more details on using hashes here.

File details

Details for the file abstract_claude-0.1.26-py3-none-any.whl.

File metadata

Download URL: abstract_claude-0.1.26-py3-none-any.whl
Upload date: Sep 4, 2026
Size: 48.2 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.13.12

File hashes

Hashes for abstract_claude-0.1.26-py3-none-any.whl
Algorithm	Hash digest
SHA256	`d73a4968597f8c178f66207d191476a7f9d89a78e23a35d328fceab4ab85886c`
MD5	`26e7f6beb7d1542885db45a425884acc`
BLAKE2b-256	`afe5a31cc25ad0d8bce8da9c63880dbe8d1583f51faeb94a93098cde4f35110e`