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.
`mct [ws] [--model ID] [--plain]`	Pointer-exchange REPL for the frontier seat: a Claude-Code-style input box pinned to the bottom of the terminal (output scrolls above, status bar below), multi-line input as one prompt (Enter sends; `\`+Enter, Alt+Enter, Ctrl-J or Shift+Enter add a line; pasted blocks stay one prompt); `--plain` = readline line loop. Also deletes `~/.claude` and starts a NEW claude session on every launch (drops the persisted `session.json` id) — same `fresh_session_mode` / `AC_FRESH=0` knobs as `launch`.
`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). abstract-claude mct does the same at REPL start and additionally forgets the persisted session.json id, so A opens a brand-new claude session each launch.
Claude-Code-style input for mct. The prompt box stays at the bottom of the terminal (prompt_toolkit); A's activity and the rendered turn scroll above it and a status bar under it shows spinner · turn · elapsed · pending queries. Multi-line input is one prompt: Enter sends, \+Enter / Alt+Enter / Ctrl-J / Shift+Enter add a line, bracketed paste keeps newlines, first Ctrl-C clears the box. --plain, no TTY, or a missing prompt_toolkit fall back to the readline line loop. Wire it up with:
```
alias claude='abstract-claude launch --dangerously-skip-permissions'
```
A's system prompt is recorded. mct runs A with --system-prompt-snapshot on, so Claude Code writes the FULL system prompt (built-in text + memory + this seat's appended directive) as a prompt_snapshot record in the session transcript (~/.claude/projects/<cwd-slug>/<session>.jsonl). Watch every session on the host live with sysprompt-watch (--once for the current state, --full, --diff). Claude Code reuses the recorded prompt on --resume, so an edited operator-guidance.md applies at the next /new / relaunch (the REPL says so). AC_SYSPROMPT_SNAPSHOT=0 turns the recording off.

Config

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

{ "listen_host": "127.0.0.1", "listen_port": 9111,
  "default_model": "claude-opus-4-8", "quota_fallback_model": "claude-opus-4-8",
  "preflight_quota_check": true }

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

Metadata

Release files for abstract-claude 0.1.55

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for abstract-claude 0.1.55
File	Size	Uploaded
abstract_claude-0.1.55.tar.gz	293.7 kB	Sep 24, 2026	Details

Release files / abstract_claude-0.1.55.tar.gz

Download URL	abstract_claude-0.1.55.tar.gz
Size	293.7 kB
Tags	Source
SHA-256 checksum How to use checksums	`77cc185372196d24b08ee7891b4a767275aaa5816d61de270d881bc9d8ef8289`
BLAKE2b-256 checksum How to use checksums	`db9de2bc64a6e538d8c2d9d0d6f95e72b311983f488f75da2a1a2f115abb965e`
Upload date	Sep 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.13.12`