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>`	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:

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:
```
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.24.tar.gz (43.1 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.24-py3-none-any.whl (46.3 kB view details)

Uploaded Sep 4, 2026 Python 3

File details

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

File metadata

Download URL: abstract_claude-0.1.24.tar.gz
Upload date: Sep 4, 2026
Size: 43.1 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.24.tar.gz
Algorithm	Hash digest
SHA256	`f5747f7f715810b3bc15a4cf53b94a026b48ad8667b775ce31831c4b837d6caa`
MD5	`f894b7fdc46560ffd7223e9c6dc161eb`
BLAKE2b-256	`489fe7a012d003eec612fd9143cb79b4f6509ed5c909d013035d697b0d2d4a21`

See more details on using hashes here.

File details

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

File metadata

Download URL: abstract_claude-0.1.24-py3-none-any.whl
Upload date: Sep 4, 2026
Size: 46.3 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.24-py3-none-any.whl
Algorithm	Hash digest
SHA256	`d6700e6d8a275cae9a2459375462fa6928b02302ff078900bab62708fbc6a2b5`
MD5	`ded6c6bccae3d12e7faf7a133fa9d01a`
BLAKE2b-256	`1ef1eee24f490a55dcb667a6587c50294cef0fd3b5a494a9a3dd1e6cbaf59921`