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.

Part of the hugpy orbit

                    ┌──────────────────────────── hugpy (fleet) ───────────────────────────┐
                    │ central + workers: platform · engine · fleet · server · media · …     │
                    │ OpenAI-compatible /v1 — every local model, incl. B (Qwen3-Coder-Next) │
                    └───────▲───────────────────────▲──────────────────────────▲───────────┘
                            │ inference             │ inference                │ B reductions
   ┌────────────────────────┴──┐   ┌────────────────┴──────────┐   ┌───────────┴───────────────┐
   │ hugpy-station             │   │ hugpy-agent               │   │ abstract-toolserver       │
   │ desktop + headless console│──▶│ agent runtime · TUI ·     │◀─▶│ comms · ledgers · boards ·│
   │ tmux seats per locus      │   │ OpenCode/qwen seats       │   │ exchanges · MCP · b_ask   │
   └────────────┬──────────────┘   └────────────┬──────────────┘   └───────────▲───────────────┘
                │ keeper/codex seats            │ --serve                      │ tools (MCP/HTTP)
   ┌────────────▼──────────────┐   ┌────────────▼──────────────┐               │
   │ abstract-gpt (Codex seat) │   │ abstract-claude serve ────┼───────────────┘
   │ abstract-claude (Claude)  │   │  └ abstract-serve-core    │
   └───────────────────────────┘   └───────────────────────────┘
          everything ships through abstract-pypit → PyPI (+ GitHub)

Package	Role	PyPI
hugpy (14 lockstep dists)	the self-hosted LLM fleet: central, workers, engine, media, server	hugpy
hugpy-station	Electron desktop + headless backend; tmux seats, prompt composer, loop/bug scan	deb via central install links
hugpy-agent	agent runtime on the fleet; `hugpy-agent tui`, the provider-neutral terminal client over the shared Serve API (`abstract-claude` / `abstract-gpt` / `hugpy-agent serve`)	hugpy-agent
abstract-claude	Claude Code launch/session/rollover + `abstract-claude serve` (roles keeper/chat/worker/local)	abstract-claude
abstract-serve-core	the HTTP routes `abstract-claude serve` actually runs (queue, relay, rollover sweeps)	abstract-serve-core
abstract-gpt	Codex/ChatGPT seat counterpart of abstract-claude	abstract-gpt
abstract-toolserver	one tool service per host: comms, ledgers, boards, exchanges, MCP bridge, B on call	abstract-toolserver
abstract-pypit	one-command publisher: bump → build → PyPI → GitHub push	abstract-pypit

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 ....

Serve, roles and launch (0.1.68 – 0.1.96)

abstract-claude serve runs abstract-serve-core's routes; the routes in abstract_claude/server.py are not used at serve runtime. See the serve-core README for roles, relay, queue and interrupt behaviour.
Launch contract: session-first launch, managed rollover (handoff → /clear → resume through the toolserver ledger), TUI harness, and a reuse gate before an existing session is attached.
Also here: seat-report sidecar, rollover.py / terminal_rollover.py, keepalive, mct_repl (pointer exchange), models.py / pricing.py, usage_db, exchange_hook.
The abstract_claude.toolset module adds the /claude/* category (claude_oauth_*, claude_state, claude_set_model, …) to abstract-toolserver when both are installed.

Attention-worthy

Versions are bumped by abstract-pypit on publish; don't hand-edit them.
Same-version republish needs pip install --force-reinstall.

Metadata

Release files for abstract-claude 0.1.105

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.105
File	Size	Uploaded
abstract_claude-0.1.105.tar.gz	79.2 kB	Oct 7, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for abstract-claude 0.1.105
File	Interpreter	ABI	Platform	Reset
abstract_claude-0.1.105-py3-none-any.whl 55.3 kB Oct 7, 2026	Python 3	none	any	Details

Total release size: 134.5 kB

Release files / abstract_claude-0.1.105.tar.gz

Download URL	abstract_claude-0.1.105.tar.gz
Size	79.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`f5ca1ecd96c5423bb80d3045bb8486234c28a0d327aa5c325411fa5be14be918`
BLAKE2b-256 checksum How to use checksums	`77626a56c341a813e00451c625afd25767e004c225566e62a8ce16b212341d75`
Upload date	Oct 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.3`

Release files / abstract_claude-0.1.105-py3-none-any.whl

Download URL	abstract_claude-0.1.105-py3-none-any.whl
Size	55.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`481dd466e7e9db51f9d0d1a3bfc3eee1142baf22c75c423085bda722a8b2afec`
BLAKE2b-256 checksum How to use checksums	`ea7708b7af5b94883463f82cdfb2b4c48a837effae0539851fa5c5bf5a6d73b0`
Upload date	Oct 7, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.3`